activityGCMM (version 1.1.1)

GCMM: Generalized circular mixed effect mixture (GCMM) model

Description

Bayesian parametric generalized circular mixed effect mixture models (GCMM) for estimating animal activity curves from camera traps and other nested data structures using JAGS. Data distributions currently supported include von Mises and wrapped Cauchy, with one or two random effects fit as random circular intercepts. The GCMM function automatically selects the number of components for the mixture model (supporting up to 4 mixture components) and runs the model in 'JAGS' through R. The number of clusters can also be manually selected. The function returns the model summary and the activity curve estimated from the circular mixture model, with additional information from the analysis provided in the output as a list of class GCMM.

Package: activityGCMM Version: 1.0.1 Date: 2021-06-06 Author: Liz AD Campbell

Usage

GCMM(
  data,
  RE1,
  RE2 = NULL,
  scale = "2pi",
  kmax = 15,
  family = c("vonmises", "wrappedcauchy"),
  autorun = TRUE,
  minESS = 5000,
  maxrep = 5,
  thin = 2,
  burnin = 5000,
  sample = 5000,
  adapt = 1000,
  n.chains = 3,
  saveREs = FALSE,
  saveResids = FALSE,
  saveclustIDs = FALSE,
  saveYExp = FALSE,
  saveJAGS = TRUE,
  Nclust = "NULL",
  clustmeans = NULL
)

Arguments

data

Vector of observations in radians (0 to 2pi)

RE1

Vector identifying random effect for observations (e.g. camera trap ID)

RE2

Vector identifying second random effect for observations (e.g. study site, year, season, sampling period)

scale

Scale of observations, either 0 to 2pi ("2pi") or -pi to pi ("pi")

kmax

Maximum number to test for vonmises kappa parameter; default=15

family

Probability distribution, either "vonmises" or "wrappedcauchy"

autorun

Logical argument for whether to autmatically extend the analyses to achieve MCMC chain convergence and a specified minimum effective sample size (ESS) for all parameters; default=TRUE

minESS

Minimum effective sample size (ESS) from the posterior distribution desired for all paramerers; default=5000, though a minimum ESS of 10000 is recommended

maxrep

Maximum number of extensions of the analysis if autorun=TRUE; default=5

thin

Thinning rate for MCMC chains, i.e. how many samples are saved. For longer models, thin can be increased to reduce computer memory requirements

burnin

If autojags=FALSE, the burnin for the MCMC chains which are not saved; default=5000

sample

If autojags=FALSE, the number of MCMC samples per chain (which is multiplied by thin); default=10000

adapt

adaptation to use for MCMC chains; default=1000

n.chains

number of MCMC chains; default=3

saveREs

Whether random intercepts are saved in output; recommended to save only one of saveREs, saveResids or saveYExp at one time due to memory limitations

saveResids

Whether model residuals are saved in output; recommended to save only one of saveREs, saveResids or saveYExp at one time due to memory limitations

saveclustIDs

Whether to save component cluster identification for the data points; default=FALSE

saveYExp

Whether expected Y values based on model are saved in output; recommended to save only one of saveREs, saveResids or saveYExp at one time due to memory limitations

saveJAGS

Logical argument of whether to save runjags output; default=FALSE

Nclust

Number of components for mixture models; if not provided, the function will estimate the number of clusters; if provided, values must be provided for clustmeans

clustmeans

A vector equal in length to Nclust of the potential means for each component in the mixture models

Value

Returns object of class GCMM which is a list containing analysis results and details. A plot of the estimated activity curve from the mixed effect mixture model is printed.

output GCMM model output summary

GCMMmixture Vectors of simulated values from mixture model

GCMMcomponents Vectors of simulated values from each component in the mixture model

runjags GCMM model output from JAGS of class runjags from runjags package; see run.jags

Details

The number of clusters is automatically selected based on a Bayesian linear finite normal mixture model via the mclust package. The Bayesian parametric GCMM is fit using 'JAGS' through R using the runjags package.

Examples

# NOT RUN {
data(redfoxsample)
# }
# NOT RUN {
 FoxActivityGCMM<-GCMM(data=redfoxsample$Radians, RE1=redfoxsample$SamplingPeriod, 
    scale=c("2pi"), family="vonmises", autorun=FALSE,
    adapt=0, sample=300, burnin=300, thin=1,n.chains=2  ) 
# }
# NOT RUN {
 
# }