subset.capthist {secr} | R Documentation

## 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 class '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 class 'capthist'
    split(x, f, drop = FALSE, prefix = "S", bytrap = FALSE,
     byoccasion = FALSE, ...)

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

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

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 omne way this can be tackled.

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

### See Also

`capthist`, `rbind.capthist`, `reduce.capthist`

### Examples

    tempcapt <- sim.capthist (make.grid(nx=6, ny=6), nocc=6)
    summary(subset(tempcapt, occ=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"), nocc = 6)
    tempcapt3 <- subset(tempcapt2, traps = sample(1:36, 18,
        replace=FALSE))
    summary(tempcapt3)
    plot(tempcapt3)

    split (tempcapt2, f = sample (c("A","B"), nrow(tempcapt2),
        replace = TRUE))

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

    ## 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 resriction 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 the new function option in 3.1.1
    subsetfn <- function(x, sex) covariates(x)$Sex == sex
    ovenCH.males <- subset(ovenCH, subset = subsetfn, sex = "M")
    summary(ovenCH.males, terse = TRUE)

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

[Package secr version 3.2.1 Index]