secr (version 5.0.0)

read.traps: Read Detector Data From File

Description

Construct an object of class traps with detector locations from a text file or data frame. Usage per occasion and covariates may be included. Data may also be read from an Excel spreadsheet (see secr-datainput.pdf).

Usage

read.traps(file = NULL, data = NULL, detector = "multi", covnames =
NULL, binary.usage = TRUE, markocc = NULL, trapID = NULL, ...)

Value

An object of class traps comprising a data frame of x- and y-coordinates, the detector type (`single', `multi', `proximity', `count', `polygon' etc.), and possibly other attributes.

Arguments

file

character string with name of text file

data

data frame of detector coordinates

detector

character string for detector type

covnames

character vector of names for detector covariate fields

binary.usage

logical; if FALSE will read usage fields as continuous effort

markocc

integer vector distinguishing marking occasions (1) from sighting occasions (0)

trapID

character column containing detector names (see Details)

...

other arguments to pass to read.table

Details

Reads a text file in which the first column is a character string (see Note) identifying a detector and the next two columns are its x- and y-coordinates, separated by white space. The coordinates optionally may be followed by a string of codes `0' or `1' indicating whether the detector was operated on each occasion. Trap-specific covariates may be added at the end of the line preceded by `/'. This format is compatible with the Density software (Efford 2012), except that all detectors are assumed to be of the same type (usage codes greater than 1 are treated as 1), and more than one covariate may be specified.

If file is missing then x-y coordinates will be taken instead from data, which should include columns `x' and `y'. Row names of data are read as detector identifiers unless trapID is specified. This option does not allow for covariates or usage, but they maybe added later.

detector specifies the behaviour of the detector following Efford et al. (2009). `single' refers to a trap that is able to catch at most one animal at a time; `multi' refers to a trap that may catch more than one animal at a time. For both `single' and `multi' detectors a trapped animals can appear at only one detector per occasion. Detectors of type `proximity', such as camera traps and hair snags for DNA sampling, allow animals to be recorded at several detectors on one occasion. See detector for further detector types.

For polygon and transect detector types, each line corresponds to a vertex and starts with a code to identify the polygon or transect (hence the same code appears on 2 or more lines). For input from a dataframe the code column should be named `polyID'. Also, usage and covariates are for the polygon or transect as a whole and not for each vertex. Usage and covariates are appended to the end of the line, just as for point detectors (traps etc.). The usage and covariates for each polygon or transect are taken from its first vertex. Although the end-of-line strings of other vertices are not used, they cannot be blank and should use the same spacing as the first vertex.

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

Efford, M. G., Borchers D. L. and Byrom, A. E. (2009) Density estimation by spatially explicit capture-recapture: likelihood-based methods. In: D. L. Thomson, E. G. Cooch and M. J. Conroy (eds) Modeling Demographic Processes in Marked Populations. Springer, New York. Pp. 255--269.

See Also

traps, make.grid, detector

Examples

if (FALSE) {
## "trap.txt" should have lines like this 
# 1     365     365
# 2     365     395
# 3     365     425
# etc.
## in following, replace file name with a valid local name
filename <- paste0(system.file("extdata", package = "secr"), '/trap.txt')
tr1 <- read.traps (filename, detector = "proximity")
summary(tr1)

## Or if we have a dataframe of coordinates...
mytrapdf <- data.frame(x = c(365,365,365), y = c(365,395,425),
                       row.names = c('A','B','C'))
mytrapdf
#     x   y
# A 365 365
# B 365 395
# C 365 425
## ...then we can convert it to a `traps' object with
tr2 <- read.traps(data = mytrapdf)
summary(tr2)

}