IncAAM

Version 1.9

IncAAM is an R package for Bayesian age-at-maturity analysis based on annual increment-width growth series, such as otolith increment measurements. It fits a hierarchical nonlinear mixed-effects model with a negative-exponential growth curve and fish-level varying parameters.

What’s new in version 1.9

• Full, uncensored fish-level TR posteriors: TR crossing ages are no longer discarded when they exceed the last measured increment. The fraction crossing within the original observed increment range remains available as the diagnostic TR_reached_prob.
• Hierarchical population median TR: group-level TR is the posterior median of the population-median TR estimand, calculated from all post-warmup model draws. It is not a mean or median of fish-level estimates. Group uncertainty is expressed as a 95% Bayesian credible interval.
• Analytical hierarchical maturity ogive: each posterior draw of the population mean and SD of log(c) yields a population threshold-crossing probability. The ogive A50 is identical to the hierarchical population median TR, with its own 95% credible interval. No logistic regression is fitted. The existing ogive plot now shows 90% Bayesian credible shading, without vertical error bars.
• Jerk output: group-level jerk is now explicitly the jerk of the hierarchical reference growth curve, not an average of individual fish jerk estimates; fish-level jerk estimates remain available as diagnostics.
• New increment-range arguments: min_max_incnum optionally selects fish with an original maximum increment number at or above a specified value; max_incnum_fit optionally truncates the increment sequence used for fitting without changing its original maximum. The existing min_increments rule applies after the fitting cap.
• Updated tables and existing plots: tables identify the estimand, posterior median, 95% credible limits, sample size and threshold-reach diagnostics. The existing posterior TR/Jerk density plot shows posterior medians and optional known A50 references in both panels. No new plot types were added.

See NEWS.md for the change log.

Installation

Install the source archive in R:

install.packages("IncAAM_1.9.tar.gz", repos = NULL, type = "source")

Or, from an unpacked package source directory:

# Requires the 'devtools' package
# devtools::install("path/to/IncAAM")

Dependencies

The model uses brms with the cmdstanr backend by default. Install the required R packages and set up a compatible CmdStan toolchain before fitting a model. The cmdstanr and CmdStan installation instructions are maintained at https://mc-stan.org/cmdstanr/.

install.packages(c("brms", "dplyr", "tidyr", "purrr", "tibble",
                   "ggplot2", "posterior", "minpack.lm"))
# Follow the cmdstanr installation instructions at mc-stan.org/cmdstanr/.
# Then run cmdstanr::install_cmdstan() if CmdStan is not yet installed.

Example

library(IncAAM)
data(plaice)

plaice_female <- plaice |>
  dplyr::filter(Sex == "female")

fit <- IncAAM(
  data = plaice_female,
  FishID = "FishID",
  Inc_num = "Inc_num",
  Inc_width = "Inc_width_mm",
  sex = "female",
  known_A50 = 7.6,
  min_max_incnum = NULL,  # No minimum original maximum (version 1.8 selection)
  max_incnum_fit = Inf,    # Fit all measured increments (version 1.8 default)
  n_iter = 1500,
  n_warmup = 750,
  n_keepdraws = 500,
  n_adapt_delta = 0.995,
  n_logc_sd = 0.1
)

fit$summary
fit$crossing_ogive
fit$crossing_ogive_prediction
fit$ogive_summary
fit$fish                  # Fish-level diagnostic estimates
fit$posterior             # Posterior hierarchical estimates

For a restricted fitting range, for example fitting only increments 2–9 from fish whose original maximum increment number is at least 8:

fit <- IncAAM(
  data = plaice_female,
  sex = "female",
  min_max_incnum = 8,
  max_incnum_fit = 9,
  min_increments = 1
)

The last example is illustrative; the selected subset must contain at least min_fish fish. Fish with only one usable fitted increment are strongly informed by hierarchical partial pooling.

Analysis groups: The function expects one analysis group at a time. Filter by species, sex, population, and anatomical axis before calling IncAAM(). The default sex-specific TR thresholds are now 0.16 for females and 0.25 for males; supply custom thresholds when needed. A threshold must be strictly between 0 and 1.

Interpretation of output tables

• fit$summary has two rows. TR is the hierarchical population median TR; Jerk is the jerk of the hierarchical reference curve. Columns include estimate, CrI95_low, CrI95_high, posterior_sd, sample_n, and proportion_success. The former p5, p95, n_posterior_draws, and note columns are omitted from this concise summary. The two indexes are not interchangeable summaries of fish-level posterior estimates.
• fit$ogive_summary$Ogive_A50 equals the group-level hierarchical median TR; Ogive_A50_CrI95_low and Ogive_A50_CrI95_high provide its 95% credible interval.
• fit$crossing_ogive and fit$crossing_ogive_prediction give posterior-median probabilities of TR crossing by increment number, plus 90% and 95% Bayesian credible limits. The 90% credible range is shown on the plot; 95% limits are in the tables.
• fit$fish$TR_reached_prob is the posterior probability of crossing within the original observed increment series. Individual-fish TR and jerk summaries are diagnostic only, not population estimators.
• max_inc and n_obs in fit$fish refer to the fitting sequence; max_inc_observed refers to the uncapped measured increment series.

Both plot subtitles now report the hierarchical population TR median (rather than the selected TR threshold), and the ogive plot no longer uses the label Median A50. The original two plot outputs, fit$plot (TR/Jerk densities) and fit$ogive_plot (crossing ogive), can be displayed directly. With save_plots = TRUE, the original PDF names are retained: IncAAM_posterior_TR_Jerk.pdf and IncAAM_crossing_ogive.pdf.

Methodological reference

Details of the model, method, outputs and applications are provided in Campana, Smoliński, Morrongiello and Black (2027, in press). Users should consult that publication for methodological background, noting that version 1.9 implements the updated full-posterior hierarchical TR and analytical-ogive calculations described above.