secr (version 4.6.9)

subset.capthist: Subset or Split capthist Object

Description

Create a new capthist object or list of objects by selecting rows (individuals), columns (occasions) and traps from an existing capthist object.

Usage

# S3 method for capthist
subset(x, subset = NULL, occasions = NULL, traps = NULL,
    sessions = NULL, cutval = NULL, dropnullCH = TRUE, dropnullocc = FALSE,
    dropunused = TRUE, droplowsignals = TRUE, dropNAsignals = FALSE,
    cutabssignal = TRUE, renumber = FALSE, ...)
# S3 method for capthist
split(x, f, drop = FALSE, prefix = "S", bytrap = FALSE, 
 byoccasion = FALSE, ...)

Value

capthist object with the requested subset of observations, or a list of such objects (i.e., a multi-session capthist object). List input results in list output, except when a single session is selected.

Arguments

x

object of class capthist

subset

vector of subscripts to select rows (individuals) (see Details for variations)

occasions

vector of subscripts to select columns (occasions)

traps

vector of subscripts to select detectors (traps)

sessions

vector of subscripts to select sessions

cutval

new threshold for signal strength

dropnullCH

logical for whether null (all-zero) capture histories should be dropped

dropnullocc

logical for whether occasions with no detections should be dropped

dropunused

logical for whether never-used detectors should be dropped

droplowsignals

logical for whether cutval should be applied at each microphone rather than to sound as a whole

dropNAsignals

logical for whether detections with missing signal should be dropped

cutabssignal

logical for whether to apply cutval to absolute signal strength or the difference between signal and noise

renumber

logical for whether row.names should be replaced with sequence number in new capthist

f

factor or object that may be coerced to a factor

drop

logical indicating if levels that do not occur should be dropped (if f is a factor)

prefix

a character prefix to be used for component names when values of f are numeric

bytrap

logical; if TRUE then each level of f identifies traps to include

byoccasion

logical; if TRUE then each level of f identifies occasions to include

...

other arguments passed to subset.capthist (split.capthist) or to optional subset function (subset.capthist)

Warning

split.capthist does not work for mark--resight data.

Details

Subscript vectors may be either logical- (length equal to the relevant dimension of x), character- or integer-valued. Subsetting is applied to attributes (e.g. covariates, traps) as appropriate. The default action is to include all animals, occasions, and detectors if the relevant argument is omitted.

When traps is provided, detections at other detectors are set to zero, as if the detector had not been used, and the corresponding rows are removed from traps. If the detector type is `proximity' then selecting traps also reduces the third dimension of the capthist array.

split generates a list in which each component is a capthist object. Each component corresponds to a level of f. Multi-session capthists are accepted in secr >= 4.4.0; f should then be a list of factors with one component per session and the same levels in all.

To combine (pool) occasions use reduce.capthist. There is no equivalent of unlist for lists of capthist objects.

The effect of droplowsignals = FALSE is to retain below-threshold measurements of signal strength on all channels (microphones) as long as the signal is above cutval on at least one. In this case all retained sounds are treated as detected on all microphones. This fails when signals are already missing on some channels.

Subsetting is awkward with multi-session input when the criterion is an individual covariate. See the Examples for one way this can be tackled.

See Also

capthist, rbind.capthist, reduce.capthist

Examples

tempcapt <- sim.capthist (make.grid(nx = 6, ny = 6), noccasions = 6)
summary(subset(tempcapt, occasions = c(1,3,5)))

## Consider `proximity' detections at a random subset of detectors
## This would not make sense for `multi' detectors, as the 
## excluded detectors influence detection probabilities in 
## sim.capthist.

tempcapt2 <- sim.capthist (make.grid(nx = 6, ny = 6, 
    detector = "proximity"), noccasions = 6)
tempcapt3 <- subset(tempcapt2, traps = sample(1:36, 18, 
    replace = FALSE))
summary(tempcapt3)
plot(tempcapt3)

tempcapt4 <- split (tempcapt2, f = sample (c("A","B"), 
    nrow(tempcapt2), replace = TRUE))
summary(tempcapt4)

## Split out captures on alternate rows of a grid
tempcapt5 <- split(captdata, f = rep(1:2, 50), bytrap = TRUE)
summary(tempcapt5)

## Divide one session into two by occasion
tempcapt6 <- split(captdata, f = factor(c(1,1,2,2,2)), byoccasion = TRUE)
summary(tempcapt6)

## Applying a covariate criterion across all sessions of a
## multi-session capthist object e.g. selecting male ovenbirds from the
## 2005--2009 ovenCH dataset. We include a restriction on occasions
## to demonstrate the use of 'MoreArgs'. Note that mapply() creates a
## list, and the class of the output must be restored manually.

ovenCH.males <- mapply(subset, ovenCH,
    subset = lapply(ovenCH, function(x) covariates(x)$Sex == "M"),
    MoreArgs = list(occasions = 1:5))
class(ovenCH.males) <- class(ovenCH)
summary(ovenCH.males, terse = TRUE)

## A simpler approach using a function to define subset
subsetfn <- function(x, sex) covariates(x)$Sex == sex
ovenCH.males <- subset(ovenCH, subset = subsetfn, sex = "M")
summary(ovenCH.males, terse = TRUE)