mark: Interface to MARK for fitting capture-recapture models

In RMark: R Code for Mark Analysis

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 = TRUE,
  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(starting with version 3.0.0 setting reverse=TRUE is not allowed)
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
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
output	base portion of filenames for input,output, vc and residual files output from MARK.EXE

Note

It is assumed that MARK.EXE is located in directory "C:/Program Files/Mark". There are now mark32.exe and mark64.exe files and the 32 or 64 bit versions of R determine which is used. You can force one or the other by naming the file mark.exe but probably no reason to do so. 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/markxx.exe" where xx is 32 or 64 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

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

RMark documentation built on Aug. 14, 2022, 1:05 a.m.