Package 'moultmcmcExtra'

Title: Add-on Functions for Moult Models
Description: Add-on functions for the moultmcmc package for modelling avian primary moult phenology.
Authors: Philipp Boersch-Supan [aut, cre] (ORCID: <https://orcid.org/0000-0001-6723-6833>)
Maintainer: Philipp Boersch-Supan <[email protected]>
License: MIT + file LICENSE
Version: 0.0.0.9000
Built: 2026-06-28 15:07:15 UTC
Source: https://github.com/pboesu/moultmcmcExtra

Help Index

Pairwise plots of posterior draws

Description

Plots pairwise scatter/density plots of posterior draws

Usage

compairs_plot(
  x,
  y = NULL,
  pars = NULL,
  scatter = TRUE,
  overlay = TRUE,
  names = NULL,
  col = NULL,
  ...
)

Arguments

x

a moultmcmc object
y

an optional second moultmcmc object
pars

An optional character vector of parameter names. If pars is not specified then the default is to use the first 4 parameters of x.
scatter

logical, draw scatterplot of posterior samples if overlay = FALSE, else draw contours
overlay

logical, plot scatterplots and density contours of both models in each triangle, else draw one model per triangle
names

optional character vector of model names
col

optional vectors of colours (length 2)
...

further arguments to plot.default (the call that draws the scatter/contour plot)

Compare plot that handles random effect models

Description

Compare plot that handles random effect models

Usage

compare_plot_annual_ranef(..., names = NULL)

Arguments

...

two or a moult or moultmcmc model
names

optional character vector of model names

Value

a plot comparing parameter estimates and their uncertainties

Bayesian inference for Underhill-Zucchini moult models and expansions

Description

Bayesian inference for Underhill-Zucchini moult models and expansions

Usage

moultmcmc_ranef(
  moult_column,
  date_column,
  id_column = NULL,
  start_formula = ~1,
  duration_formula = ~1,
  sigma_formula = ~1,
  ranef_factor_column,
  type = 5,
  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,
  ranef_components = c("start", "duration"),
  standata_only = FALSE,
  all_pars = 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
ranef_factor_column

the name of a factor column in data that contains factor values representing the levels of a random effect
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
ranef_components

character vector specifying which linear predictors receive annual random intercepts. Any combination of "start" (start date) and "duration". Defaults to c("start", "duration") (both).
standata_only

logical; if TRUE, return the Stan data list (standata) without fitting the model.
all_pars

logical; if TRUE, do not restrict pars in rstan::sampling (return all parameters).
...

Arguments passed to rstan::sampling (e.g. iter, chains).

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.

Value

An object of class stanfit returned by rstan::sampling

Predict method for moultmcmc models with non-individual random effects

Description

Predict method for moultmcmc models with non-individual random effects

Usage

predict_ranef(
  object,
  newdata = NULL,
  predict.type = "parameters",
  summary = TRUE,
  intervals = 0.1,
  prob = 0.95,
  ...
)

Arguments

object

a fitted moultmcmc model
newdata

data.frame with explanatory variables for which to make predictions
predict.type

specifies form of predictions, see details.
summary

logical, if TRUE (default) return a data.frame of posterior means, otherwise return a list of arrays of the full posterior sample of the predicted quantity (with one list element per predicted quantity and array dimensions nrow(newdata) *number or posterior draws)
intervals

not currently used
prob

nominal coverage probability of credible interval
...

further arguments

Value

a data.frame or list, depending on input arguments

Empirical moult dependent capture probabilities

Description

A lookup dataset containing empirical capture probabilities for siskins

Usage

siskin_capture

Format

A data frame with 1000 rows and 2 variables:

pfmg

pfmg

p_cap

capture probability

Source

P. Boersch-Supan / Hugh Insley

Bayesian inference for the Type 2 moult model with annual random intercepts (no individual recaptures)

Description

Fits a Type 2 (Underhill-Zucchini) moult model with annual random intercepts on start date and duration. No individual-level random effects; use when within-season recaptures are absent. Type 2 data include birds in old plumage, active moult, and new plumage.

Usage

uz2_linpred_annual_ranef(
  moult_index_column,
  date_column,
  start_formula = ~1,
  duration_formula = ~1,
  sigma_formula = ~1,
  ranef_factor_column,
  ranef_components = c("start", "duration"),
  flat_prior = FALSE,
  lumped = FALSE,
  beta_sd = 0,
  data,
  init = "auto",
  log_lik = TRUE,
  standata_only = FALSE,
  ...
)

Arguments

moult_index_column

the name of the column in data containing moult indices, i.e. a numeric vector of (linearised) moult scores: 0 = old plumage, 1 = new plumage
date_column

the name of the column in data containing sampling dates, encoded as days since an arbitrary reference date (numeric vector)
start_formula

model formula for start date
duration_formula

model formula for duration
sigma_formula

model formula for start date sigma
ranef_factor_column

the name of a factor column in data containing year identifiers
ranef_components

character vector specifying which linear predictors receive annual random intercepts. Any combination of "start" (start date) and "duration". Defaults to c("start", "duration") (both).
flat_prior

logical; use flat (uniform) priors on start date and duration intercepts? Defaults to FALSE (weakly informative normal priors)
lumped

logical; use the lumped (Type 2L) likelihood? Defaults to FALSE
beta_sd

use zero-centred normal priors for regression coefficients other than intercepts? If <= 0 Stan's default improper flat priors are used
data

input data frame
init

specification of initial values. Can be "auto" or any permitted rstan::sampling option
log_lik

logical; retain pointwise log-likelihood in output? Defaults to TRUE
standata_only

logical; if TRUE, return the Stan data list without fitting
...

arguments passed to rstan::sampling (e.g. iter, chains)

Value

When standata_only = FALSE, an object of class moultmcmc; otherwise the Stan data list

Bayesian inference for the Type 2 moult model with repeat measures and annual random intercepts

Description

Fits a Type 2 (Underhill-Zucchini) moult model that includes individual-level random intercepts for within-season recaptures and annual random intercepts on start date and duration. Type 2 data include birds in old plumage, active moult, and new plumage.

Usage

uz2_recap_annual_ranef(
  moult_index_column,
  date_column,
  id_column,
  start_formula = ~1,
  duration_formula = ~1,
  sigma_formula = ~1,
  ranef_factor_column,
  ranef_components = c("start", "duration"),
  flat_prior = FALSE,
  lumped = FALSE,
  use_phi_approx = FALSE,
  beta_sd = 0,
  data,
  init = "auto",
  log_lik = TRUE,
  standata_only = FALSE,
  ...
)

Arguments

moult_index_column

the name of the column in data containing moult indices, i.e. a numeric vector of (linearised) moult scores: 0 = old plumage, 1 = new plumage
date_column

the name of the column in data containing sampling dates, encoded as days since an arbitrary reference date (numeric vector)
id_column

factor identifier for within-season individual recaptures
start_formula

model formula for start date
duration_formula

model formula for duration
sigma_formula

model formula for start date sigma
ranef_factor_column

the name of a factor column in data containing year identifiers
ranef_components

character vector specifying which linear predictors receive annual random intercepts. Any combination of "start" (start date) and "duration". Defaults to c("start", "duration") (both).
flat_prior

logical; use flat (uniform) priors on start date and duration intercepts? Defaults to FALSE (weakly informative normal priors)
lumped

logical; use the lumped (Type 2L) likelihood where pre- and post-moult birds are treated as indistinguishable? Defaults to FALSE
use_phi_approx

logical; use Phi_approx instead of Phi for computational efficiency? Defaults to FALSE
beta_sd

use zero-centred normal priors for regression coefficients other than intercepts? If <= 0 Stan's default improper flat priors are used
data

input data frame
init

specification of initial values. Can be "auto" for an automatic guess based on the data, or any permitted rstan::sampling option
log_lik

logical; retain pointwise log-likelihood in output? Enables model comparison via the loo package. Defaults to TRUE
standata_only

logical; if TRUE, return the Stan data list without fitting
...

arguments passed to rstan::sampling (e.g. iter, chains)

Value

When standata_only = FALSE, an object of class moultmcmc; otherwise the Stan data list

Bayesian inference for the Type 5 moult model with repeat measures and an additional annual random intercept

Description

Bayesian inference for the Type 5 moult model with repeat measures and an additional annual random intercept

Usage

uz5_linpred_recap_annual_ranef(
  moult_index_column,
  date_column,
  id_column,
  start_formula = ~1,
  duration_formula = ~1,
  sigma_formula = ~1,
  ranef_factor_column,
  ranef_components = c("start", "duration"),
  beta_sd = 0,
  data,
  init = "auto",
  log_lik = TRUE,
  standata_only = FALSE,
  ...
)

Arguments

moult_index_column

the name the column in data containing moult indices, i.e. a numeric vector of (linearized) moult scores (0 = old plumage,1 = new plumage).
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

factor identifier. Usually a season-individual combination to encode within-season recaptures
start_formula

model formula for start date
duration_formula

model formula for duration
sigma_formula

model formula for start date sigma
ranef_factor_column

the name of a factor column in data that contains factor values representing the levels of a random effect
ranef_components

character vector specifying which linear predictors receive annual random intercepts. Any combination of "start" (start date) and "duration". Defaults to c("start", "duration") (both).
beta_sd

use zero-centred normal priors for regression coefficients other than intercepts? If <= 0 the stan default of improper flat priors is used.
data

Input data frame
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.
log_lik

boolean retain pointwise log-likelihood in output? This enables model assessment and selection via the loo package. Defaults to true, can lead to very large output arrays if sample size is large.
standata_only

logical; if TRUE, return the Stan data list (standata) without fitting the model.
...

Arguments passed to rstan::sampling (e.g. iter, chains).

Value

When standata_only = FALSE, an object of class stanfit returned by rstan::sampling; otherwise the Stan data list (standata).