Package {IncAAM}

IncAAM (Version 1.8): 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.14,
  male_threshold = 0.24,
  custom_threshold = NULL,
  known_A50 = NULL,
  min_Inc_num = 2,
  min_increments = 3,
  min_fish = 3,
  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.

The TR estimate is derived from the posterior distribution of c and the selected threshold. Jerk is calculated numerically from posterior fitted curves. The function then summarizes the posterior estimates across fish and constructs a posterior threshold-crossing ogive. A logistic ogive is fitted to the crossing probabilities, providing an estimated ogive A50 where the fitted probability reaches 0.5.

The threshold-crossing ogive describes the probability that the Tangent Ratio (TR) has fallen below the defined TR threshold at a given increment number, and therefore indicates sexual maturity according to the selected threshold. Ogive_A50 is the estimated increment number at 50% maturity from the fitted logistic ogive. The TR index is the estimated age at 50% maturity when the selected TR threshold is the maturity criterion calibrated for that purpose. The Jerk index is the increment number corresponding to the 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 (2026, 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

Group-level summary of TR and Jerk estimates.

fish

Fish-level posterior summaries of model parameters, TR, and Jerk.

increment

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

posterior

Posterior group-level draws for TR and Jerk.

crossing_ogive

Observed posterior crossing-ogive summary by increment number.

crossing_ogive_prediction

Predicted values from the fitted logistic ogive.

ogive_summary

Estimated ogive A50, slope, and intercept.

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.

plot

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

Examples

# 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

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.