create initial versions of composition plots by ericward-noaa · Pull Request #424 · nmfs-ost/stockplotr

ericward-noaa · 2026-10-16T16:06:07Z

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.

Added new entries to the WORDLIST file.

- change example / diagnostic dataset from simulated to big skate - added more plots from ian's list - more / better tests

forgot to run spell_check_package() added a few missing words

Schiano-NOAA · 2026-10-19T19:34:50Z

@ericward-noaa is this ready for review?

ericward-noaa · 2026-10-19T19:37:31Z

Yes @Schiano-NOAA I think so

Schiano-NOAA · 2026-10-21T13:45:44Z

+)
+
+# Reshape r4ss composition databases to stockplotr's snake_case columns
+tidy_dbase <- function(dbase, comp_type, fleet_names) {


convert_output() accepts the returned value from r4ss::ss_output() called replist in this example so this step should not be neccessary

Good point, changed in this commit: 2fc6036

Schiano-NOAA · 2026-10-21T13:54:40Z

+#' `aggregate = TRUE` instead sums the compositions across years so that each
+#' fleet is summarized in a single panel.
+#'
+#' @param dat A data frame of composition data in any format accepted by


This should be the standard output framework from convert_output(). prepare_comp_data() can be called inside of this function as done with all other functions in {stockplotr}. This ensures this function works with all assessment models compatible with convert_output() (BAM, FIMS, SS3, and Rceattle).

I changed this per your suggestion in this commit: 2fc6036

Schiano-NOAA · 2026-10-21T13:56:21Z

+#' created for every fleet and year combination; use `fleet` to focus on one
+#' fleet at a time.
+#'
+#' @section r4ss equivalent: `r4ss::SSplotComps()` subplot 1 (by year) and


this will need to be expanded for equivalent for other models which I can look into

Changed this a little in this commit, but other models can be added eventually: 2fc6036

My main motivation in doing this is to show residuals / diagnostics for FIMS, and some of the plots are being brought over from SS.

Schiano-NOAA · 2026-10-21T13:58:48Z

+  bins <- sort(unique(comps$bin))
+  width <- if (length(bins) > 1) min(diff(bins)) else 1
+
+  plt <- ggplot2::ggplot(comps, ggplot2::aes(x = .data$bin))


Can you see this type of plot being used for anything else? In that case, this could be generalized in a separate function like plot_timeseries. If not, then no action.

Good idea, split out in this commit: 2fc6036

Schiano-NOAA · 2026-10-21T14:07:35Z

+  has_exp <- any(!is.na(means$mean_exp))
+  has_se <- any(!is.na(means$se))
+
+  # Francis weights by fleet. As in Stock Synthesis and


Do other regions use this as well?

Schiano-NOAA · 2026-10-21T14:20:11Z

+#------------------------------------------------------------------------------
+
+# Prepare comps and keep rows with residuals, or abort with a hint
+comp_residuals_or_abort <- function(dat, comp_type = NULL, fleet = NULL) {


helpers should go into the utils_plot.R file or can shift into the utils_comp.R file in this PR

These functions moved over in this commit: 11424d6

Schiano-NOAA · 2026-10-21T14:35:33Z

+      )
+  }
+
+  caption <- NULL


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 · 2026-10-21T14:43:21Z

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.

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 · 2026-10-21T21:02:46Z

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 and others added 5 commits October 16, 2026 07:20

create initial versions of composition plots

ce6adae

Merge branch 'main' into feat/composition-plots

997f818

Update WORDLIST with additional terms

4f0cdee

Added new entries to the WORDLIST file.

update examples

aaf99ea

- change example / diagnostic dataset from simulated to big skate - added more plots from ian's list - more / better tests

spelling

67e1152

forgot to run spell_check_package() added a few missing words

JZahner1 mentioned this pull request Oct 21, 2026

Brainstorm ways to automatically update save_all_plots() #432

Open

Schiano-NOAA reviewed Oct 21, 2026

View reviewed changes

Comment thread R/plot_composition.R

Schiano-NOAA reviewed Oct 21, 2026

View reviewed changes

Schiano-NOAA requested changes Oct 21, 2026

View reviewed changes

ericward-noaa and others added 4 commits October 21, 2026 14:05

Merge branch 'nmfs-ost:main' into feat/composition-plots

0bf590f

update function names throughout

b0cc312

moving utilts to utils_composition

11424d6

reorganization and re-doc

2fc6036

Conversation

ericward-noaa commented Oct 16, 2026

Uh oh!

Schiano-NOAA commented Oct 19, 2026

Uh oh!

ericward-noaa commented Oct 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Schiano-NOAA Oct 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Schiano-NOAA left a comment

Choose a reason for hiding this comment

Uh oh!

ericward-noaa commented Oct 21, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Schiano-NOAA Oct 21, 2026 •

edited

Loading