Document units in FIMS

[Bai-Li-NOAA]

What is the feature?

This PR addresses issue #561 and documents units in FIMS

How have you implemented the solution?

• Document units in code snips of the FIMS demo vignette since folks uses this vignette as an example to set up case studies.
• Add units to output figures and add a spawning biomass comparison figure
• Add a test to confirm that age composition input can be in number or proportion

Does the PR impact any other area of the project?

No

How to test this change

No changes to the core code base

Developer pre-PR checklist

• I relied on GitHub actions to 🧪 things for me while I sat on the 🛋️.

[github-actions]

Instructions for code reviewer

Hello reviewer, thanks for taking the time to review this PR!

• Please use this checklist during your review, checking off items that you have verified are complete!
• For PRs that don't make changes to code (e.g., changes to README.md or Github actions workflows), feel free to skip over items on the checklist that are not relevant. Remember it is still important to do a thorough review.
• Then, comment on the pull request with your review indicating where you have questions or changes need to be made before merging.
• Remember to review every line of code you’ve been asked to review, look at the context, make sure you’re improving code health, and compliment developers on good things that they do.
• PR reviews are a great way to learn, so feel free to share your tips and tricks. However, for optional changes (i.e., not required for merging), please include nit: (for nitpicking) before making the suggestion. For example, nit: I prefer using a data.frame() instead of a matrix because...
• Engage with the developer when they respond to comments and check off additional boxes as they become complete so the PR can be merged in when all the tasks are fulfilled. Make it clear when this has been reached by commenting on the PR with something like This PR is now ready to be merged, no changes needed.

Checklist

• The PR is requested to be merged into the appropriate branch (typically main)
• The code is well-designed.
• The functionality is good for the users of the code.
• Any User Interface changes are sensible and look good.
• The code isn’t more complex than it needs to be.
• Code coverage remains high, indicating the new code is tested.
• The developer used clear names for everything.
• Comments are clear and useful, and mostly explain why instead of what.
• Code is appropriately documented (doxygen and roxygen).

[kellijohnson-NOAA]

These commits help with the documentation in the vignette but #561 refers to the fact that there is a unit column in data_mile1 that is not filled out for all entries and that is not addressed.

[Bai-Li-NOAA]

@kellijohnson-NOAA, I've updated the unit column in data_mile1, but I think issue #561 needs further discussion & work if we want to document units alongside the code (see my comment here). Should I open a pull request to merge the changes I've made so far or would it be preferable to wait until we've reached decisions on where to document units alongside code?

[kellijohnson-NOAA]

@Bai-Li-NOAA do you mind if I make one change to this PR and one addition?

[Bai-Li-NOAA]

@kellijohnson-NOAA. No, I don't mind at all. Please feel free to make any changes.

[kellijohnson-NOAA]

Thanks @Bai-Li-NOAA I pushed one small change and an addition. The addition is going to conflict with the other open PR but it is pretty minor so I am willing to deal with the conflicts.

[iantaylor-NOAA]

Thanks @Bai-Li-NOAA and @kellijohnson-NOAA for working on this.

The index units are listed as "mt", but since we have a catchability parameter available, isn't it equally possible to use any other units (or unknown units) as long as the index is assumed proportional to biomass?

Related to that, it looks like our model specification says (incorrectly I think) that "survey is in number":
https://github.com/NOAA-FIMS/collaborative_workflow/blob/865c05e5513ff1efc9533e647d1a4bf023f6d561/03-model-specification.Rmd#L122-L130

[kellijohnson-NOAA]

@Bai-Li-NOAA I was able to rebase this branch with the main branch without any conflicts. Would you like me to force push the rebase?

[Bai-Li-NOAA]

Force push the rebase sounds good. Thanks, @kellijohnson-NOAA. I will reopen the pull request after that.

@iantaylor-NOAA , good catch. The unit from the model specification chapter is incorrect.

[Andrea-Havron-NOAA]

@Bai-Li-NOAA, can you reassign this to another reviewer? I won't have time to look at this until the end of next week.

[Bai-Li-NOAA]

@Andrea-Havron-NOAA, thanks for letting me know. I will find another reviewer for the pull request.

@iantaylor-NOAA, would you be available to review the pull request? You've made some helpful suggestions on it in the past. If you're busy, no worries. I'll continue looking for another reviewer. Thanks!

[iantaylor-NOAA]

Looks good. Thanks @Bai-Li-NOAA for making these improvements.

The one question that this PR raises for me is whether there's a way to make the tests more modular. That is, the new "agecomp in proportion works" test added to test-integration-fims-estimation.R has a lot of redundancy with the existing "estimation test of fims". We want to make sure proportions still pass all the same checks but the duplicate code would be harder to maintain than if there's some way to wrap it in a function without losing the ability to get detailed output from each element of the test. Having said that, I don't think it makes sense to spend more time on this now, rather to think about the issue for future revisions to the tests.