make.capthist {secr} | R Documentation

## Construct capthist Object

### Description

Form a `capthist` object from a data frame of capture records and a `traps` object.

### Usage

    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)

### Arguments

`captures` | dataframe of capture records in one of two possible formats (see Details)
`traps` | object of class `traps` describing an array of passive detectors
`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’

### Details

`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).

### Value

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.

### Note

`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.

### References

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.

### See Also

`capthist`, `traps`, `read.capthist`, `secr.fit`, `sim.capthist`

### Examples

    ## 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")

[Package secr version 3.2.1 Index]