fx.total {secr}

Activity Centres of Detected and Undetected Animals

Description

The summed probability densities of both observed and unobserved individuals are computed for a fitted model and dataset.

Usage

fx.total(object, sessnum = 1, mask = NULL, ncores = NULL, ...)

Arguments

object

a fitted secr model

sessnum

session number if object$capthist spans multiple sessions

mask

x- and y- coordinates of points at which density will be computed

ncores

integer number of threads to be used for parallel processing

...

other arguments passed to detectpar and thence to predict.secr

Details

This function calls fxi.secr for each detected animal and overlays the results to obtain a summed probability density surface D.fx for the locations of the home-range centres of detected individuals.

A separate calculation using pdot provides the expected spatial distribution of undetected animals, as another density surface: crudely, D.nc(X) = D(X) * ( 1 – pdot(X)).

The pointwise sum of the two surfaces is sometimes used to represent the spatial distrbution of the population, but see Notes.

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

Value

An object of class ‘Dsurface’ (a variety of mask) with a ‘covariates’ attribute that is a dataframe with columns –

D.fx

sum of fxi over all detected individuals

D.nc

expected density of undetected (‘not caught’) individuals

D.sum

sum of D.fx and D.nc

All densities are in animals per hectare (the ‘scale’ argument of plot.Dsurface allows the units to be varied later).

Note

The surface D.sum represents what is known from the data about a specific realisation of the spatial point process for home range centres: varying the intensity of sampling will change its shape. It is not an unbiased estimate of a biologically meaningful density surface. The surface will always tend to lack relief towards the edge of a habitat mask where the main or only contribution is from D.nc.

References

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

See Also

fxi.secr, fxi.contour, pdot

Examples

## Not run: 

tmp <- fx.total(secrdemo.0)

## to plot we must name one of the covariates:
## the Dsurface default 'D.0' causes an error 

plot(tmp, covariate = 'D.sum', col = terrain.colors(16),
   plottype = 'shaded')
plot(tmp, covariate = 'D.sum', col = 'white', add = TRUE,
   plottype = 'contour')
if (interactive()) {
    spotHeight(tmp, prefix = 'D.sum')
}

fxsurface <- fx.total(ovenbird.model.D, sessnum = 3)
plot(fxsurface, covariate = 'D.sum')


## End(Not run)