Package {IncAAM}

IncAAM (Version 1.9): Bayesian age-at-maturity analysis from increment-width growth series

Description

Fits a Bayesian hierarchical nonlinear mixed-effects model to annual increment-width data and estimates age at maturity using posterior threshold-ratio (TR) and jerk approaches. The model uses a negative exponential curve with fish-level varying parameters.

Usage

IncAAM(
  data,
  FishID = "FishID",
  Inc_num = "Inc_num",
  Inc_width = "Inc_width_mm",
  sex = "female",
  female_threshold = 0.16,
  male_threshold = 0.25,
  custom_threshold = NULL,
  known_A50 = NULL,
  min_Inc_num = 2,
  min_increments = 3,
  min_fish = 3,
  min_max_incnum = NULL,
  max_incnum_fit = Inf,
  jerk_step = 0.01,
  chains = 4,
  cores = 4,
  n_iter = 1500,
  n_warmup = 750,
  n_keepdraws = 500,
  seed = 123,
  backend = "cmdstanr",
  n_adapt_delta = 0.995,
  n_logc_sd = 0.1,
  max_treedepth = 15,
  make_plots = TRUE,
  save_plots = FALSE,
  output_dir = NULL
)

Arguments

Details

The input data should represent one analysis group. IncAAM() does not perform grouping by species, sex, axis, stock, or other variables; users should filter the data before calling the function.

The model describes increment width using a negative exponential function,

Increment = a + b exp(-c Inc\_num),

with fish-level varying parameters a, b, and c. The parameters are estimated in log space in a Bayesian hierarchical model using brms.

Individual fish TR is calculated analytically from every selected fish-level posterior draw of c, without censoring at the last observed increment. The primary group-level estimator is the hierarchical population median TR, calculated for every post-warmup draw from the population intercept of log(c). Its uncertainty is a 95% Bayesian credible interval across these full posterior draws, not an SE across fish. Jerk remains the numerically calculated index; its group-level value is the jerk of the hierarchical reference growth curve, not a population median jerk.

The threshold-crossing ogive is computed analytically from the joint posterior of the population log(c) intercept and between-fish SD. The ogive displays posterior-median crossing probability and 90% Bayesian credible shading; both 90% and 95% credible limits are included in tables. The ogive A50 equals the hierarchical median TR with its own posterior 95% credible interval. No logistic regression is fitted. TR_reached_prob is a diagnostic probability of crossing by the LAST originally observed increment, not a criterion for excluding posterior TR. The TR threshold must be strictly between 0 and 1.

The TR index estimates the age at 50% maturity when the selected TR threshold has been calibrated to that criterion. The jerk index indicates the age of maximum jerk and is not currently assigned to a defined proportion or stage of sexual maturity.

Details of the model, method, outputs and applications are provided in Campana, Smoliński, Morrongiello and Black (2027, in press). Users should consult this publication for the methodological background and interpretation of IncAAM outputs.

The function returns the fitted Bayesian model together with fish-level estimates, increment-level threshold-crossing probabilities, posterior group distributions, ogive results, fitted curves, diagnostics, settings, and optional plots.

Value

An object of class IncAAM (a list) containing:

summary

Hierarchical population median TR and reference-curve jerk, with 95% credible intervals; excludes redundant p5, p95, n_posterior_draws and note columns.

fish

Diagnostic fish-level posterior summaries of model parameters, uncensored TR, and Jerk.

increment

Fish- and increment-level posterior threshold-crossing probabilities.

posterior

Posterior draws of hierarchical population median TR and reference-curve jerk.

crossing_ogive

Analytical hierarchical crossing probability and credible intervals at observed increment numbers.

crossing_ogive_prediction

Analytical hierarchical crossing probabilities and credible intervals over a fine age grid.

ogive_summary

Hierarchical ogive A50, its 95% credible interval, and model metadata.

ogive_plot

Threshold-crossing ogive plot, when plots are enabled.

fitted_curves

Fish-level fitted negative-exponential curves.

model

The fitted brms model object.

diagnostics

MCMC and sampling diagnostics.

settings

Analysis settings used by the function.

data

Basic information on the analyzed data, including original maximum increment numbers.

plot

Posterior TR/Jerk density plot, when plots are enabled.

Examples

## Not run: 
# Example based on the current IncAAM test workflow:
library(IncAAM)
library(dplyr)

data(plaice)
head(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,
  n_iter = 1500,
  n_warmup = 750,
  n_keepdraws = 500,
  n_adapt_delta = 0.995,
  n_logc_sd = 0.1
)

#Users can display the complete set of model outputs with `print(fit)`,
#or inspect individual output components directly (e.g. `fit$summary`).

print(fit)

fit$summary
fit$crossing_ogive
fit$ogive_summary

## End(Not run)

Example plaice otolith increment data

Description

A small example dataset containing otolith increment-width measurements from 28 plaice (Pleuronectes platessa) of both sexes. The dataset is provided for demonstrating the IncAAM workflow, including data filtering, preparation, and age-at-maturity modelling.

Usage

data(plaice)

Format

A data frame with 347 rows and 7 variables:

Species

Species name.

FishID

Unique fish identifier.

Sex

Sex of the fish (male or female).

Axis

Otolith axis used for increment measurements (section).

Inc_num

Sequential increment number.

Inc_width_mm

Width of the otolith increment in millimetres.

Fishlen_cm

Fish length in centimetres.

Details

The dataset contains complete increment-width series for 28 individual fish and is intentionally composed of both males and females. In the example workflow, the data are first loaded with data(plaice) and subsequently filtered to retain female fish before fitting the age-at-maturity model.

Source

Example data prepared for the IncAAM package.