mark: Interface to MARK for fitting capture-recapture models

Description Usage Arguments Details Value Note Author(s) See Also Examples

View source: R/mark.R

Description

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

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
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, events = NULL, nodes = 101,
  useddl = FALSE, check.model = FALSE)

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

se

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

events

vector of character events for Hidden Markov models

nodes

number of integration nodes for individual random effects (min 15, max 505, default 101)

useddl

if TRUE and no rows of ddl are missing (deleted) then it will use ddl in place of full.ddl that is created internally.

check.model

if TRUE, code does an internal consistency check between PIMs and design data when making model.

Details

This function acts as an interface to the FORTRAN program MARK written by Gary White (http://www.phidot.org/software/mark/). 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.

Value

model: a MARK object containing output and extracted results. It is a list with the following elements

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

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
chat

over-dispersion constant; if not present assumed to be 1

Note

It is assumed that MARK.EXE is located in directory "C:/Program Files/Mark". If it is in a different location set the variable MarkPath to the directory location. For example, seting MarkPath="C:/Mark/" at the R prompt will assign run "c:/mark/mark.exe" to do the analysis. If you have chosen a non-default path for Mark.exe, MarkPath needs to be defined for each R session. It is easiest to do this assignment automatically by putting the MarkPath assignment into your .First function which is run each time an R session is initiated. In addition to MarkPath, the variable MarkViewer can be assigned to a program other than notepad.exe (see print.mark).

Author(s)

Jeff Laake

See Also

make.mark.model, run.mark.model, make.design.data, process.data, summary.mark

Examples

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

RMark documentation built on Nov. 7, 2019, 1:06 a.m.

Related to mark in RMark...