Vignette Request of Integer representation

[Andrea-Havron-NOAA]

This Discussion stems around the desire to have a vignette to explain "integer representation" and how it is used in FIMS instead of using a file/list of control options to control what pieces of FIMS get used in a given model run. Quickly, integer representation in FIMS refers to how users create multiple individual modules which are each tracked with a unique integer, identifier, pointer, etc. and those modules are put together to build a model. Using a vignette to explain this idea to users, especially now that the wrapper functions for the input are available, would help document what we are doing and make this information more accessible.

The list below will be continually edited as new ideas are generated in the comments.

• Define what integer representation is
• Give an example of how a power user can interact with a module
• Give an example of how a module can be set up for a new user
• Compare how other assessment platforms build models instead of using integer representation
• Provide unified modeling language (UML) graphs where helpful
• Show some cons to using integer representation
• Highlight the benefits of using integer representation in FIMS
  • eliminates need for conditional statements in the codebase
  • does not require an integer list as user input to determine which modules to use

[msupernaw]

I've been trying to think of a way to represent this in a vignette. At the moment, I think a UML graph would be best, what are your thoughts?

[Andrea-Havron-NOAA]

Vignette also needs to capture the big picture design benefits of this approach, such as:

• eliminates need for conditional statements in the codebase
• does not require an integer list as user input to determine which modules to use

[nathanvaughan-NOAA]

I think the scalability of user knowledge is also an important selling point. With SS3 a new user gets hit with everything in the control/data files where as you could show them how to set up a simple FIMS model and they wouldn't even have to know that other options exist. In SS3 the approach is usually that someone reuses existing model files with lots of settings that they don't understand often leading to errors.

[k-doering-NOAA]

I would love to see more UML graphs (where they are helpful) for FIMS!

An aside: I think this vignette also needs to explain what "integer representation" means - my brain does not intuitively understand and it sounds highly technical. Or, alternatively, come up with a clearer title for this vignette.

I'll also note that while it is fairly common in Stock assessment software to have input files to control model behavior, I don't think it is common in regular modern software based on discussions I've had to explain how SS3 works to software engineers.

[kellijohnson-NOAA]

@Andrea-Havron-NOAA I am wondering if you think this Discussion and need for a vignette is still relevant?