Learn R Programming

secr (version 4.6.10)

derived: Derived Parameters of Fitted SECR Model

Description

Compute derived parameters of spatially explicit capture-recapture model. Density is a derived parameter when a model is fitted by maximizing the conditional likelihood. So also is the effective sampling area (in the sense of Borchers and Efford 2008).

Usage

derived(object, ...)

# S3 method for secr derived(object, sessnum = NULL, groups = NULL, alpha = 0.05, se.esa = FALSE, se.D = TRUE, loginterval = TRUE, distribution = NULL, ncores = NULL, bycluster = FALSE, ...)

# S3 method for secrlist derived(object, sessnum = NULL, groups = NULL, alpha = 0.05, se.esa = FALSE, se.D = TRUE, loginterval = TRUE, distribution = NULL, ncores = NULL, bycluster = FALSE, ...)

esa(object, sessnum = 1, beta = NULL, real = NULL, noccasions = NULL, ncores = NULL)

Value

Dataframe with one row for each derived parameter (`esa', `D') and columns as below

estimateestimate of derived parameter
SE.estimatestandard error of the estimate
lcllower 100(1--alpha)% confidence limit
uclupper 100(1--alpha)% confidence limit
CVnrelative SE of number observed (Poisson or binomial assumption)
CVarelative SE of effective sampling area
CVDrelative SE of density estimate

For a multi-session or multi-group analysis the value is a list with one component for each session and group.

The result will also be a list if object is an `secrlist'.

Arguments

object

secr object output from secr.fit, or an object of class c("secrlist", "list")

sessnum

index of session in object$capthist for which output required

groups

vector of covariate names to define group(s) (see Details)

alpha

alpha level for confidence intervals

se.esa

logical for whether to calculate SE(mean(esa))

se.D

logical for whether to calculate SE(D-hat)

loginterval

logical for whether to base interval on log(D)

distribution

character string for distribution of the number of individuals detected

ncores

integer number of threads used for parallel processing

bycluster

logical; if TRUE results are reported separately for each cluster of detectors

beta

vector of fitted parameters on transformed (link) scale

real

vector of `real' parameters

noccasions

integer number of sampling occasions (see Details)

...

other arguments (not used)

Warning

derived() may be applied to detection models fitted by maximizing the full likelihood (CL = FALSE). However, models using g (groups) will not be handled correctly.

Details

The derived estimate of density is a Horvitz-Thompson-like estimate: $$\hat{D} = \sum\limits _{i=1}^{n} {a_i (\hat{\theta})^{-1}}$$ where \(a_i (\hat{\theta})\) is the estimate of effective sampling area for animal \(i\) with detection parameter vector \(\theta\).

A non-null value of the argument distribution overrides the value in object$details. The sampling variance of \(\hat{D}\) from secr.fit by default is spatially unconditional (distribution = "Poisson"). For sampling variance conditional on the population of the habitat mask (and therefore dependent on the mask area), specify distribution = "binomial". The equation for the conditional variance includes a factor \((1 - a/A)\) that disappears in the unconditional (Poisson) variance (Borchers and Efford 2007). Thus the conditional variance is always less than the unconditional variance. The unconditional variance may in turn be an overestimate or (more likely) an underestimate if the true spatial variance is non-Poisson.

Derived parameters may be estimated for population subclasses (groups) defined by the user with the groups argument. Each named factor in groups should appear in the covariates dataframe of object$capthist (or each of its components, in the case of a multi-session dataset).

esa is used by derived to compute individual-specific effective sampling areas: $$a_i (\hat{\theta}) = \int _A \: p.(\mathbf{X};\mathbf{z}_i, \mathbf{\hat{\theta}}) \; \mathrm{d} \mathbf{X}$$ where \(p.(\mathbf{X})\) is the probability an individual at X is detected at least once and the \(\mathbf{z}_i\) are optional individual covariates. Integration is over the area \(A\) of the habitat mask.

The argument noccasions may be used to vary the number of sampling occasions; it works only when detection parameters are constant across individuals and across time.

Setting ncores = NULL uses the existing value from the environment variable RCPP_PARALLEL_NUM_THREADS (see setNumThreads).

The effective sampling area `esa' (\(a(\hat{\theta})\)) reported by derived is equal to the harmonic mean of the \(a_i (\hat{\theta})\) (arithmetic mean prior to version 1.5). The sampling variance of \(a(\hat{\theta})\) is estimated by $$\widehat{\mbox{var}}(a(\hat{\theta})) = \hat{G}_\theta^T \hat{V}_\theta \hat{G}_\theta, $$ where \(\hat{V}\) is the asymptotic estimate of the variance-covariance matrix of the beta detection parameters (\(\theta\)) and \(\hat{G}\) is a numerical estimate of the gradient of \(a(\theta)\) with respect to \(\theta\), evaluated at \(\hat{\theta}\).

A 100(1--alpha)% asymptotic confidence interval is reported for density. By default, this is asymmetric about the estimate because the variance is computed by backtransforming from the log scale. You may also choose a symmetric interval (variance obtained on natural scale).

The vector of detection parameters for esa may be specified via beta or real, with the former taking precedence. If neither is provided then the fitted values in object$fit$par are used. Specifying real parameter values bypasses the various linear predictors. Strictly, the `real' parameters are for a naive capture (animal not detected previously).

The computation of sampling variances is relatively slow and may be suppressed with se.esa and se.D as desired.

For computing derived across multiple models in parallel see par.derived.

References

Borchers, D. L. and Efford, M. G. (2007) Supplements to Biometrics paper. Available online at https://www.otago.ac.nz/density/.

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximum likelihood methods for capture--recapture studies. Biometrics, 64, 377--385.

Huggins, R. M. (1989) On the statistical analysis of capture experiments. Biometrika 76, 133--140.

See Also

predict.secr, print.secr, secr.fit, empirical.varD par.derived

Examples

Run this code

if (FALSE) {
## extract derived parameters from a model fitted previously
## by maximizing the conditional likelihood 
derived (secrdemo.CL)

## what happens when sampling variance is conditional on mask N?
derived(secrdemo.CL, distribution = "binomial")
## fitted g0, sigma
esa(secrdemo.CL)
## force different g0, sigma
esa(secrdemo.CL, real = c(0.2, 25))
}

Run the code above in your browser using DataLab