Bayesian inference for Underhill-Zucchini moult models and expansions

moultmcmc(
  moult_column,
  date_column,
  id_column = NULL,
  start_formula = ~1,
  duration_formula = ~1,
  sigma_formula = ~1,
  type = 2,
  lump_non_moult = FALSE,
  data,
  init = "auto",
  flat_prior = TRUE,
  beta_sd = 0,
  log_lik = FALSE,
  use_phi_approx = FALSE,
  active_moult_recaps_only = TRUE,
  same_sigma = FALSE,
  ...
)

Arguments

moult_column: the name the column in data containing moult indices, i.e. a numeric vector of (linearized) moult scores in [0,1] (0 = old plumage, 1 = new plumage; for model types 1-5), numerical moult codes (1 = old plumage, 2 = moulting, 3 = new plumage; for model type 1), or a mixed column created by consolidate_moult_records for model type 12.
date_column: the name the column in data containing sampling dates, encoded as days since an arbitrary reference date, i.e. a numeric vector
id_column: (optional) factor identifier. Usually a season-individual combination to encode within-season recaptures, defaults to NULL. When provided moultmcmc will attempt to fit the relevant recaptures model.
start_formula: model formula for start date
duration_formula: model formula for duration
sigma_formula: model formula for start date sigma
type: integer (one of 1,2,3,4,5,12) referring to type of moult data and consequently model to be fitted (see details)
lump_non_moult: logical; should pre- and post-moult observations be treated as indistinguishable? if TRUE and type %in% c(1,2,12), the relevant lumped model will be fitted (see details).
data: Input data frame must contain a numeric column "date" and a column "moult_cat" which is a numeric vector of categorical moult codes (1 = old plumage,2 = moulting,3 = new plumage).
init: Specification of initial values for all or some parameters. Can be the string "auto" for an automatic guess based on the data, or any of the permitted rstan options: the digit 0, the strings "0" or "random", or a function. See the detailed documentation for the init argument in rstan::stan.
flat_prior: use uniform prior on start date and duration (TRUE) or vaguely informative truncated normal prior (FALSE). Defaults to TRUE.
beta_sd: use zero-centred normal priors for regression coefficients other than intercepts? If <= 0 the stan default of improper flat priors is used.
log_lik: boolean retain pointwise log-likelihood in output? This enables model assessment and selection via the loo package. Defaults to FALSE, can lead to very large output arrays when sample size is large.
use_phi_approx: logical flag whether to use stan's Phi_approx function to calculate the "old" likelihoods
active_moult_recaps_only: logical flag whether to ignore repeated observations outside the active moult phase
same_sigma: logical flag, currently unused
...: Arguments passed to rstan::sampling (e.g. iter, chains).

Value

An object of class stanfit returned by rstan::sampling

Details

type refers to the type of moult data available (see Underhill and Zucchini (1998) and Underhill, Zucchini and Summers (1990)).

type = 1 sample is representative of entire population (not yet moulting, in moult, and birds which have completed moult). For type 1 data, any value between 0 and 1 (> 0 and < 1) can be used as the moult index for birds in active moult. The value used does not matter, only the fact that they are in moult. type = 2 (default) sample is representative of entire population (not yet moulting, in moult, and birds which have completed moult). Moult scores are required.

type = 3 sample is representative only of birds in moult. Individuals with moult scores 0 or 1 are ignored.

type = 4 sample is representative only of birds in moult and those that have completed moult. Individuals with moult scores 0 are ignored.

type = 5 sample is representative only of birds that have not started moult or that are in moult. Individuals with moult scores 1 are ignored.