secr 5.0 - spatially explicit capture–recapture in R
This document provides an overview of secr 5.0, an R package for spatially explicit capture–recapture analysis (SECR). It includes some background on SECR, an outline of the package, and a more detailed description of how models are implemented. See secr-tutorial.pdf for an introductory tutorial. For details of how to use secr see the help pages and vignettes.
NOTE: secr was extensively re-written between versions 3.2 and 4.0, but the interface remained unchanged. For many datasets version 4 is significantly faster. Other changes are described in secr-version4.pdf.
Add-on packages extend the capability of secr and are documented separately. secrlinear enables the estimation of linear density (e.g., animals per km) for populations in linear habitats such as stream networks (secrlinear-vignette.pdf). ipsecr fits models by simulation and inverse prediction, rather than maximum likelihood; this is a rigorous way to analyse data from single-catch traps (ipsecr-vignette.pdf). secrdesign enables the assessment of alternative study designs by Monte Carlo simulation; scenarios may differ in detector (trap) layout, sampling intensity, and other characteristics (secrdesign-vignette.pdf).
Spatial open-population capture–recapture models are implemented in the R package openCR (Efford and Schofield 2020). Other open-population packages due to Ben Augustine and Richard Glennie are available on GitHub (https://github.com/benaug/OpenPopSCR; https://github.com/r-glennie/openpopscr).
Introduction to SECR
Spatially explicit capture–recapture (SECR) is a set of methods for modelling animal capture–recapture data collected with an array of ‘detectors’. The methods are used primarily to estimate population density, but they also have advantages over non-spatial methods when the goal is to estimate population size (Efford and Fewster 2013). SECR methods overcome edge effects that are problematic in conventional capture–recapture estimation of animal populations (Otis et al. 1978). Detectors may be live-capture traps, with animals uniquely tagged, sticky traps or snags that passively sample hair, from which individuals are distinguished by their microsatellite DNA, or cameras that take photographs from which individuals are recognized by their natural marks. The concept of a detector extends to areas (polygons) or transects that are searched for animals or their sign.
The primary data for SECR are (i) the locations of the detectors, and (ii) detections of known individuals on one or more sampling occasions (i.e. their detection histories). The generic terms ‘detector’ and ‘detections’ cover several possibilities (see ‘Detector types’ below); we use them interchangeably with the more specific and familiar terms ‘traps’ and ‘captures’. Table 1 gives a concrete example of trapping data (the structure differs for detectors that are not traps).
Table 1. Some spatially explicit detection data. Each entry (e.g., A9) records the detector at which a known animal (ID) was observed at each sample time (occasion). ‘.’ indicates no detection. Each detector has known x-y coordinates. Formats for data input are described in secr-datainput.pdf.
Occasion
ID 1 2 3 4 5
----- ----- ----- ----- ----- -----
1 A9 . . . .
2 A12 A12 . . .
3 . . C6 B5 .
4 . . G3 . F3
etc. In SECR, a spatial model of the population and a spatial model of the detection process are fitted to the spatial detection histories. The resulting estimates of population density are unbiased by edge effects and incomplete detection (other sources of bias may remain). Inverse prediction (IP SECR) and maximum likelihood (ML SECR) are alternative methods for fitting the spatial detection model (Efford 2004, Borchers and Efford 2008). Of these, ML SECR is the more flexible, with a caveat for data from single-catch traps. Data augmentation and Markov chain Monte Carlo (MCMC) methods have also been used for SECR (Royle and Young 2008, Royle et al. 2009, Singh et al. 2010, Royle and Gardner 2011, Royle et al. 2014), but this approach is much slower than ML SECR; it is not considered here.
State and observation models
Like other statistical methods for estimating animal abundance (Borchers et al. 2002), SECR combines a state model and an observation model. The state model describes the distribution of animal home ranges in the landscape, and the observation model (a spatial detection model) relates the probability of detecting an individual at a particular detector to the distance of the detector from a central point in each animal’s home range. The distances are not observed directly (usually we don’t know the range centres), so conventional distance sampling methods do not apply.
Distribution of home-range centres
The distribution of range centres in the population (Borchers and Efford 2008) will usually be treated as a homogeneous Poisson point process (Fig. 1a). Density (= intensity) is the sole parameter of a homogeneous Poisson process. An inhomogeneous Poisson distribution may also be fitted; this provides a means to evaluate the effects of habitat variables on density.
Detection functions
A detection model describes the decline in detection probability with distance (d) from the home-range centre (Fig. 1b). The probability g(d) is for the ‘ideal’ case of just one animal and one detector; the actual probability may differ (see discussion of ‘traps’ under Detector Types).
Fig. 1. (a) Hypothetical Poisson distribution of range centres near an array of detectors. Each dot represents one individual. SECR estimates the density of this distribution. (b) Alternative detection functions. The halfnormal is defined by $g(d) = g_0\exp\left(\frac{-d^2}{2\sigma^2}\right)$ and the exponential by $g(d) = g_0\exp\left(-\frac{d}{\sigma}\right)$. See ?detectfn for more.
Detector types
The properties of detectors are an important part of the SECR observation model (Table 2). Inside secr, data are tagged with a detector type to ensure they are printed, plotted and analysed appropriately.
Some common detectors (camera ‘traps’ and hair snags for DNA) do not
capture animals, but merely record that an animal has visited a site.
These ‘proximity’ detectors can be considered to act independently of
each other. With proximity detectors, each animal × occasion ‘cell’ of a detection history
potentially contains several positive records. In the simplest case each
cell contains a binary vector coding presence or absence at each
detector (for such binary proximity detectors each observation has a
Bernoulli distribution). A ‘count’ detector is a generalised proximity
detector in which the data are vectors of counts, one per detector.
Models for ‘count’ data will specify a distribution for the counts via
the ‘binomN’ argument of secr.fit (binomN = 0 indicates
Poisson; binomN > 1 indicates binomial with size = binomN; binomN = 1
indicates binomial with size given by the ‘usage’ attribute for the
detector and occasion).
Detectors that are true traps do not act independently because capture of an animal in one trap prevents it being caught in another trap until it is released. Traps expose animals to competing risks of capture. The per-trap probability of capture may be adjusted for the competing risk from other traps by using an additive hazard model (Borchers and Efford 2008). However, if the detectors are traps that catch only one animal at a time then there is a further level of competition – between animals for traps. Multi-catch and single-catch traps therefore represent distinct detector types. No general adjustment has been found for the per-trap probability of capture in the single-catch case (it’s an open research question), and there is strictly no known maximum likelihood estimator. Estimates of average density using the multi-catch likelihood for single-catch data appear only slightly biased (Efford, Borchers and Byrom 2009), and this substitution is made automatically in secr, with a warning. However, the substitution is imperfect when density varies (Distiller and Borchers 2015). Simulation and inverse prediction in ipsecr is an alternative and more robust method for single-catch data.
Polygon and transect detectors are for binary or count detection data (e.g., number of detections per animal per polygon per occasion) supplemented with the x-y coordinates of each detection. When a study uses multiple search areas or multiple transects, detections may be either independent or dependent (e.g., maximum one per animal per polygon per occasion) as with traps. The dependent or ‘exclusive’ type is indicated by the suffix ‘X’; in this case the counts are necessarily binary. Using the ‘polygonX’ or ‘transectX’ detector type ensures that a competing-risk model is fitted.
Acoustic ‘signal strength’ detectors produce a binary detection vector supplemented by measurements of signal strength, as from an array of microphones.
There is limited support in secr for the analysis of
locational data from telemetry (‘telemetry’ detector type). Telemetry
data are used to augment capture–recapture data (see
addTelemetry and secr-telemetry.pdf).
Table 2. Detector types in secr
| Detector | Description |
|---|---|
| single | traps that catch one animal at a time |
| multi | traps that may catch more than one animal at a time |
| proximity | records presence at a point without restricting movement |
| count | proximity detector allowing >1 detection per animal per time |
| capped | proximity detector with maximum one animal at a time |
| polygon | counts from searching one or more areas |
| transect | counts from searching one or more transects |
| polygonX | binary data from mutually exclusive areas |
| transectX | binary data from mutually exclusive transects |
| signal | detections and signal strengths at multiple microphones |
| telemetry | locations from radiotelemetry |
Origins and outline of the package secr
The program DENSITY (Efford et al. 2004, Efford 2012) provides a graphical interface to SECR methods that was used by many biologists. However, DENSITY has significant drawbacks: it requires the Windows operating system, its algorithms are not always transparent or well-documented, it fits only homogeneous Poisson models, and it omits recent advances in SECR.
The R package secr was written to address these weaknesses and allow for further development. It implements almost all the methods described by Borchers and Efford (2008), Efford et al. (2009), Efford (2011), Efford and Fewster (2013), Efford et al. (2013) and Efford and Mowat (2014). secr 5.0 uses external C++ code via package Rcpp for computationally intensive operations (Eddelbuettel and Francois 2011); Multi-threading on multiple CPUs with RcppParallel (Allaire et al. 2021) gives major speed gains. The most important functions of secr are listed in Appendix 1.
How secr works
secr defines a set of R classes1 and methods for data from detector arrays and models fitted to those data.
Table 3. Essential classes in secr.
| Class | Data |
|---|---|
| traps | locations of detectors; detector type (‘proximity’, ‘multi’, etc.) |
| capthist | spatial detection histories, including a ‘traps’ object |
| mask | raster map of habitat near the detectors |
| secr | fitted SECR model |
To perform an SECR analysis you explicitly or implicitly construct each of these objects in turn. Fig. 2 indicates the relationships among the classes.
Fig. 2. Essentials of the secr package.
- Each object class (shaded box) comes with methods to display and
manipulate the data it contains (e.g.
print,summary,plot,rbind,subset)2. - The function
read.capthistforms a ‘traps’ object from the detector layout data and saves it as an attribute, along with capture data read from another file, in a ‘capthist’ object. - By default, a habitat mask is generated automatically by
secr.fitusing a specified buffer around the detectors (traps). The functionmake.maskgives greater control over this step. - Any of the objects input to
secr.fit(traps, capthist, mask) may include a dataframe of covariates saved as an attribute. Covariate names may be used in model formulae; thecovariatesmethod is used to extract or replace covariates. UseaddCovariatesfor covariates from spatial data sources (e.g., shapefile or ‘sf’ object) - Fitted secr models may be manipulated with the methods shown on the right and others listed in Appendix 2.
Input
Data input is covered in the separate document secr-datainput.pdf.
One option is to use text files in the formats used by DENSITY; these
accommodate most types of data. Two files are required, one of detector
(trap) locations and one of the detections (captures) themselves; the
function read.capthist reads both files and constructs a
capthist object. It is also possible to construct the capthist object in
two stages, first making a traps object (with read.traps)
and a captures dataframe, and then combining these with
make.capthist. This more general route may be needed for
unusual datasets.
Output
The output from the function secr.fit is an object of
class secr. This is an R list with many components.
Assigning the output to a named object saves both the fit and the data
for further manipulation. Typing the name at the R prompt invokes
print.secr which formats the key results. These include the
dataframe of estimates from the predict method for
secr objects. Functions are provided for further
computations on secr objects (e.g., AIC model selection,
model averaging, profile-likelihood confidence intervals, and
likelihood-ratio tests). Many of these are listed in Appendix 2.
One system of units is used throughout secr. Distances are in metres and areas are in hectares (ha). The unit of density for 2-dimensional habitat is animals per hectare. 1 ha = 10000 m2 = 0.01 km2. To convert density to animals per km2, multiply by 100. Density in linear habitats (see package secrlinear) is expressed in animals per km.
Documentation
The primary documentation for secr is in the help
pages that accompany the package. Help for a function is obtained in the
usual way by typing a question mark at the R prompt, followed by the
function name. Note the ‘Index’ link at the bottom of each help page –
you will probably need to scroll down to find it. The index may also be
accessed with help(package = secr).
The consolidated help pages are in the file secr-manual.pdf. Searching this text is a powerful way to locate a function for a particular task.
Other documentation, in the form of pdf vignettes built with knitr, will be added from time to time. The ‘User guides…’ link in the package help index lists available files. The vignettes in Table 4 may be found on the Density website.
Table 4. Vignettes for secr 5.0.
| Vignette | Topic |
|---|---|
| secr-overview.pdf | introduction (this document) |
| secr-datainput.pdf | data formats and input functions |
| secr-version4.pdf | what’s new in secr 4.x |
| secr-tutorial.pdf | tutorial using Burnham and Cushwa snowshoe hare data |
| secr-habitatmasks.pdf | habitat masks, buffer width and related topics |
| secr-models.pdf | general description of models in secr |
| secr-troubleshooting.pdf | problems with secr.fit, including speed issues |
| secr-densitysurfaces.pdf | modelling density surfaces |
| secr-finitemixtures.pdf | mixture models for individual heterogeneity |
| secr-markresight.pdf | mark–resight models |
| secr-multisession.pdf | data from multiple independent sessions |
| secr-noneuclidean.pdf | non-Euclidean distance models |
| secr-parameterisations.pdf | alternative parameterisations of detection |
| secr-polygondetectors.pdf | using polygon and transect detector types |
| secr-sound.pdf | analysing data from microphone arrays |
| secr-spatialdata.pdf | tips on external spatial data and functions |
| secr-telemetry.pdf | analysing combined telemetry and capture–recapture data |
| secr-varyingeffort.pdf | variable effort (usage) in SECR models |
The web page https://www.otago.ac.nz/density/ should be checked for news of bug fixes and new releases. New versions will be posted on CRAN, but there may be a delay of a few days. Help may be sought on the Density | secr forum at www.phidot.org; see also the FAQ there for DENSITY and secr. Another forum intended for both software issues and wider discussion is secrgroup. For information on changes in each version, type at the R prompt:
Defining models with the ‘model’ argument of secr.fit
By default, the parameters of SECR models are assumed to be constant.
We specify more interesting, and often better-fitting, models with the
‘model’ argument of secr.fit. Here ‘models’ relates to
variation in the parameters that may be explained by known factors and
covariates. The explanation in secr-models.pdf
may help. If you just want to know how to use models, read on.
Models are defined symbolically in secr using R formula notation. A separate linear predictor is used for each core parameter. Core parameters are ‘real’ parameters in the terminology of MARK, and secr uses that term because it will be familiar to biologists.
Three real parameters are commonly modelled in secr
5.0; these are denoted ‘D’ (for density), ‘g0’ (or ‘lambda0’) and
‘sigma’. Only the last two real parameters, which jointly define the
model for detection probability as a function of location, can be
estimated directly when the model is fitted by maximizing the
conditional likelihood (CL = TRUE in
secr.fit). D is then a derived parameter that is computed
from an secr object with the function
derived or one of its siblings (derivedCluster
etc.).
Here is a simple example of the model argument in use:
The real parameter g0 is no longer constant, but takes a unique value on each sampling occasion (t).
Other ‘real’ parameters appear in particular contexts. ‘z’ is a shape
parameter that is used only when the detection function has three
parameters (annular halfnormal, cumulative gamma, hazard-rate etc. – see
?detectfn). Some detection functions primarily model
‘exposure’ or the cumulative hazard of detection, rather than the
probability of detection; these use the real parameter ‘lambda0’ in
place of ‘g0’ (see ?detectfn). ‘lambda0’ is also used with count
detectors. A further ‘real’ parameter is the mixing proportion ‘pmix’,
used in finite mixture models and hybrid mixture models (see ?hcov).
Sometimes it is illuminating and efficient to parameterise the detection function using a function of the primary ‘real’ parameters described above. This gives rise to the surrogate ‘real’ parameters a0 and sigmak; see the vignette secr-parameterisations.pdf for details and references.
Detection parameters and density parameters are modelled separately, as we now describe.
Detection parameters
Effects on parameters of detection probability are specified via R formulae. The variable names used in formulae are either names for standard effects (Table 5) or the names of user-supplied covariates. Effects ‘b’, ‘B’, ‘bk’, and ‘Bk’ refer to individuals whereas ‘k’ and ‘K’ refer only to sites. Groups (‘g’) are used only in models fitted by maximizing the full likelihood; for conditional likelihood models use a factor covariate to achieve the same effect. See also the later section on modelling sex differences.
Table 5. Automatically generated predictor variables used in detection models
| Variable | Description | Notes |
|---|---|---|
| g | group | individual covariates listed in secr.fit argument
‘groups’ |
| t | time factor | one level for each occasion |
| T | time trend | linear trend over occasions on link scale |
| b | learned response | step change after first detection |
| B | transient response | depends on detection at preceding occasion (Markovian response) |
| bk | animal x site response | site-specific step change |
| Bk | animal x site response | site-specific transient response |
| k | site learned response | site effectiveness changes once any animal caught |
| K | site transient response | site effectiveness depends on preceding occasion |
| session | session factor | one level for each session |
| Session | session trend | linear trend on link scale |
| h2 | 2-class mixture | finite mixture model with 2 latent classes |
| ts | marking vs sighting | two levels (marking and sighting occasions) |
Any name in a formula that is not a variable in Table 5 is assumed to
refer to a user-supplied covariate. secr.fit looks for
user-supplied covariates in data frames embedded in the ‘capthist’
argument, or supplied in the ‘timecov’ and ‘sessioncov’ arguments, or
named with the ‘timevaryingcov’ attribute of a traps object, using the
first match (Table 6).
Table 6. Types of user-provided covariate for in detection models. The names of columns in the respective dataframes, and names of components in the ‘timevaryingcov’ attribute, may be used in model formulae
| Covariate type | Data source | Notes |
|---|---|---|
| Individual | covariates(capthist) | conditional likelihood only |
| Time | timecov argument | |
| Detector | covariates(traps(capthist)) | |
| Detector x Time | covariates(traps(capthist)) | see ?timevaryingcov |
| Session | sessioncov argument |
The formula for any detection parameter (e.g., g0, lambda0 or sigma) may be constant (∼ 1, the default) or some combination of terms in standard R formula notation (see ?formula). For example, g0 ∼ b + T specifies a model with a learned response and a linear time trend in g0; the effects are additive on the link scale. See Table 7 for other examples.
Table 7. Some examples of the ‘model’ argument in
secr.fit
| Formula | Effect |
|---|---|
| g0 ∼ 1 | g0 is constant across animals, occasions and detectors |
| g0 ∼ b | learned response affects g0 |
| list(g0 ∼ b, sigma ∼ b) | learned response affects both g0 and sigma |
| g0 ∼ h2 | 2-class finite mixture for heterogeneity in g0 |
| g0 ∼ b + T | learned response in g0 combined with trend over occasions |
| sigma ∼ g | detection scale sigma differs between groups |
| sigma ∼ g*T | group-specific trend in sigma |
| D ∼ cover | density varies with ‘cover’, a variable in covariates(mask) |
| list(D ∼ g, g0 ∼ g) | both density and g0 differ between groups |
| D ∼ session | session-specific density |
For other effects, the design matrix for detection parameters may
also be provided manually in the argument dframe of
secr.fit. This feature is untested.
Inhomogeneous density models
The SECR log likelihood is evaluated by summing values at points on a
‘habitat mask’ (the ‘mask’ argument of secr.fit). Each
point in a habitat mask represents a grid cell of potentially occupied
habitat (their combined area may be almost any shape). The full design
matrix for density (D) has one row for each point in the mask. As for
the detection submodels, the design matrix has one column for the
intercept (constant) term and one for each predictor.
Predictors may be based on Cartesian coordinates (e.g. ‘x’ for an east-west trend), a continuous habitat variable (e.g. vegetation cover) or a categorical (factor) habitat variable. Predictors must be known for all points in the mask (non-habitat excluded). The variables ‘x’ and ‘y’ are the coordinates of the habitat mask and are automatic, as are ‘x2’, ‘y2’, and ‘xy’. Other spatial covariates should be named columns in the ‘covariates’ attribute of the habitat mask.
Regression splines are particularly effective for modelling spatial trend. For these and general guidance on fitting and displaying density surfaces, see the vignette secr-densitysurfaces.pdf.
Model fitting and estimation
Models are fitted in secr.fit by numerically maximizing
the likelihood. The likelihood involves integration over the unknown
locations of the animals’ range centres. This is achieved in practice by
summation over points in the habitat mask, which has some implications
for the user. Computation may be slow, especially if there are many
points in the mask, and estimates may be sensitive to the particular
choice of mask (either explicitly in make.mask or
implicitly via the ‘buffer’ argument).
The default maximization algorithm is Newton-Raphson in the function
stats::nlm. By default, all reported variances,
covariances, standard errors and confidence limits are asymptotic and
based on a numerical estimate of the information matrix. The
Newton-Raphson algorithm is fast, but it sometimes fails to compute the
information matrix correctly, causing some standard errors to be set to
NA; see the ‘method’ argument of secr.fit for alternatives.
Use confint.secr for profile likelihood intervals and
sim.secr for parametric bootstrap intervals (both are
slow).
Habitat masks
We have already introduced the idea of a habitat mask. The SECR
likelihood is evaluated by summing values at points on a mask; each
point represents a grid cell of potentially occupied habitat. Masks may
be constructed by placing a buffer of arbitrary width around the
detectors, possibly excluding known non-habitat. How wide should the
buffer be? The general answer is ‘Wide enough not to cause bias in
estimated densities’. This depends on the scale of movement of the
animal, and on the chosen detection function. For specifics, see the
separate vignette on habitat masks secr-habitatmasks.pdf
and the help for ‘mask’ and the various mask-related functions
(make.mask, mask.check,
suggest.buffer, and esaPlot). Heavy-tailed
detection functions such as the hazard-rate and lognormal can be
problematic because they require an unreasonably large buffer for stable
density estimates.
Miscellaneous topics
Modelling sex differences
There are many ways to model sex differences in secr. Here we sketch some possibilities, in order of usefulness (your mileage may vary).
Fit a hybrid mixture model as described in the online help (?hcov). This accommodates occasional missing values and estimates the sex ratio (pmix).
Use conditional likelihood (
CL = TRUE) and include a categorical (factor) covariate in model formulae (e.g., g0 ∼ sex). To get sex-specific densities then specifygroups = "sex"inderived.Use full likelihood (
CL = FALSE) and separate data for the two sexes as different sessions (most easily, by coding ‘female’ or ‘male’ in the first column of the capture file read withread.capthist). Then include a group term ‘session’ in relevant model formulae (e.g., g0 ∼ session).Use full likelihood (
CL = FALSE), definegroups = "sex"or similar, and include a group term ‘g’ in relevant formulae (e.g., g0 ∼ g).
‘CL’ and ‘groups’ are arguments of secr.fit.
Possibilities 1–4 should not be mixed for comparing AIC. Sex differences
in home-range size (and hence sigma) may be mitigated by compensatory
variation in g0 or lambda0 (Efford and Mowat 2014).
Varying effort
The probability of observing an individual at a particular detector may depend directly on a known quantity such as how long the detector was exposed on a particular occasion. In the extreme, a detector may not have been operated. The terms ‘effort’ and ‘usage’ are used here interchangeably for variation in the duration of exposure and similar known effects. Usage is an attribute of the detectors in a traps object (a traps x occasions matrix); it may be entered with the detector coordinates in a trap layout file or added later (see ?usage). Models fitted to data including a usage attribute will adjust automatically for varying usage across detectors and occasions. Usage may take any non-negative value. This simplifies the modelling of data aggregated over varying numbers of occasions or nearby sites.
See the separate document secr-varyingeffort.pdf and Efford et al. (2013) for more.
Mark–resight
Mark–resight data include sampling occasions on which previously marked animals were recorded, but new animals were not distinguished from each other. secr 5.0 provides a suite of spatial models for these data, as documented in secr-markresight.pdf. Two general classes of spatial mark–resight model are included: those in which the marking process is modelled (we call these spatial capture–mark–resight models), and those in which the process is not modelled and pre-marked animals are assumed to follow some distribution (e.g., uniform across a known area) (sighting-only or mark–resight models). Mark–resight models in secr 5.0 discard some spatial information in the unmarked sightings – information that is used in the models of Chandler and Royle (2013) and Sollmann et al. (2013). This results in some (probably small) loss of precision, and requires an adjustment for overdispersion to ensure confidence intervals have good coverage properties. The vignette secr-markresight.pdf should be consulted.
Detector clusters
For surveying large areas it is efficient to use groups of detectors: within a group the detectors are close enough that animals may be re-detected at multiple points, while groups of detectors may be distributed across a region according to a probability design to sample possible spatial variation in density. secr allows for detector groups with the ‘cluster’ data structure. This is an attribute of a traps object that records which detectors belong to which cluster3.
Functions are provided to generate detector arrays with a clustered
structure (trap.builder, make.systematic), to
extract or replace the cluster attribute (clusterID), to
compute the geometric centres and numbers of detections per cluster
(cluster.centres, cluster.counts), etc.
A lacework design (Efford in prep.) is an alternative to a clustered
design that is suitable when the region is intermediate size. Lacework
designs may be constructed with make.lacework.
Data from a large, clustered design may often be analysed more
quickly if the ‘capthist’ object is first collapsed into one using the
geometry of a single cluster (the object retains a memory of the number
of individuals from each original cluster in the attribute ‘n.mash’).
Use the function mash for this. Functions
derived, derivedMash and the method
predict.secr use ‘n.mash’ to adjust their output density,
SE, and confidence limits.
Parallel processing
On processors with multiple cores it is possible to speed up
computation by using cores in parallel. In secr 5.0
this happens automatically in secr.fit and a few other
functions using the multi-threading paradigm of
RcppParallel (Allaire et al. 2021). The number of
threads may be set directly with the function
setNumThreads, or via the ‘ncores’ argument of several
functions.
Earlier versions of secr relied on parallel
processing with the parallel package (invoked when the
argument ncores was set greater than 1). The benefits of that form of
parallel processing were variable (considerable with simulations in
sim.secr, but otherwise unimpressive).
The functions par.secr.fit, par.region.N
and par.derived allowed models to be fitted or analysed in
parallel, one per core. The greater speed of secr.fit in
secr 5.0 makes par.secr.fit redundant. All
three functions now appear to run faster with ncores=1 than with
ncores>1. They are deprecated and will be removed later in 2024.
list.secr.fit replaces par.secr.fit.
Regression splines
The standard models for ‘real’ parameters in secr are linear on the link scale, much like a generalised linear model. Semi-parametric ‘regression spline’ smooths provide more flexibility. These are implemented in secr using a method suggested by Borchers and Kidney (2014): Simon Wood’s R package mgcv is used to parse s() and te() terms in model formulae and construct basis functions that are used like linear covariates within secr. Any ‘real’ parameter may be modelled with regression splines (D, lambda0, sigma, noneuc etc.). For details see the help page (?smooths) and the documentation for mgcv.
Non-Euclidean distances
‘Distance’ in SECR models usually, and by default, means the Euclidean distance $d = \sqrt{(x_1-x_2)^2 + (y_1 - y_2)^2}$. The observation model can be customised by replacing the Euclidean distance with one that ‘warps’ space in some ecologically meaningful way. There are innumerable ways to do this. Royle et al. (2013) envisioned an ‘ecological distance’ that is a function of landscape covariates. Redefining distance is a way to model spatial variation in the size of home ranges, and hence the spatial scale of movement σ; Efford et al. (2016) use this to model inverse covariation between density and home range size. Distances measured along a linear habitat network such as a river system are also non-Euclidean (see package secrlinear).
secr provides general tools for specifying and
modelling non-Euclidean distance, via the secr.fit details
component ‘userdist’. This may be a user-specified function or a
pre-computed matrix. See secr-noneuclidean.pdf
for a full explanation and examples.
References
Allaire, J. J., Francois, R., Ushey, K., Vandenbrouck, G., Geelnard, M. and Intel (2021) RcppParallel: Parallel Programming Tools for ‘Rcpp’. R package version 5.1.4. https://CRAN.R-project.org/package=RcppParallel.
Borchers, D. L., Buckland, S. T. and Zucchini, W. (2002) Estimating animal abundance: closed populations. Springer, London.
Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximum likelihood methods for capture–recapture studies. Biometrics 64, 377–385.
Borchers, D. L. and Fewster, R. M. (2016) Spatial capture–recapture models. Statistical Science 31, 219–232.
Borchers, D. L. and Kidney, D. (2014) Flexible density surface estimation for spatially explicit capture–recapture surveys. Technical Report, University of St Andrews.
Chandler, R. B. and Royle, J. A. (2013) Spatially explicit models for inference about density in unmarked or partially marked populations. Annals of Applied Statistics 7, 936–954.
Cooch, E. and White, G. (eds) (2014) Program MARK: A Gentle Introduction. 13th edition. Most recent edition available online at www.phidot.org/software/mark/docs/book/.
Distiller, G. and Borchers, D. L. (2015) A spatially explicit capture–recapture estimator for single-catch traps. Ecology and Evolution 5, 5075–5087.
Eddelbuettel, D. and Francois, R. (2011) Rcpp: Seamless R and C++ Integration. Journal of Statistical Software 40(8), 1–18. https://www.jstatsoft.org/v40/i08/.
Efford, M. G. (2004) Density estimation in live-trapping studies. Oikos 106, 598–610.
Efford, M. G. (2011) Estimation of population density by spatially explicit capture–recapture analysis of data from area searches. Ecology 92, 2202–2207.
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.
Efford, M. G., Borchers D. L. and Byrom, A. E. (2009) Density estimation by spatially explicit capture–recapture: likelihood-based methods. In: D. L. Thomson, E. G. Cooch, M. J. Conroy (eds) Modeling Demographic Processes in Marked Populations. Springer. Pp 255–269.
Efford, M. G., Borchers D. L. and Mowat, G. (2013) Varying effort in capture–recapture studies. Methods in Ecology and Evolution 4, 629–636.
Efford, M. G., Dawson, D. K. and Borchers, D. L. (2009) Population density estimated from locations of individuals on a passive detector array. Ecology 90, 2676–2682.
Efford, M. G., Dawson, D. K., Jhala, Y. V. and Qureshi, Q. (2016) Density-dependent home-range size revealed by spatially explicit capture-recapture. Ecography 39, 676–688.
Efford, M. G. and Fewster, R. M. (2013) Estimating population size by spatially explicit capture–recapture. Oikos 122, 918–928.
Efford, M. G. and Mowat, G. (2014) Compensatory heterogeneity in spatially explicit capture–recapture data. Ecology 95, 1341–1348.
Efford, M. G. and Schofield, M. R. (2020) A spatial open-population capture–recapture model. Biometrics 76, 392–402.
Huggins, R. M. (1989) On the statistical analysis of capture experiments. Biometrika 76, 133–140.
Laake, J. and Rexstad E. (2014) Appendix C. RMark - an alternative approach to building linear models in MARK. In: Cooch, E. and White, G. (eds) Program MARK: A Gentle Introduction. 13th edition. most recent edition available at www.phidot.org/software/mark/docs/book/.
Lebreton, J.-D., Burnham, K. P., Clobert, J., and Anderson, D. R. (1992) Modeling survival and testing biological hypotheses using marked animals: a unified approach with case studies. Ecological Monographs 62, 67–118.
Otis, D. L., Burnham, K. P., White, G. C. and Anderson, D. R. (1978) Statistical inference from capture data on closed animal populations. Wildlife Monographs 62.
Royle, J. A., Chandler, R. B., Gazenski, K. D. and Graves, T. A. (2013) Spatial capture–recapture models for jointly estimating population density and landscape connectivity. Ecology 94 287–294.
Royle, J. A., Chandler, R. B., Sollmann, R. and Gardner, B. (2014) Spatial capture–recapture. Academic Press.
Royle, J. A. and Gardner, B. (2011) Hierarchical spatial capture–recapture models for estimating density from trapping arrays. In: A.F. O’Connell, J.D. Nichols and K.U. Karanth (eds) Camera Traps in Animal Ecology: Methods and Analyses. Springer, Tokyo. Pp. 163–190.
Royle, J. A., Nichols, J. D., Karanth, K. U. and Gopalaswamy, A. M. (2009). A hierarchical model for estimating density in camera-trap studies. Journal of Applied Ecology 46, 118–127.
Royle, J. A. and Young, K. V. (2008) A hierarchical model for spatial capture–recapture data. Ecology 89, 2281–2289.
Sollmann, R., Gardner, B., Parsons, A. W., Stocking, J. J., McClintock, B. T., Simons, T. R., Pollock, K. H. and O’Connell, A. F. (2013) A spatial mark–resight model augmented with telemetry data. Ecology 94, 553–559.
Stanley, T. R. and Burnham, K. P. (1999) A closure test for time-specific capture–recapture data. Environmental and Ecological Statistics 6, 197–209.
Appendix 1. Core functions of secr
These are the core functions of secr 5.0 – the ones that you are most likely to use. S3 methods are marked with an asterisk.
| Function | Purpose |
|---|---|
addCovariates |
add spatial covariates to traps or mask |
AIC* |
model selection, model weights |
covariates |
extract or replace covariates of traps, capthist or mask |
derived* |
compute density from conditional likelihood models |
make.mask |
construct habitat mask (= mesh) |
plot* |
plot capthist, traps or mask |
read.capthist |
input captures and trap layout from Density format, one call |
predict* |
compute ‘real’ parameters for arbitrary levels of predictor variables |
predictDsurface |
evaluate density surface at each point of a mask |
region.N* |
compute expected and realised population size in specified region |
secr.fit |
maximum likelihood fit; result is a fitted ‘secr’ object |
summary* |
summarise capthist, traps or mask |
traps |
extract or replace traps object in capthist |
Appendix 2. Classified index to secr functions
Here is an index of secr functions classified by use (some minor functions are omitted). S3 methods are marked with an asterisk.
- Manipulate core objects
- Attributes of traps object
- Attributes of capthist object
- Data for each detection
- Operate on fitted model(s)
- Mask diagnostics
- Specialised graphics
- Convert or export data
- Miscellaneous
Appendix 3. Datasets
See each help page for details e.g., ?deermouse. Code for model fitting is in Appendix 2 of secr-version4.pdf.
`blackbear’
Ursus americanus Tennessee Great Smoky Mountains 2003 DNA hair snag data of J. Laufenberg, F. van Manen and J. Clark; an earlier version was described by Settlage et al. (2008) Journal of Wildlife Management 72.
deermouse
Peromyscus maniculatus Live-trapping data of V. H. Reid published as a CAPTURE example by Otis et al. (1978) Wildlife Monographs 62
hornedlizard
Repeated searches of a quadrat in Arizona for flat-tailed horned lizards Phrynosoma mcallii (Royle & Young Ecology 89, 2281–2289)
housemouse
Mus musculus live-trapping data of H. N. Coulombe published as a CAPTURE example by Otis et al. (1978) Wildlife Monographs 62
ovenbird
Multi-year mist-netting study of ovenbirds Seiurus aurocapilla at a site in Maryland, USA.
ovensong
Acoustic detections of ovenbirds (Dawson & Efford Journal of Applied Ecology 46, 1201–1209)
OVpossum
Brushtail possum Trichosurus vulpecula live trapping in the Orongorongo Valley, Wellington, New Zealand 1996–1997 (Efford and Cowan In: The Biology of Australian Possums and Gliders Goldingay and Jackson eds. Pp. 471–483).
possum
Brushtail possum Trichosurus vulpecula live trapping at Waitarere, North Island, New Zealand April 2002 (Efford et al. 2005 Wildlife Society Bulletin 33, 731–738)
secrdemo
Simulated data ‘captdata’, and some fitted models
skink
Multi-session lizard (Oligosoma infrapunctatum and O. lineoocellatum) pitfall trapping data from Lake Station, Upper Buller Valley, South Island, New Zealand (M. G. Efford, B. W. Thomas and N. J. Spencer unpublished).
stoatDNA
Stoat Mustela erminea hair tube DNA data from Matakitaki Valley, South Island, New Zealand (Efford, Borchers and Byrom 2009).
Technically, these are S3 classes. A ‘class’ in R specifies a particular type of data object and the functions (methods) by which it is manipulated (computed, printed, plotted etc). See the R documentation for further explanation.↩︎
Text in this font refers to R objects that are documented in online help for the secr package, or in base R.↩︎
Clusters are assumed to share the same geometry (number of detectors, within-cluster spacing etc.).↩︎
- Introduction to SECR
- State and observation models
- Origins and outline of the package secr
- How secr works
- Documentation
- Defining models with the ‘model’ argument of secr.fit
- Model fitting and estimation
- Habitat masks
- Miscellaneous topics
- References
- Appendix 1. Core functions of secr
- Appendix 2. Classified index to secr functions
- Appendix 3. Datasets