Reshape age or length composition data (observed and, optionally, expected proportions) from convert_output() into the tidy format used by the composition plotting functions (plot_composition_distribution(), plot_composition_bubble(), plot_composition_residuals(), plot_composition_sexratio(), plot_composition_francis(), plot_composition_samples(), plot_composition_residual_distribution(), plot_composition_residual_pattern(), and plot_composition_andre()). Each of these functions calls prepare_composition_data() itself, so it only needs to be called directly to inspect or modify the data.

prepare_composition_data(
  dat,
  comp_type = NULL,
  fleet = NULL,
  normalize = TRUE,
  conditional = FALSE
)

Arguments

dat

A tibble returned from convert_output() (see bigskate_lencomp). Compositions are the rows whose label contains "composition", for example:

Stock Synthesis (from an r4ss::SS_output() list)

"length_composition_observed", "length_composition_predicted", "length_composition_pearson_residual", and "length_composition_sample_size" (and the "age_" equivalents), with conditional age-at-length data labeled "conditional_age_composition_*".

FIMS

"age_composition_proportion" and "age_composition_expected" (and the "length_" equivalents).

BAM and Rceattle

"age_composition_observed" and "age_composition_predicted", or "composition_observed" and "composition_predicted".

Bins are taken from the age or length_bins column, and partitions from the part column. Other formats are also recognized:

Tidy composition data

Columns year, bin, and observed, with optional columns fleet, sex, part (partition: 0 = whole catch, 1 = discard, 2 = retained), expected, n (input or adjusted sample size), pearson, comp_type, and length_bin (for conditional age-at-length data).

FIMS estimates

Output from FIMS::get_estimates() that contains observed and expected columns. Rows whose label contains "comp" are kept and the bin is taken from the age or length column.

r4ss output

A list returned by r4ss::SS_output() (length and age compositions are combined and fleet names are added) or its lendbase or agedbase elements (columns Yr, Fleet, Sex, Bin, Obs, Exp, Pearson, Nsamp_adj, ...). Conditional age-at-length rows are dropped from agedbase so that only marginal age compositions remain, unless conditional = TRUE.

For conditional age-at-length data (conditional = TRUE), see bigskate_caal.

comp_type

String. Type of composition to keep when dat contains more than one. Options: "age", "length", or NULL (keep all). Default: NULL

fleet

Character or numeric vector. Fleet(s) to keep, matching either the fleet name (e.g., "Fishery_current") or the fleet name with its partition (e.g., "Fishery_current (retained)"). NULL keeps all fleets. Default: NULL

normalize

Logical. TRUE/FALSE; rescale observed and expected values so that they sum to one within each year, fleet, and composition type (and length bin for conditional data). Sex-specific compositions are normalized jointly across sexes, unless each sex already sums to one on its own (single-sex compositions). Use TRUE when dat contains counts rather than proportions. Default: TRUE

conditional

Logical. TRUE/FALSE; keep conditional age-at-length data instead of marginal compositions. Conditional compositions are normalized within each length bin. Used by plot_composition_andre() and plot_composition_bubble(). Default: FALSE

Value

A tibble with one row per year, fleet, sex, and bin and columns comp_type, fleet, year, sex, bin, observed, expected, n, and pearson (plus length_bin when conditional = TRUE). Columns that cannot be determined from dat are NA.

Details

When Pearson residuals are not supplied, they are calculated assuming a multinomial distribution as $$r = (o - e) / \sqrt{e (1 - e) / N}$$ where \(o\) and \(e\) are the observed and expected proportions and \(N\) is the sample size in the n column. If n is not available, residuals are left as NA.

Examples

comps <- prepare_composition_data(bigskate_lencomp, fleet = "WCGBTS")
head(comps)
#> # A tibble: 6 × 9
#>   comp_type fleet   year sex      bin observed expected     n pearson
#>   <chr>     <chr>  <dbl> <chr>  <dbl>    <dbl>    <dbl> <dbl>   <dbl>
#> 1 length    WCGBTS  2003 female    20  0.00516  0.00172  9.57  0.257 
#> 2 length    WCGBTS  2003 female    25  0.0109   0.00748  9.57  0.124 
#> 3 length    WCGBTS  2003 female    30  0.0161   0.0151   9.57  0.0257
#> 4 length    WCGBTS  2003 female    35  0.0312   0.0236   9.57  0.154 
#> 5 length    WCGBTS  2003 female    40  0.0362   0.0317   9.57  0.0811
#> 6 length    WCGBTS  2003 female    45  0.0213   0.0377   9.57 -0.266 

# Conditional age-at-length data
prepare_composition_data(bigskate_caal, conditional = TRUE)
#> # A tibble: 6,560 × 10
#>    comp_type fleet            year sex     bin observed expected      n  pearson
#>    <chr>     <chr>           <dbl> <chr> <dbl>    <dbl>    <dbl>  <dbl>    <dbl>
#>  1 age       Fishery_current  2004 male      0  9.98e-5  1.05e-4 0.0844 -1.49e-4
#>  2 age       Fishery_current  2004 male      1  9.98e-5  2.69e-3 0.0844 -1.45e-2
#>  3 age       Fishery_current  2004 male      2  9.98e-5  1.05e-1 0.0844 -9.92e-2
#>  4 age       Fishery_current  2004 male      3  9.98e-5  5.54e-1 0.0844 -3.24e-1
#>  5 age       Fishery_current  2004 male      4  9.99e-1  2.90e-1 0.0844  4.54e-1
#>  6 age       Fishery_current  2004 male      5  9.98e-5  4.71e-2 0.0844 -6.45e-2
#>  7 age       Fishery_current  2004 male      6  9.98e-5  9.75e-4 0.0844 -8.15e-3
#>  8 age       Fishery_current  2004 male      7  9.98e-5  1.13e-4 0.0844 -3.47e-4
#>  9 age       Fishery_current  2004 male      8  9.98e-5  9.99e-5 0.0844 -1.11e-6
#> 10 age       Fishery_current  2004 male      9  9.98e-5  9.98e-5 0.0844 -6.82e-9
#> # ℹ 6,550 more rows
#> # ℹ 1 more variable: length_bin <dbl>

# Data in the stockplotr long format are reshaped automatically
long <- data.frame(
  label = rep(c("age_composition_proportion", "age_composition_expected"), each = 3),
  year = 2020,
  fleet = "fleet1",
  age = rep(1:3, 2),
  estimate = c(0.2, 0.5, 0.3, 0.25, 0.45, 0.3)
)
prepare_composition_data(long)
#> # A tibble: 3 × 9
#>   comp_type fleet   year sex        bin observed expected     n pearson
#>   <chr>     <chr>  <dbl> <chr>    <dbl>    <dbl>    <dbl> <dbl>   <dbl>
#> 1 age       fleet1  2020 combined     1      0.2     0.25    NA      NA
#> 2 age       fleet1  2020 combined     2      0.5     0.45    NA      NA
#> 3 age       fleet1  2020 combined     3      0.3     0.3     NA      NA