make.capthist | R Documentation |
Form a capthist
object from a data frame of capture records and a traps
object.
make.capthist(captures, traps, fmt = c("trapID", "XY"), noccasions = NULL,
covnames = NULL, bysession = TRUE, sortrows = TRUE,
cutval = NULL, tol = 0.01, snapXY = FALSE, noncapt = "NONE", signalcovariates)
captures |
dataframe of capture records in one of two possible formats (see Details) |
traps |
object of class |
fmt |
character string for capture format. |
noccasions |
number of occasions on which detectors were operated |
covnames |
character vector of names for individual covariate fields |
bysession |
logical, if true then ID are made unique by session |
sortrows |
logical, if true then rows are sorted in ascending order of animalID |
cutval |
numeric, threshold of signal strength for ‘signal’ detector type |
tol |
numeric, snap tolerance in metres |
snapXY |
logical; if TRUE then fmt = 'XY' uses nearest trap within tol for non-polygon detectors |
noncapt |
character value; animal ID used for ‘no captures’ |
signalcovariates |
character vector of field names from ‘captures’ |
make.capthist
is the most flexible way to prepare data for
secr.fit
. See read.capthist
for a more streamlined
way to read data from text files for common detector types. Each row of
the input data frame captures
represents a detection on one
occasion. The capture data frame may be formed from a text file with
read.table
.
Input formats are based on the Density software (Efford 2012; see also
secr-datainput.pdf). If fmt =
"XY"
the required fields are (session, ID, occasion, x, y) in that
order. If fmt = "trapID"
the required fields are (session, ID,
occasion, trap), where trap
is the numeric index of the relevant
detector in traps
. session
and ID
may be
character-, vector- or factor-valued; other required fields are
numeric. Fields are matched by position (column number), not by
name. Columns after the required fields are interpreted as individual
covariates that may be continuous (e.g., size) or categorical (e.g.,
age, sex).
If captures
has data from multiple sessions then traps
may
be either a list of traps
objects, one per session, or a single
traps
object that is assumed to apply throughout. Similarly,
noccasions
may be a vector specifying the number of occasions in
each session.
Covariates are assumed constant for each individual; the first
non-missing value is used. The length of covnames
should equal the
number of covariate fields in captures
.
bysession
takes effect when the same individual is detected in
two or more sessions: TRUE results in one capture history per session,
FALSE has the effect of generating a single capture history (this is not
appropriate for the models currently provided in secr).
Deaths are coded as negative values in the occasion field of
captures
. Occasions should be numbered 1, 2, ..., noccasions. By
default, the number of occasions is the maximum value of ‘occasion’ in
captures
.
Signal strengths may be provided in the fifth (fmt = trapID) or sixth (fmt = XY) columns. Detections with signal strength missing (NA) or below ‘cutval’ are discarded.
A session may result in no detections. In this case a null line is
included in captures
using the animal ID field given by
noncapt
, the maximum occasion number, and any trapID (e.g. "sess1
NONE 5 1" for a 5-occasion session) (or equivalently "sess1 NONE 5 10
10" for fmt = XY).
Nonspatial data (Session, AnimalID, Occasion and possibly individual covariates) may be entered by omitting the ‘traps’ argument or setting it to NULL.
An object of class capthist
(a matrix or array of
detection data with attributes for detector positions etc.). For
‘single’ and ‘multi’ detectors this is a matrix with one row per animal
and one column per occasion (dim(capthist)=c(nc,noccasions)); each
element is either zero (no detection) or a detector number (the row
number in traps
not the row name). For ‘proximity’
detectors capthist
is an array of values {-1, 0, 1} and
dim(capthist)=c(nc,noccasions,ntraps). The number of animals nc
is determined from the input, as is noccasions
if it is not specified.
traps
, covariates
and other data are retained as
attributes of capthist
.
Deaths during the experiment are represented as negative values in capthist
.
For ‘signal’ and ‘signalnoise’ detectors, the columns of captures
identified in signalcovariates
are saved along with signal
strength measurements in the attribute ‘signalframe’.
If the input has data from multiple sessions then the output is an
object of class c("capthist", "list") comprising a list of single-session
capthist
objects.
make.capthist
requires that the data for captures
and
traps
already exist as R objects. To read data from external
(text) files, first use read.table
and read.traps
, or try
read.capthist
for a one-step solution.
Prior to secr 4.4.0, occasional valid records for "multi" and "single" detectors were rejected as duplicates.
From secr 4.5.0, ‘snapXY’ works for transects as well as point detectors.
Efford, M. G. (2012) DENSITY 5.0: software for spatially explicit capture–recapture. Department of Mathematics and Statistics, University of Otago, Dunedin, New Zealand. https://www.otago.ac.nz/density/.
capthist
, traps
,
read.capthist
, secr.fit
,
sim.capthist
## peek at demonstration data
head(captXY)
head(trapXY)
demotraps <- read.traps(data = trapXY)
demoCHxy <- make.capthist (captXY, demotraps, fmt = "XY")
demoCHxy ## print method for capthist
plot(demoCHxy) ## plot method for capthist
summary(demoCHxy) ## summary method for capthist
## To enter `count' data without manually repeating rows
## need a frequency vector f, length(f) == nrow(captXY)
n <- nrow(captXY)
f <- sample (1:5, size = n, prob = rep(0.2,5), replace = TRUE)
## repeat rows as required...
captXY <- captXY[rep(1:n, f),]
counttraps <- read.traps(data = trapXY, detector = "count")
countCH <- make.capthist (captXY, counttraps, fmt = "XY")
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.