[Feature]: provide input with units of spawning output

[iantaylor-NOAA]

Describe the feature request.

Stock Synthesis is ignorant of the units of spawning output (if different from biomass) because it depends on the units you choose for the fecundity parameters. In the case of petrale sole, we have chosen parameter values such that the resulting units are in trillions of eggs to avoid really long numbers in the figure axis labels and table.

I think it would be useful for the user to be able to provide inputs to the various functions that will add the units to the axis labels or table headers, but I'm not sure how best to do that.

My current thinking is that the best approach would be providing an additional argument to SS_output() so that the units are added to the list created by that function and automatically used (if not NULL) by the various functions that use the output, such as SSplotTimeseries(), SSplotBiology(), SSplotSpawnrecruit() and SSexecutivesummary().

Describe alternatives you have considered

Additional arguments to SS_plots() and SSexecutivesummary() and have the user add the units each time one of those functions is run. However, that seems like more work than adding the units in one place and would result in differences between plots created by SS_plots() vs the individual plotting functions.

Statistical validity, if applicable

No response

Describe if this is needed for a management application

No response

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[e-perl-NOAA]

@iantaylor-NOAA I think this would be relatively easy to do. I believe it would have to be specified in SS_plots as well as all of the different plotting functions that will use it. I could see an additional param of spawn_output_units = NULL. At least for the SSplotSpawnrecruit I see the labels specified here:

r4ss/R/SSplotSpawnrecruit.R

Lines 59 to 64 in 80ba821

	labels = c(
	"Spawning biomass (mt)",
	"Recruitment (1,000s)",
	"Spawning output",
	expression(paste("Spawning output (relative to ", italic(B)[0], ")")),
	expression(paste("Recruitment (relative to ", italic(R)[0], ")")),

and that spawning output label used here:

r4ss/R/SSplotSpawnrecruit.R

Lines 110 to 113 in 80ba821

	if (is.null(replist[["SpawnOutputUnits"]]) ||
	is.na(replist[["SpawnOutputUnits"]]) ||
	replist[["SpawnOutputUnits"]] == "numbers") { # quantity from test in SS_output
	xlab <- labels[3]

I think that could be changed to something like:

if(!is.null(spawn_output_units){
xlab <- paste(labels[3], spawn_output_units, sep = " ")
} else {
xlab <- paste(labels[3]
}

or just a general:

if(!is.null(spawn_output_units){
labels[3] <- paste(labels[3], spawn_output_units, sep = " ")
}

or even simpler without having to specify a particular label closer to the beginning of each plotting function:

if(!is.null(spawn_output_units){
gsub("(.*?)Spawning output(.*?)", paste0("Spawning output (", spawn_output_units,")"), labels)
}

[kellijohnson-NOAA]

@iantaylor-NOAA is there no way to figure out the scale from the fecundity parameters?

[iantaylor-NOAA]

There's not because you could choose to rescale the fecundity parameters to get different units, as discussed in https://pfmc-assessments.github.io/pfmc_assessment_handbook/02-model-choices.html#fecundity.

And fecundity varies so much among species is so great that there's no way to figure out what a reasonable value would be.

I put together an attempted solution that worked for petrale for purposes of the report that is due today and I will put together a draft pull request later today or tomorrow to generate discussion about whether it is a reasonable approach.