[ericward-noaa]

This PR is related to this FIMS discussion, NOAA-FIMS/FIMS#1873, and this r4ss issue r4ss/r4ss#1104 (comment), the need to generate composition plots.

Copilot summary:
This pull request adds a comprehensive set of tools for visualizing and diagnosing composition data (age/length) in fisheries stock assessment, including new plotting functions, example data, and extensive documentation. The main changes are the introduction of new plotting functions for composition data and their documentation, the addition of a simulated example dataset, and updates to the package exports and documentation to support these features.

New composition plotting and diagnostics functionality:

• Added new plotting functions for composition data: plot_comp, plot_comp_bubble, plot_comp_mean, plot_comp_residuals, and plot_comp_sex_ratio, along with a data preparation function prepare_comp_data. These functions provide a variety of diagnostic plots for observed and expected age/length compositions, including bubble plots, mean trends, Pearson residuals, and sex ratio plots. [1] [2]

• Added man page documentation for all new functions, describing their usage, arguments, outputs, and examples: plot_comp.Rd, plot_comp_bubble.Rd, plot_comp_mean.Rd, plot_comp_residuals.Rd, plot_comp_sex_ratio.Rd, and prepare_comp_data.Rd. [1] [2] [3] [4] [5] [6]

Example data and reproducibility:

• Added a new simulated dataset example_comp_data (with generation code and documentation) to demonstrate the composition plotting functions. This data includes sex-specific age compositions for a fishery and a survey, with known patterns of misfit for testing diagnostics. [1] [2] [3]

Documentation and navigation updates:

• Updated the package documentation site navigation to include a new article on composition data diagnostics, making it easier for users to find and learn about these new features.

These changes significantly expand the package's capabilities for composition data analysis and provide users with tools and guidance for diagnosing model fit to age/length compositions.

[Schiano-NOAA]

@ericward-noaa is this ready for review?

[ericward-noaa]

Yes @Schiano-NOAA I think so

[Schiano-NOAA]

We can set up a space in the csv that holds captions and alternative text for figures that can be called and made into an RDA which is a cundle of the plot, caption, and alternative text that can be incorporated into a report or other thing.

[Schiano-NOAA]

Could you expand on the use of this data set with the exception of using it for the comps plots? We the test data set for all examples in the package, example_data. I have an open PR to expand them to have samples for each model that is compatible with the convet_output function.

[ericward-noaa]

Good question. I initially was going to use example_data, but couldn't because the composition plots need the observed and expected proportions in each bin. I used the Big Skate example because it's the one used in the r4ss example plots (https://r4ss.github.io/r4ss/BigSkate/), so plots can be checked against r4ss

I think once the other PR is done and example_data is expanded to include each model, then the Big Skate datasets could be dropped

[Schiano-NOAA]

This works great for the skate example data and provides a good foundation for the comp plots. I have a series of comments and questions and comments that need to be answered. If you don't have the bandwidth to make this work with the standard output, then I can take over from here. I think some of the issue is due to a divergence of the FIMS output and standard output which is not our intention and will be resolved by the end of the year.

I also am wondering how standard some of these approaches are. I apologize for my ignorance on this topic and would be interested to hear if this is done across the board or just the decision made for comp plots for FIMS or specific regions.

There are also some other minor things like function naming and locations that can easily be adjusted.

I thank you so much for this important contribution to {stockplotr} and cannot stress enough the help this brings to our team 😄

[ericward-noaa]

Thanks for the review @Schiano-NOAA -- I think most of these are pretty minor, and I"ll start to push changes to address them. I'll tag you when ready for re-review

[ericward-noaa]

@Schiano-NOAA I think I've dealt with most of the comments above, but there's 2 lingering ones that I think you can help with:

1. You say "We can set up a space in the csv that holds captions and alternative text for figures that can be called and made into an RDA which is a cundle of the plot, caption, and alternative text that can be incorporated into a report or other thing."

2. Related to the other PR request around data, I'm not wedded to the Big Skate data but used it because of compatibility with r4ss. It seems like if the example_data contains observed and expected counts by bin, we wouldn't need the Big Skate data any more.

Given the overlap with r4ss, it'd be great to have @iantaylor-NOAA or @Rick-Methot-NOAA take a look and see how these can be improved

bigskate_composition_plots.pdf

[iantaylor-NOAA]

@ericward-noaa, these are excellent! It's amazing to see how quickly you were able to replicate years worth of work. We live in amazing times.

Overall, I think the plots are great and are more than adequate to replace the r4ss diagnostics.

Here are a few additional changes that could be considered, none of which are vital and all could be added down the road. I'm happy to help with any of these things if folks think it's a good idea to add them.

1. Numeric values in the corner of the bar plots: You've replicated the r4ss behavior of printing the adjusted input sample size and the effective sample size associated with the McAllister-Ianelli weighting. We've moved away from using the McAllister-Ianelli weighting thanks to a Punt paper showing other methods perform better so I'm not sure there's value in printing that number. For FIMS, there's just the single input sample size. When Dirichlet-multinomial likelihoods are added to FIMS, then we could print the input sample size and the adjusted sample size (scaled by the D-M parameter). In theory the numbers could be model dependent--maybe your code already does this. In that spirit, I'm not sure the Adjusted input sample size vs Effective sample size plot is providing value for anyone any longer.
2. Potential improvements to Andre plots: There's a list of potential changes in a slide from an old talk with comments below here: refinements to CAAL diagnostic plots r4ss/r4ss#613.
3. Colors for cohorts in age comps: the hake assessment colors cohorts in age comps using code in https://github.com/pacific-hake/hake-assessment/blob/main/R/plot-age-comp-fit.R (example below pasted from https://www.pcouncil.org/documents/status-of-the-pacific-hake-whiting-stock-in-us-and-canadian-waters-in-2025/). I think @jimianelli-NOAA was the first person I saw using this approach. Note that In the case of hake it's a single-sex model, so there's no need to distinguish females from males and also the fits are based on Bayesian posterior samples so uncertainty is available.

[iantaylor-NOAA]

Here's one more comment that I forgot to include.
4. Sorting panels by column instead of row: This was actually the original reason we didn't use the lattice package for r4ss back in 2008 because sorting by column wasn't available. I think the benefits of the column sorting are clear in the hake example I pasted above, where the march of the cohorts are more easily visible when sorted by column due to the bars also being vertical (e.g. pink 1980 cohort, purple 1984 and 1999 cohorts).

[ericward-noaa]

Great comments, thanks for the fast thoughts @iantaylor-NOAA ! For the plots breaking out sex, r4ss sticks with red-blue -- should we stick to the same convention here?

[iantaylor-NOAA]

For the plots breaking out sex, r4ss sticks with red-blue -- should we stick to the same convention here?

I just found this post: https://www.datawrapper.de/blog/gendercolor which makes me think that we can do better than red and blue. I don't have strong opinions on what alternative to use, however. I personally like the Telegraph 2018 purple and green, but this seems like something that the stockplotr team can decide however they see fit. Thanks to the flexibility of ggplot, I'm assuming that users could theoretically change the colors however they wish (although hopefully a good default will be good enough for everyone).

[Rick-Methot-NOAA]

This all looks great to me. Good work.
I'll reiterate suggestion for an interactive viewer which allows users to select and re-arrange plot elements to create a mind's eyeful collection that facilitates finding patterns in residuals that warrant additional model flexibility to resolve.