mark: Interface to MARK for fitting capture-recapture models

Description

Fits user specified models to various types of capture-recapture data by creating input file and running MARK software and retrieving output

Usage

mark(data, ddl = NULL, begin.time = 1, model.name = NULL, model = "CJS", title = "", model.parameters = list(), initial = NULL, design.parameters = list(), right = TRUE, groups = NULL, age.var = NULL, initial.ages = 0, age.unit = 1, time.intervals = NULL, nocc = NULL, output = TRUE, invisible = TRUE, adjust = TRUE, mixtures = 1, se = FALSE, filename = NULL, prefix = "mark", default.fixed = TRUE, silent = FALSE, retry = 0, options = NULL, brief = FALSE, realvcv = FALSE, delete = FALSE, external = FALSE, profile.int = FALSE, chat = NULL, reverse = FALSE, run = TRUE, input.links = NULL, parm.specific = FALSE, mlogit0 = FALSE, threads = -1, hessian = FALSE, accumulate = TRUE, allgroups = FALSE, strata.labels = NULL, counts = NULL, icvalues = NULL, wrap = TRUE)

Arguments

data

Either the raw data which is a dataframe with at least one column named ch (a character field containing the capture history) or a processed dataframe

ddl

Design data list which contains a list element for each parameter type; if NULL it is created

begin.time

Time of first capture(release) occasion

model.name

Optional name for the model

model

Type of c-r model (eg CJS, Burnham, Barker)

title

Optional title for the MARK analysis output

model.parameters

List of model parameter specifications

initial

Optional vector of named or unnamed initial values for beta parameters or previously run model object

design.parameters

Specification of any grouping variables for design data for each parameter

right

if TRUE, any intervals created in design.parameters are closed on the right and open on left and vice-versa if FALSE

groups

Vector of names factor variables for creating groups

age.var

Optional index in groups vector of a variable that represents age

initial.ages

Optional vector of initial ages for each age level

age.unit

Increment of age for each increment of time

time.intervals

Intervals of time between the capture occasions

nocc

number of occasions for Nest model; either time.intervals or nocc must be specified for this model

output

If TRUE produces summary of model input and model output

invisible

If TRUE, window for running MARK is hidden

adjust

If TRUE, adjusts npar to number of cols in design matrix, modifies AIC and records both

mixtures

number of mixtures for heterogeneity model or number of secondary samples for MultScaleOcc model

if TRUE, se and confidence intervals are shown in summary sent to screen

filename

base filename for files created by MARK.EXE. Files are named filename.*.

prefix

base filename prefix for files created by MARK.EXE; for example if prefix="SpeciesZ" files are named "SpeciesZnnn.*"

default.fixed

if TRUE, real parameters for which the design data have been deleted are fixed to default values

silent

if TRUE, errors that are encountered are suppressed

retry

number of reanalyses to perform with new starting values when one or more parameters are singular

options

character string of options for Proc Estimate statement in MARK .inp file

brief

if TRUE and output=TRUE then a brief summary line is given instead of a full summary for the model

realvcv

if TRUE the vcv matrix of the real parameters is extracted and stored in the model results

delete

if TRUE the output files are deleted after the results are extracted

external

if TRUE the mark object is saved externally rather than in the workspace; the filename is kept in its place

profile.int

if TRUE will compute profile intervals for each real parameter; or you can specify a vector of real parameter indices

chat

value of chat used for profile intervals

reverse

if set to TRUE, will reverse timing of transition (Psi) and survival (S) in Multistratum models

run

if FALSE does not run model after creation

input.links

specifies set of link functions for parameters with non-simplified structure

parm.specific

if TRUE, forces a link to be specified for each parameter

mlogit0

if TRUE, any real parameter that is fixed to 0 and has an mlogit link will have its link changed to logit so it can be simplified

threads

number of cpus to use with mark.exe if positive or number of cpus to remain idle if negative

hessian

if TRUE specifies to MARK to use hessian rather than second partial matrix

accumulate

if TRUE accumulate like data values into frequencies

allgroups

Logical variable; if TRUE, all groups are created from factors defined in groups even if there are no observations in the group

strata.labels

vector of single character values used in capture history(ch) for ORDMS, CRDMS, RDMSOccRepro models; it can contain one more value beyond what is in ch for an unobservable state except for RDMSOccRepro which is used to specify strata ordering (eg 0 not-occupied, 1 occupied no repro, 2 occupied with repro.

counts

named list of numeric vectors (one group) or matrices (>1 group) containing counts for mark-resight models

icvalues

numeric vector of individual covariate values for computation of real values

wrap

if TRUE, data lines are wrapped to be length 80; if length of a row is not a problem set to FALSE and it will run faster

Value

data: name of the processed data frame
model: type of analysis model (see list above)
title: title used for analysis
model.name: descriptive name of model
links: vector of link function(s) used for parameters, one for each row in design matrix or only one if all parameters use the same function
mixtures: number of mixtures in Pledger-style closed capture-recapture models
call: call to make.mark.model used to construct the model
parameters: a list of parameter descriptions including the formula, pim.type, link etc.
model.parameters: the list of parameter descriptions used in the call to mark; this is used only by rerun.mark
time.intervals: Intervals of time between the capture occasions
number.of.groups: number of groups defined in the data
group.labels: vector of labels for the groups
nocc: number of capture occasions
begin.time: single time of vector of times (if different for groups) for the first capture occasion
covariates: vector of covariate names (as strings) used in the model
fixed: dataframe of parameters set at fixed values; index is the parameter index in the full parameter structure and value is the fixed value for the real parameter
design.matrix: design matrix used in the input to MARK.EXE
pims: list of pims used for each parameter including any group or strata designations; each parameter in list is denoted by name and within each parameter one or more sub-lists represent groups and strata if any
design.data: design data used to construct the design matrix
strata.labels: labels for strata if any
mlogit.list: structure used to simplify parameters that use mlogit links
simplify: list containing pim.translation which translate between all different and simplified pims, real.labels which are labels for real parameters for full (non-simplified) pim structure and links the link function names for the full parameter structure
output: base portion of filenames for input,output, vc and residual files output from MARK.EXE
results: List of values extracted from MARK ouput
chat: over-dispersion constant; if not present assumed to be 1

Details

This function acts as an interface to the FORTRAN program MARK written by Gary White (http://www.cnr.colostate.edu/~gwhite/mark/mark.htm). It creates the input file for MARK based on user-specified sub-models (model.parameters) for each of the parameters in the capture-recapture model being fitted to the data. It runs MARK.EXE (see note below) and then imports the text output file and binary variance-covariance file that were created. It extracts output values from the text file and creates a list of results that is returned as part of the list (of class mark) which is the return value for this function.

The models that are currently supported are listed in MarkModels.pdf which you can find in the RMark sub-directory of your R Library. Also, they are listed under Help/Data Types in the MARK interface.

The function mark is a shell that calls 5 other functions in the following order as needed: 1) process.data, 2) make.design.data, 3) make.mark.model, 4) run.mark.model, and 5) summary.mark. A MARK model can be fitted with this function (mark) or by calling the individual functions that it uses. The calling arguments for mark are a compilation of the calling arguments for each of the functions it calls (with some arguments renamed to avoid conflicts). If data is a processed dataframe (see process.data) then it expects to find a value for ddl. Likewise, if the data have not been processed, then ddl should be NULL. This dual calling structure allows either a single call approach for each model or alternatively for the data to be processed and the design data (ddl) to be created once and then a whole series of models can be analyzed without repeating those steps.

For descriptions of the arguments data, begin.time, groups, age.var, initial.ages, age.unit, time.intervals and mixtures see process.data.

For descriptions of ddl, design.parameters=parameters, and right, see make.design.data.

For descriptions of model.name , model, title,model.parameters=parameters , default.fixed , initial, options, see make.mark.model.

And finally, for descriptions of arguments invisible, filename and adjust,see run.mark.model.

output,silent, and retry are the only arguments specific to mark. output controls whether a summary of the model input and output are given(if output=TRUE). silent controls whether errors are shown when fitting a model. retry controls the number of times a model will be refitted with new starting values (uses 0) when some parameters are determined to be non-estimable or at a boundary. The latter is the only time it makes sense to retry with new starting values but MARK cannot discern between these two instances. The indices of the beta parameters that are "singular" are stored in results$singular.

Examples

Run this code


data(dipper)
dipper.Phidot.pdot=mark(dipper,threads=1)

Run the code above in your browser using DataLab

	`lnl`
-2xLog Likelihood value
`npar`	Number of parameters (always the number of columns in design matrix)
	`npar.unadjusted`
number of estimated parameters from MARK if different than npar
`n`	effective sample size
	`AICc`
Small sample corrected AIC using npar
`AICc.unadjusted`	Small sample corrected AIC using npar.unadjusted
	`beta`
data frame of beta parameters with estimate, se, lcl, ucl
`real`	data frame of real parameters with estimate, se, lcl, ucl and fixed
	`beta.vcv`
variance-covariance matrix for beta
`derived`	dataframe of derived parameters if any
	`derived.vcv`
variance-covariance matrix for derived parameters if any
`covariate.values`	dataframe with fields `Variable` and `Value`

which are the covariate names and value used for real parameter
	estimates in the MARK output
	`singular`
indices of beta parameters that are non-estimable or at a boundary
`real.vcv`	variance-covariance matrix for real parameters (simplified) if realvcv=TRUE