\renewcommand{\vec}[1]{\mathbf{#1}}
\vspace{12pt}
This document provides an overview of secr 4.4, an R package for spatially explicit capturerecapture analysis (SECR). It includes some background on SECR, an outline of the package, and a more detailed description of how models are implemented. See secrtutorial.pdf for an introductory tutorial. For details of how to use secr see the help pages and vignettes.
NOTE: secr was extensively rewritten 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 secrversion4.pdf.
Two addon 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 (secrlinearvignette.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 (secrdesignvignette.pdf).
Spatial openpopulation capturerecapture models are implemented in the R package openCR (Efford and Schofield 2019). Other openpopulation packages due to Ben Augustine and Richard Glennie are available on GitHub (https://github.com/benaug/OpenPopSCR; https://github.com/rglennie/openpopscr).
Spatially explicit capturerecapture (SECR) is a set of methods for modelling animal capturerecapture data collected with an array of 'detectors'. The methods are used primarily to estimate population density, but they also have advantages over nonspatial methods when the goal is to estimate population size (Efford and Fewster 2013). SECR methods overcome edge effects that are problematic in conventional capturerecapture estimation of animal populations (Otis et al. 1978). Detectors may be livecapture 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).
\vspace{12pt}
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 xy coordinates. Formats for data input are described in secrdatainput.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 singlecatch 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.
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.
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.
A detection model describes the decline in detection probability with distance ($d$) from the homerange 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).
library(secr) ## Following is not needed as no multithreaded operations in this vignette ## To avoid ASAN/UBSAN errors on CRAN, following advice of Kevin Ushey ## e.g. https://github.com/RcppCore/RcppParallel/issues/169 Sys.setenv(RCPP_PARALLEL_BACKEND = "tinythread")
options(digits=6, width=85)
\vspace{8pt}
par(mfrow=c(1,2), pty='s', mar=c(2,1,2,2), cex=1.2, las = 1, bty = 'l', xpd=T, cex=1.2, xaxs='i', yaxs='i', lwd=1.5) plot(sim.popn(D=5, core=make.grid(), buffer=150), cex=1) plot(make.grid(),add=T, detpar=list(col = "red", pch = 3, cex = 1.2)) text(160,300,'a.', cex=1.3) par(mar=c(4,5,2,2)) plot(0,0, type='n', xlim=c(0,800), ylim=c(0,0.15), xlab='', ylab='', lwd=2, col='blue', axes = FALSE) plot(stoat.model.HN, limits=FALSE, xv=0:800, ylim=c(0,0.12), xlab='', ylab='', lwd=2, col='blue', add = TRUE) axis (1) mtext(side=1, line=2.5, 'Distance (m)', cex=1.2) axis (2, at=c(0, 0.05, 0.10, 0.15)) mtext(side=2, line=3.5, 'Detection probability', cex=1.2, las=0) plot(stoat.model.EX, add=T, limits=F, xv=1:800, col='green', lwd=2) legend (260,0.15, lwd=2, col=c('blue', 'green'), legend=c('halfnormal','exponential'), bty='n') text(450, 0.18,'b.', cex=1.3)
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 (also the list in Appendix 1).
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
$\times$ 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 pertrap 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. Multicatch and singlecatch traps therefore represent distinct detector types. No general adjustment has been found for the pertrap probability of capture in the singlecatch case (it's an open research question), and there is strictly no known maximum likelihood estimator. However, density estimates using the multicatch likelihood for singlecatch data appear only slightly biased (Efford, Borchers and Byrom 2009).
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 xy 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 competingrisk 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 capturerecapture data (see addTelemetry
and secrtelemetry.pdf).
\vspace{12pt}
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 
The program DENSITY (Efford et al. 2004, Efford 2012) provides a graphical interface to SECR methods that has been accepted by many biologists. However, DENSITY has significant drawbacks: it requires the Windows operating system, its algorithms are not always transparent or welldocumented, 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 4.4 uses external C++ code via package Rcpp for computationally intensive operations (Eddelbuettel and Francois 2011); Multithreading on multiple CPUs with RcppParallel (Allaire et al. 2021) gives major speed gains. Appendix 1 compares the features of DENSITY and secr. The most important functions of secr are listed in Appendix 2.
secr defines a set of R classes[^1] and methods for data from detector arrays and models fitted to those data.
\vspace{12pt}
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
[^1]: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.
To perform an SECR analysis you explicitly or implicitly construct each of these objects in turn. Fig. 2 indicates the relationships among the classes.
\pagebreak
\setkeys{Gin}{height=95mm, width=140mm,keepaspectratio=TRUE}
Fig. 2. Essentials of the secr package.
print
, summary
, plot
, rbind
, subset
)[^2]. read.capthist
forms 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. secr.fit
using a specified buffer around the detectors (traps). The function make.mask
gives greater control over this step.secr.fit
(traps, capthist, mask) may include a dataframe of covariates saved as an attribute. Covariate names may be used in model formulae; the covariates
method is used to extract or replace covariates.[^2]:Text in this font refers to R objects that are documented in online help for the secr package, or in base R.
Data input is covered in the separate document secrdatainput.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.
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, profilelikelihood confidence
intervals, and likelihoodratio tests). Many of these are listed in Appendix 3.
One system of units is used throughout secr. Distances are in metres and areas are in hectares (ha). The unit of density for 2dimensional habitat is animals per hectare. 1 ha = 10000 m^2^ = 0.01 km^2^. To convert density to animals per km^2^, multiply by 100. Density in linear habitats (see package secrlinear) is expressed in animals per km.
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 secrmanual.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.
\vspace{18pt}
Table 4. Vignettes for secr 4.4.
 Vignette  Topic 

 secroverview.pdf  introduction (this document) 
 secrdatainput.pdf  data formats and input functions 
 secrversion4.pdf  what's new in secr 4.x 
 secrtutorial.pdf  tutorial using Burnham and Cushwa snowshoe hare data 
 secrhabitatmasks.pdf  habitat masks, buffer width and related topics
 secrmodels.pdf  general description of models in secr
 secrtroubleshooting.pdf  problems with secr.fit
, including speed issues 
  
 secrdensitysurfaces.pdf  modelling density surfaces 
 secrfinitemixtures.pdf  mixture models for individual heterogeneity 
 secrmarkresight.pdf  markresight models
 secrmultisession.pdf  data from multiple independent sessions 
 secrnoneuclidean.pdf  nonEuclidean distance models 
 secrparameterisations.pdf  alternative parameterisations of detection
 secrpolygondetectors.pdf  using polygon and transect detector types 
 secrsound.pdf  analysing data from microphone arrays
 secrtelemetry.pdf  analysing combined telemetry and capturerecapture data
 secrvaryingeffort.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 at phidot; 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:
news (package = "secr")
By default, the parameters of SECR models are assumed to be constant. We specify more interesting, and often betterfitting, 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 secrmodels.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 4.4; 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:
secr.fit(captdata, model = g0~t)
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, hazardrate 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 secrparameterisations.pdf for details and references.
Detection parameters and density parameters are modelled separately, as we now describe.
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 usersupplied 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.
\vspace{12pt}
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  sitespecific step change
 Bk  animal x site response  sitespecific 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  2class 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 usersupplied covariate. secr.fit
looks for usersupplied 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).
\vspace{12pt}
Table 6. Types of userprovided 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 ($\sim$ 1, the default) or some combination of terms in standard R formula notation (see ?formula). For example, g0 $\sim$ 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.
\vspace{12pt}
Table 7. Some examples of the 'model' argument in secr.fit
 Formula  Effect    g0 $\sim$ 1  g0 is constant across animals, occasions and detectors   g0 $\sim$ b  learned response affects g0   list(g0 $\sim$ b, sigma $\sim$ b)  learned response affects both g0 and sigma   g0 $\sim$ h2  2class finite mixture for heterogeneity in g0   g0 $\sim$ b + T  learned response in g0 combined with trend over occasions   sigma $\sim$ g  detection scale sigma differs between groups   sigma $\sim$ g*T  groupspecific trend in sigma   D $\sim$ cover  density varies with 'cover', a variable in covariates(mask)   list(D $\sim$ g, g0 $\sim$ g)  both density and g0 differ between groups   D $\sim$ session  sessionspecific 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.
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 eastwest 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 (nonhabitat 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 secrdensitysurfaces.pdf.
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 NewtonRaphson 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 NewtonRaphson
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).
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 nonhabitat. 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 secrhabitatmasks.pdf
and the help for 'mask' and the various maskrelated functions (make.mask
,
mask.check
, suggest.buffer
, and esa.plot
). Heavytailed detection
functions such as the hazardrate and lognormal can be problematic because
they require an unreasonably large buffer for stable density estimates.
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 $\sim$
sex). To get sexspecific densities then specify groups =
"sex"
in derived
.
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 with
read.capthist
). Then include a group term 'session' in
relevant model formulae (e.g., g0 $\sim$ session).
Use full likelihood (CL = FALSE
), define groups = "sex"
or
similar, and include a group term 'g' in relevant formulae (e.g.,
g0 $\sim$ g).
'CL' and 'groups' are arguments of secr.fit
. Possibilities 14 should not be mixed for comparing AIC. Sex differences in homerange size (and hence sigma) may be mitigated by compensatory
variation in g0 or lambda0 (Efford and Mowat 2014).
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 nonnegative value. This simplifies the modelling of data aggregated over varying numbers of occasions or nearby sites.
See the separate document secrvaryingeffort.pdf and Efford et al. (2013) for more.
Markresight data include sampling occasions on which previously marked animals were recorded, but new animals were not distinguished from each other. secr 4.4 provides a suite of spatial models for these data, as documented in secrmarkresight.pdf. Two general classes of spatial markresight model are included: those in which the marking process is modelled (we call these spatial capturemarkresight models), and those in which the process is not modelled and premarked animals are assumed to follow some distribution (e.g., uniform across a known area) (sightingonly or markresight models). Markresight models in secr 4.4 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 secrmarkresight.pdf should be consulted.
For surveying large areas it is efficient to use groups of detectors: within a group the detectors are close enough that animals may be redetected 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 cluster[^3].
[^3]:Clusters are assumed to share the same geometry (number of detectors, withincluster spacing etc.).
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.
On processors with multiple cores it is possible to speed up computation by using cores in parallel. In secr 4.4 this happens automatically in secr.fit
and a few other functions using the multithreading 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
and ip.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 4.4 makes par.secr.fit
redundant. All three functions now appear to run faster with ncores=1 than with ncores>1. They are retained because it is sometimes useful to process several models at once.
The standard models for 'real' parameters in secr are linear on the link scale, much like a generalised linear model. Semiparametric '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.
'Distance' in SECR models usually, and by default, means the Euclidean distance $d = \sqrt{(x_1x_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 $\sigma$; 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 nonEuclidean (see package secrlinear).
secr provides general tools for specifying and modelling nonEuclidean distance, via the secr.fit
details component 'userdist'. This may be a userspecified function or a precomputed matrix. See secrnoneuclidean.pdf for a full explanation and examples.
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.Rproject.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 capturerecapture studies. Biometrics 64, 377385.
Borchers, D. L. and Fewster, R. M. (2016) Spatial capturerecapture models. Statistical Science 31, 219232.
Borchers, D. L. and Kidney, D. (2014) Flexible density surface estimation for spatially explicit capturerecapture 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, 936954.
Cooch, E. and White, G. (eds) (2014) Program MARK: A Gentle Introduction. 13th edition. Available online at http://www.phidot.org/software/mark/docs/book/.
Eddelbuettel, D. and Francois, R. (2011) Rcpp: Seamless R and C++ Integration. Journal of Statistical Software 40(8), 118. https://www.jstatsoft.org/v40/i08/.
Efford, M. G. (2004) Density estimation in livetrapping studies. Oikos 106, 598610.
Efford, M. G. (2011) Estimation of population density by spatially explicit capturerecapture analysis of data from area searches. Ecology 92, 22022207.
Efford, M. G. (2012) DENSITY 5.0: software for spatially explicit capturerecapture. 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 capturerecapture: likelihoodbased methods. In: D. L. Thomson, E. G. Cooch, M. J. Conroy (eds) Modeling Demographic Processes in Marked Populations. Springer. Pp 255269.
Efford, M. G., Borchers D. L. and Mowat, G. (2013) Varying effort in capturerecapture studies. Methods in Ecology and Evolution 4, 629636.
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, 26762682.
Efford, M. G., Dawson, D. K., Jhala, Y. V. and Qureshi, Q. (2016) Densitydependent homerange size revealed by spatially explicit capturerecapture. Ecography 39, 676688.
Efford, M. G. and Fewster, R. M. (2013) Estimating population size by spatially explicit capturerecapture. Oikos 122, 918928.
Efford, M. G. and Mowat, G. (2014) Compensatory heterogeneity in spatially explicit capturerecapture data. Ecology 95, 13411348.
Huggins, R. M. (1989) On the statistical analysis of capture experiments. Biometrika 76, 133140.
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. http://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, 67118.
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 capturerecapture models for jointly estimating population density and landscape connectivity. Ecology 94 287294.
Royle, J. A., Chandler, R. B., Sollmann, R. and Gardner, B. (2014) Spatial capturerecapture. Academic Press.
Royle, J. A. and Gardner, B. (2011) Hierarchical spatial capturerecapture 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. 163190.
Royle, J. A., Nichols, J. D., Karanth, K. U. and Gopalaswamy, A. M. (2009). A hierarchical model for estimating density in cameratrap studies. Journal of Applied Ecology 46, 118127.
Royle, J. A. and Young, K. V. (2008) A hierarchical model for spatial capturerecapture data. Ecology 89, 22812289.
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 markresight model augmented with telemetry data. Ecology 94, 553559.
Stanley, T. R. and Burnham, K. P. (1999) A closure test for timespecific capturerecapture data. Environmental and Ecological Statistics 6, 197209.
\pagebreak
• full implementation
◦ incomplete or inferior implementation.
 Feature  DENSITY 5.0  secr 4.4    General      Graphical interface  •  ◦   Inverse prediction (IP SECR)  •  •   Maximum likelihood estimation (ML SECR)  •  •   Nonspatial closedpopulation estimators  •  •   Simulation of spatial sampling  •  •   Build detector arrays  •  •   Control of random number generator  ◦  •   Closure tests  ◦  •   Import or export DENSITY text files  •  •   Convert BUGS data   ◦   GIS polygons as habitat mask  •  •   Clustered detector layouts   •   Mash data from clustered layouts   •   Upload coordinates to GPS (uses GPSBabel)   •   Multithreaded C++ for fast model fitting   •   ML secr      Density models (inhomogeneous 2D Poisson)   •   Regional population size (region.N)   •   Varying effort (detector usage)  ◦  •   Fixed parameters  ◦  •   Parametric bootstrap  ◦  •   Betweensession models  •  •   Profile likelihood confidence intervals  •  •   Mixture models for individual heterogeneity  •  •   Confidence ellipses  •  •   Formulabased model notation   •   Plot density models   •   Groups (e.g. males & females)   •   Score tests for model selection   •   Model averaging   •   Plot likelihood surface   •   Empirical variance from replicate units   •   Mask diagnostics  ◦  •   Suggested buffer width   •   Contours of detection probability  •  •   Compute pdf for individual's range centre  •  •   Timevarying detector covariates   •   Hybrid mixture models (hcov)   •   Compensation (a0 parameterization)   •   Densitydependent sigma (sigmak parameterization)   •   Varianceonly mode (method = 'none')   •   Combined telemetrydetection models   •   Regression splines   •   NonEuclidean distance   •   Markresight   •   Detector types      Singlecatch trap^a^  ◦  ◦   Multicatch trap  •  •   Proximity  •  •   Signal strength (acoustic)   •   Count   •   Capped   ◦   Polygon   •   Transect   •   Polygon (exclusive)   •   Transect (exclusive)   •   Telemetry   •   Detection functions      Halfnormal  •  •   Hazard rate^b^  •  •   Exponential  •  •   Compound halfnormal   •   Uniform^a^  ◦  ◦   wexponential   •   Annular halfnormal   •   Binary signal strength   •   Signal strength   •   Signal strength spherical   •   Cumulative lognormal^b^   •   Cumulative gamma   •   Hazard halfnormal   •   Hazard hazard rate^b^   •   Hazard exponential   •   Hazard annular halfnormal   •   Hazard cumulative gamma   •   Hazard variable power   • 
a. Not fitted by ML secr
b. Not recommended because of heavy tail
\pagebreak
These are the core functions of secr 4.4  the ones that you are most likely to use. S3 methods are marked with an asterisk.
 Function  Purpose 

 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 
\pagebreak
Here is an index of secr functions classified by use (some minor functions are omitted). S3 methods are marked with an asterisk.
 Function  Purpose 

 Manipulate data objects  
 addCovariates
 add spatial covariates to 'traps' or 'mask' 
 as.mask
 coerce 'traps' object to 'mask' for specialised plotting 
 deleteMaskPoints
 edit 'mask' 
 discretize
 rasterize areasearch capthist data 
 head
 first rows of 'capthist', 'traps' or 'mask' 
 join
 combine sessions of multisession 'capthist' object 
 make.grid
 construct detector array 
 make.capthist
 form 'capthist' from 'traps' and detection data 
 make.mask
 construct habitat mask (mesh) 
 make.systematic
 construct clustered random systematic design 
 make.lacework
 construct lacework random systematic design 
 MS.capthist
 combine 'capthist' objects into one multisession 'capthist' 
 plot
 plot 'capthist', 'traps' or 'mask' 
 plotMaskEdge
 draw line around mask cells 
 randomHabitat
 generates habitat mask with random landscape 
 rbind
 append 'capthist', 'traps', 'popn' or 'mask' objects 
 read.capthist
 input captures and trap layout from Density format, one call 
 read.traps
 input detector locations from text file 
 reduce
 aggregate detectors or occasions; change detector type 
 sim.capthist
 simulate capture histories 
 sightingPlot
 bubble plot of sightings in capthist object 
 snip
 split transect(s) into equal sections 
 split
 split a singlesession capthist or mask by various criteria 
 subset
 filter 'capthist', 'traps' or 'mask' 
 summary
 summarise 'capthist', 'traps' or 'mask' 
 tail
 last rows of 'capthist', 'traps' or 'mask' 
 trap.builder
 construct various complex designs 
 verify
 check 'capthist', 'traps' or 'mask' for internal consistency 
 Attributes of traps object  
 clusterID
 cluster identifier 
 clustertrap
 detector number within cluster 
 covariates
 detectorlevel covariates 
 detector
 detector type ('multi', 'proximity' etc.) 
 markocc
 vector distinguishing marking and sighting occasions 
 polyID
 polygon or transect identifier 
 timevaryingcov
 name timevarying covariate(s) 
 usage
 occasion and detectorspecific effort 
 Attributes of capthist object  
 addSightings
 add sighting data to a 'proximity', 'count' or 'polygon' object 
 addTelemetry
 add telemetry data to a 'proximity' or 'count' object 
 covariates
 individuallevel covariates, including grouping factors 
 session
 session identifier(s) 
 signalmatrix
 sound x microphone table 
 telemetryxy
 coordinates of telemetry fixes 
 Tm
 counts of marked animals that were not identified 
 traps
 embedded traps object(s) 
 Tu
 counts of unmarked animals 
 Data for each detection  
 alive
 TRUE/FALSE 
 animalID
 individual ID 
 clusterID
 cluster identifier 
 clustertrap
 detector number within cluster 
 noise
 noise (signal detectors) 
 occasion
 occasion 
 signal
 signal strength (signal detectors) 
 signalframe
 whole signal \ noise dataframe (rows = detections) 
 trap
 detector 
 xy
 detection coordinates (polygon and transect detectors)
 Fit SECR model(s)  
 ip.secr
 fit simple SECR model by simulation \ inverse prediction 
 par.secr.fit
 parallel secr.fit() (several models, using multiple cores) 
 secr.fit
 maximum likelihood fit; result is a fitted secr
object 
 Operate on fitted model(s)  
 AIC
 model selection, model weights 
 coef
 'beta' parameters 
 collate
 tabulate estimates from several models 
 confint
 profile likelihood confidence intervals 
 CVa, CVa0
 CV of individual detection from fitted mixture model 
 derived
 density from conditional likelihood models 
 deviance
 model deviance 
 df.residual
 degrees of freedom for deviance 
 derivednj
 variance from replicated sampling units 
 derivedCluster
 variance from replicated sampling units 
 derivedExternal
 variance from replicated sampling units 
 ellipse.secr
 confidence ellipses for estimated parameters 
 fxi.secr
 probability density of homerange centre 
 LLsurface
 compute likelihood surface and plot contours 
 logLik
 loglikelihood of fitted model 
 LR.test
 likelihoodratio test of two models 
 model.average
 combine estimates using AIC or AICc weights 
 par.derived
 parallel derived() 
 par.region.N
 parallel region.N() 
 plot
 plot detection functions with confidence bands 
 predict
 'real' parameters for arbitrary levels of predictor variables 
 predictDsurface
 evaluate density surface at each point of a mask 
 region.N
 expected and realised population size in specified region 
 RSE
 extract precision (relative SE) of 'real' parameter estimates 
 score.test
 model selection with score statistic using observed information 
 secr.test
 Monte Carlo goodnessoffit tests 
 simulate
 generate realisations of fitted model 
 sim.secr
 parametric bootstrap 
 vcov
 variancecovariance matrix of 'beta' or 'real' parameters 
 Mask diagnostics  
 esa.plot
 cumulative plot esa or $\hat D$ vs buffer width 
 mask.check
 likelihood or estimates vs. buffer width and spacing [6pt]
 suggest.buffer
 find buffer width to keep bias within bounds 
 Specialised graphics  
 buffer.contour
 concave and convex boundary strips 
 fx.total
 summed pdfs of homerange centre pdfs (use with plot.Dsurface
) 
 fxi.contour
 contour plot of homerange centre pdf(s) 
 pdot.contour
 contour plot of detection probability 
 strip.legend
 add colour legend to existing plot 
 Convert or export data  
 RMarkInput
 convert 'capthist' to dataframe for RMark 
 write.capthist
 export 'capthist' as text files for DENSITY 
 write.DA
 convert 'capthist' for analysis in WinBUGS 
 writeGPS
 upload coordinates to GPS using GPSBabel 
 Miscellaneous  
 ARL
 asymptotic range length
 autoini
 generate starting values of D, g0 and sigma for secr.fit

 centroids
 centroid of each animal's detections 
 clone
 replicate points to emulate overdispersion 
 closure.test
 closure tests of Otis et al. (1978) and Stanley \ Burnham (1999) 
 closedN
 closed population size by various conventional estimators 
 counts
 summary data from 'capthist' object 
 CV
 coefficient of variation 
 dbar
 mean distance between capture locations 
 distancetotrap
 from an arbitrary set of points 
 edist
 Euclidean distance 
 MMDM
 mean maximum distance moved 
 moves
 distances between capture locations 
 nearesttrap
 from an arbitrary set of points 
 nedist
 NonEuclidean distance 
 ORL
 observed range length
 pdot
 locationspecific net probability of detection 
 PG
 proportion of telemetry fixes in given polygons 
 pmixProfileLL
 profile likelihood as function of mixing proportion 
 RPSV
 'root pooled spatial variance', a simple measure of homerange size 
 setNumThreads
 sets environment variable RCPP_PARALLEL_NUM_THREADS 
\pagebreak
See each help page for details e.g., ?deermouse. Code for model fitting is in Appendix 2 of secrversion4.pdf.
deermouse
Peromyscus maniculatus Livetrapping 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 flattailed horned lizards Phrynosoma mcallii (Royle & Young Ecology 89, 22812289)
housemouse
Mus musculus livetrapping data of H. N. Coulombe published as a CAPTURE example by Otis et al. (1978) Wildlife Monographs 62
ovenbird
Multiyear mistnetting study of ovenbirds Seiurus aurocapilla at a site in Maryland, USA.
ovensong
Acoustic detections of ovenbirds (Dawson & Efford Journal of Applied Ecology 46, 12011209)
OVpossum
Brushtail possum Trichosurus vulpecula live trapping in the Orongorongo Valley, Wellington, New Zealand 19961997 (Efford and Cowan In: The Biology of Australian Possums and Gliders Goldingay and Jackson eds. Pp. 471483).
possum
Brushtail possum Trichosurus vulpecula live trapping at Waitarere, North Island, New Zealand April 2002 (Efford et al. 2005 Wildlife Society Bulletin 33, 731738)
secrdemo
Simulated data 'captdata', and some fitted models
skink
Multisession 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).
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.