DENSITY: Import or export data

In secr: Spatially Explicit Capture-Recapture

Import or export data

Description

Data in the DENSITY formats for capture data and trap layouts may be imported as a capthist object for analysis in secr. Data in a capthist object may also be exported in these formats for use in DENSITY (Efford 2012). read.capthist inputs data from text files and constructs a capthist object in one step using the functions read.traps and make.capthist. Data may also be read from Excel spreadsheets if the package readxl is installed (see secr-datainput.pdf).

Usage

read.capthist(captfile, trapfile, detector = "multi", fmt = c("trapID","XY"),
    noccasions = NULL, covnames = NULL, trapcovnames = NULL,
    cutval = NULL, verify = TRUE, noncapt = "NONE", tol = 0.01, snapXY = FALSE, 
    markocc = NULL, ...)

write.capthist(object, filestem = deparse(substitute(object)),
     sess = "1", ndec = 2, covariates = FALSE, tonumeric = TRUE, ...)

Arguments

captfile	name of capture data file
trapfile	name of trap layout file or (for a multi-session captfile) a vector of file names, one for each session
detector	character value for detector type (‘single’, ‘multi’, ‘proximity’, etc.)
fmt	character value for capture format (‘trapID’ or ‘XY’)
noccasions	number of occasions on which detectors were operated
covnames	character vector of names for individual covariate fields in ‘captfile’
trapcovnames	character vector of names for detector covariate fields in ‘trapfile’
cutval	numeric, threshold of signal strength for ‘signal’ detector type
verify	logical if TRUE then the resulting capthist object is checked with verify
noncapt	character value; animal ID used for ‘no captures’
tol	numeric, snap tolerance in metres
snapXY	logical; if TRUE then fmt = 'XY' uses nearest trap within tol
markocc	integer vector distinguishing marking occasions (1) from sighting occasions (0)
...	other arguments passed to read.table, write.table and count.fields
object	capthist object with the captures and trap locations to export
filestem	character value used to form names of output files
sess	character session identifier
ndec	number of digits after decimal point for x,y coordinates
covariates	logical or a character vector of covariates to export
tonumeric	logical for whether factor and character covariates should be converted to numeric values on output

Details

read.capthist

captfile should record one detection on each line. A detection comprises a session identifier, animal identifier, occasion number (1, 2,...,S where S is the number of occasions), and a detector identifier (fmt = "trapID") or X- and Y-coordinates (fmt = "XY"). Each line of trapfile has a detector identifier and its X- and Y-coordinates. In either file type the identifiers (labels) may be numeric or alphanumeric values. Values should be separated by blanks or tabs unless (i) the file name ends in ‘.csv’ or (ii) sep = "," is passed in ..., in which case commas are assumed. Blank lines and any text after ‘#’ are ignored. For further details see secr-datainput.pdf, make.capthist and ‘Data formats’ in the help for DENSITY.

The noccasions argument is needed only if there were no detections on the final occasion; it may be a positive integer (constant across all sessions) or a vector of positive integers, one for each session. covnames is needed only when captfile includes individual covariates. Likewise for trapcovnames and detector covariates. Values of noccasions and covnames are passed directly to make.capthist, and trapcovnames is passed to read.traps.

A session identifier is required even for single-session capture data. In the case of data from multiple sessions, trapfile may be a vector of file names, one for each session.

Additional data may be coded as for DENSITY. Specifically, captfile may include extra columns of individual covariates, and trapfile may code varying usage of each detector over occasions and detector covariates.

markocc is needed only if sightings of unmarked animals are potentially recorded on some occasions. If the data span multiple sessions with differing combinations of marking and sighting occasions then markocc may be a list with one vector per session.

The function read.telemetry is a simplified version of read.capthist for telemetry data.

write.capthist

For a single-session analysis, DENSITY requires one text file of capture data and one text file with detector coordinates (the 'trap layout' file). write.capthist constructs names for these files by appending ‘capt.txt’ and ‘trap.txt’ to filestem which defaults to the name of the capthist object. If filestem is empty then output goes to the console.

If object contains multiple sessions with differing traps then a separate trap layout file is exported for each session and each file name includes the session name. All capture data are exported to one file regardless of the number of sessions. The DENSITY format used is ‘TrapID’ except when x-y coordinates are specific to a detection (i.e., polygon and transect detectors).

covariates controls the export of both detector and individual covariates. If it is TRUE or FALSE then it is taken to apply to both. A vector of covariate names is used as a lookup for both detector and capthist covariate fields: covariates are exported if their name matches; this may be used to export any combination of (uniquely named) detector and capthist covariates.

Existing text files will be replaced without warning. In the case of a multi-session capthist file, session names are taken from object rather than sess. Session names are truncated to 17 characters with blanks and commas removed.

To export data in comma-delimited (‘.csv’) format, pass sep = "," in .... The resulting files have extension ‘.csv’ rather than ‘.txt’ and may be opened with spreadsheet software.

Warning

write.capthist does not work for mark–resight data.

Note

The original DENSITY formats accommodate ‘single’, ‘multi’ and ‘proximity’ data. Data for the newer detector types (‘count’, ‘signal’, ‘polygon’, ‘polygonX’, ‘transect’, ‘transectX’ and ‘telemetryonly’) may be input using the DENSITY formats with minor variations. They may also be output with write.capthist, but a warning is given that DENSITY does not understand these data types. See detector and secr-datainput.pdf for more.

The ... argument is useful for some special cases. For example, if your input uses ‘;’ instead of ‘#’ for comments (‘;’ is also valid in DENSITY) then set comment.char = ";" in read.capthist.

In a similar fashion, write comma- or tab-separated values by setting sep = "," or sep = "\t" respectively.

The arguments of count.fields are a subset of those of read.table so ... is limited to any of {sep, quote, skip, blank.lines.skip, comment.char}.

If you fail to set fmt correctly in read.capthist then the error message from verify may be uninformative.

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

read.telemetry, read.traps, make.capthist, write.captures, write.traps, read.table

Examples

## export ovenbird capture histories
## the files "ovenCHcapt.txt" and "ovenCHtrap.txt" are
## placed in the current folder (check with getwd() or dir())

## Not run: 
write.capthist(ovenCH)

## End(Not run)

secr documentation built on Nov. 4, 2024, 9:06 a.m.