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] (YOUR-ORCID-ID)
Maintainer: Philipp Boersch-Supan <[email protected]>
License: MIT + file LICENSE
Version: 0.0.0.9000
Built: 2025-02-23 05:56:41 UTC
Source: https://github.com/pboesu/moultmcmcExtra

Help Index

The 'moultmcmcExtra' package.

Description

A DESCRIPTION OF THE PACKAGE

References

Stan Development Team (NA). RStan: the R interface to Stan. R package version 2.26.11. https://mc-stan.org

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_raneff(..., 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,
  year_factor_column,
  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
year_factor_column

the name of a factor column in data that contains year_factor values
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).

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 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_raneff(
  moult_index_column,
  date_column,
  id_column,
  start_formula = ~1,
  duration_formula = ~1,
  sigma_formula = ~1,
  year_factor_column,
  beta_sd = 0,
  data,
  init = "auto",
  log_lik = TRUE,
  ...
)

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
year_factor_column

the name of a factor column in data that contains year_factor values
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.
...

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

Value

An object of class stanfit returned by rstan::sampling