cpm {GenEst}

Fit cp carcass persistence models

Description

Carcass persistence is modeled as survival function where the one or both parameter(s) can depend on any number of covariates. Format and usage parallel that of common R functions such as lm, glm, and gam. However, the input data (data) are structured differently to accommodate the survival model approach (see "Details"), and model formulas may be entered for both l ("location") and s ("scale").

Usage

cpm(
  formula_l,
  formula_s = NULL,
  data,
  left,
  right,
  dist = "weibull",
  allCombos = FALSE,
  sizeCol = NULL,
  CL = 0.9,
  quiet = FALSE
)

cpm0(
  formula_l,
  formula_s = NULL,
  data = NULL,
  left = NULL,
  right = NULL,
  dist = "weibull",
  CL = 0.9,
  quiet = FALSE
)

cpmSet(
  formula_l,
  formula_s = NULL,
  data,
  left,
  right,
  dist = c("exponential", "weibull", "lognormal", "loglogistic"),
  CL = 0.9,
  quiet = FALSE
)

cpmSize(
  formula_l,
  formula_s = NULL,
  data,
  left,
  right,
  dist = c("exponential", "weibull", "lognormal", "loglogistic"),
  sizeCol = NULL,
  allCombos = FALSE,
  CL = 0.9,
  quiet = FALSE
)

Arguments

formula_l

Formula for location; an object of class "formula" (or one that can be coerced to that class): a symbolic description of the model to be fitted. Details of model specification are given under "Details".

formula_s

Formula for scale; an object of class "formula" (or one that can be coerced to that class): a symbolic description of the model to be fitted. Details of model specification are given under "Details".

data

Data frame with results from carcass persistence trials and any covariates included in formula_l or formula_s (required).

left

Name of columns in data where the time of last present observation is stored.

right

Name of columns in data where the time of first absent observation is stored.

dist

Distribution name ("exponential", "weibull", "loglogistic", or "lognormal")

allCombos

logical. If allCombos = FALSE, then the single model expressed by formula_l and formula_s is fit using a call to cpm0. If allCombos = TRUE, a full set of cpm submodels derived from combinations of the given covariates for p and k is fit. For example, submodels of formula_l = p ~ A * B would be p ~ A * B, p ~ A + B, p ~ A, p ~ B, and p ~ 1. Models for each pairing of a p submodel with a k submodel are fit via cpmSet, which fits each model combination using successive calls to cpm0, which fits a single model.

sizeCol

character string. The name of the column in data that gives the size class of the carcasses in the field trials. If sizeCol = NULL, then models are not segregated by size. If a sizeCol is provided, then separate models are fit for the data subsetted by sizeCol.

CL

confidence level

quiet

Logical indicator of whether or not to print messsages

Details

The probability of a carcass persisting to a particular time is dictated by the specific distribution chosen and its underlying location (l) and scale (s) parameters (for all models except the exponential, which only has a location parameter). Both l and s may depend on covariates such as ground cover, season, species, etc., and a separate model format (formula_l and formula_s) may be entered for each. The models are entered as they would be in the familiar lm or glm functions in R. For example, l might vary with A, B, and C, while k varies only with A. A user might then enter p ~ A + B + C for formula_l and k ~ A for formula_s. Other R conventions for defining formulas may also be used, with A:B for the interaction between covariates A and B and A * B as short-hand for A + B + A:B.

Carcass persistence data must be entered in a data frame with data in each row giving the fate of a single carcass in the trials. There must be a column for each of the last time the carcass was observed present and the first time the carcass was observed absent (or NA if the carcass was always present). Additional columns with values for categorical covariates (e.g., visibility = E, M, or D) may also be included.

Value

an object of an object of class cpm, cpmSet, cpmSize, or cpmSetSize.

cpm0()

returns a cpm object, which is a description of a single, fitted pk model. Due to the large number and complexity of components of acpm model, only a subset of them is printed automatically; the rest can be viewed/accessed via the $ operator if desired. These are described in detail in the 'cpm Components' section.

cpmSet()

returns a list of cpm objects, one for each of the submodels, as described with parameter allCombos = TRUE.

cpmSize()

returns a list of cpmSet objects (one for each 'size') if allCombos = T, or a list of cpm objects (one for each 'size') if allCombos = T

cpm

returns a cpm, cpmSet, cpmSize, or cpmSetSize object:

• cpm object if allCombos = FALSE, sizeCol = NULL

• cpmSet object if allCombos = TRUE, sizeCol = NULL

• cpmSize object if allCombos = FALSE, sizeCol != NULL

• cpmSetSize object if allCombos = TRUE, sizeCol != NULL

cpm Components

The following components of a cpm object are displayed automatically:

call

the function call to fit the model

formula_l

the model formula for the p parameter

formula_s

the model formula for the k parameter

distribution

distribution used

predictors

list of covariates of l and/or s

AICc

the AIC value as corrected for small sample size

convergence

convergence status of the numerical optimization to find the maximum likelihood estimates of p and k. A value of 0 indicates that the model was fit successfully. For help in deciphering other values, see optim.

cell_ls

summary statistics for estimated cellwise l and s, including the medians and upper & lower bounds on CIs for each parameter, indexed by cell (or combination of covariate levels).

cell_ab

summary statistics for estimated cellwise pda and pdb, including the medians and upper & lower bounds on CIs for each parameter, indexed by cell (or combination of covariate levels).

cell_desc

Descriptive statistics for estimated cellwise median persistence time and rI for search intervals of 1, 3, 7 14, and 28 days, where rI is the probability of that carcass that arrives at a uniform random time in within a search interval of I days persists until the first search after arrival.

The following components are not printed automatically but can be accessed via the $ operator:

data

the data used to fit the model

betahat_l

parameter estimates for the terms in the regression model for for l

betahat_s

parameter estimates for the terms in the regression model for for s. If dist = "exponential", s is set at 1 and not calculated.

varbeta

the variance-covariance matrix of the estimators for c(betahat_l, betahat_s.

cellMM_l

a cellwise model (design) matrix for covariate structure of l_formula

cellMM_s

a cellwise model(design) matrix for covariate structure of s_formula

levels_l

all levels of each covariate of l

levels_s

all levels of each covariate of s

nbeta_l

number of parameters fit for l

nbeta_s

number of parameters fit for s

cells

cell structure of the cp-model, i.e., combinations of all levels for each covariate of p and k. For example, if covar1 has levels "a", "b", and "c", and covar2 has levels "X" and "Y", then the cells would consist of a.X, a.Y, b.X, b.Y, c.X, and c.Y.

ncell

total number of cells

predictors_l

list of covariates of l

predictors_s

list of covariates of s

observations

observations used to fit the model

carcCells

the cell to which each carcass belongs

AIC

the AIC value for the fitted model

CL

the input CL

Advanced

cpmSize may also be used to fit a single model for each size class if allCombos = FALSE. To do so, formula_l, formula_s, and dist be named lists with names matching the sizes listed in unique(data[, sizeCol]). The return value is then a list of cpm objects, one for each size.

Examples

 head(data(wind_RP))
 mod1 <- cpm(formula_l = l ~ Season, formula_s = s ~ 1, data = wind_RP$CP,
   left = "LastPresent", right = "FirstAbsent")
 class(mod1)
 mod2 <- cpm(formula_l = l ~ Season, formula_s = s ~ 1, data = wind_RP$CP,
   left = "LastPresent", right = "FirstAbsent", allCombos = TRUE)
 class(mod2)
 names(mod2)
 class(mod2[[1]])
 mod3 <- cpm(formula_l = l ~ Season, formula_s = s ~ 1, data = wind_RP$CP,
   left = "LastPresent", right = "FirstAbsent",
   allCombos = TRUE, sizeCol = "Size")
 class(mod3)
 names(mod3)
 class(mod3[[1]])
 class(mod3[[1]][[1]])