[Documentation]: Vignette Request of Integer representation

[Andrea-Havron-NOAA]

A key difference between FIMS and other stock assessment platforms is that FIMS uses integer representation instead of a file/list of control options to control what pieces of FIMS get used in a given model run. Users create a module which is tracked in FIMS with a unique integer. It is recommended to highlight this feature of FIMS in a new vignette.

• [ ] 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
• [ ] Provide UML graphs where helpful

[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]

Yes, I think it would be useful to generate a UML graph. I think this 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]

I think that this vignette can partially be created when the R interface team revamps how users interact with the modules. I will work with @msupernaw on it once we start working with that part of the code.