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.