% \VignetteIndexEntry{Spatially explicit capture--recapture in R}
% \VignetteKeyword{models}
\documentclass[a4paper]{article}

\title{\textbf{secr} - spatially explicit capture--recapture in R}
\author{Murray Efford}
\date{February 28, 2010}
\usepackage{graphicx}
\usepackage{textcomp}
\usepackage{longtable}
\usepackage{color}
\renewcommand{\vec}[1]{\mathbf{#1}}

\begin{document}

\maketitle

\vspace{24pt}

This document provides an overview of \textbf{secr}, an R package for
spatially explicit capture--recapture analysis (SECR). It includes
some necessary background on SECR, an outline of the package, and a
more detailed description of how models are implemented. See Appendix
1 for a glimpse of \textbf{secr} in action. For details of how to use
\textbf{secr} see the help pages.

\vspace{24pt}

\tableofcontents


\newpage

\section*{Introduction to SECR}
\addcontentsline{toc}{section}{Introduction to SECR}

SECR is a set of methods for estimating the density of an animal
population from capture--recapture data collected with an array of
`detectors'. 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 marked.  Detectors also may be sticky traps or snags that
passively sample hair, from which individuals are distinguished by
their DNA microsatellites, or cameras that take photographs from which
individuals are recognized by their natural marks.

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 terms `detectors' and
`detections' cover the full spectrum of possibilities (see `Detector
types' below), but we use them interchangeably with the more familiar
`traps' and `captures', respectively. Table \ref{tab:example} gives a concrete
example.
\setcounter{table}{0}
\begin{table}[h]   % b 'bottom' h 'here' t 'top' of page
\caption{Example of spatially explicit detection data. Each entry
(e.g. A9) records the detector at which a known animal (ID) was
observed on the given occasion (sample time). `.' indicates no
detection. Each detector has known x-y coordinates.}
\vspace{6pt}
\begin{tabular}{r r r r r r}
 & \multicolumn{5}{c}{Occasions} \\
ID  &   1 &   2 &   3 &   4 &   5 \\
 1  &  A9 &   . &   . &   . &   . \\
 2  & A12 & A12 &   . &   . &   . \\
 3  &   . &   . &  C6 &  B5 &   . \\
 4  &   . &   . &  G3 &   . &  F3 \\
 etc.
 \end{tabular}
\label{tab:example}
\end{table}

In SECR, a spatial model of the population and the detection process
is 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
et al. 2009), but this approach is not considered here.

\subsection*{State and observation models}
\addcontentsline{toc}{subsection}{State and observation models}

Like other 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 (we
don't know the range centre), so conventional distance sampling
methods do not apply.

\subsection*{Distribution of home-range centres}
\addcontentsline{toc}{subsection}{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. \ref{fig:poisson}). Density is the sole parameter of a Poisson
process. An inhomogeneous distribution may also be fitted and this
provides a means to evaluate the effects of habitat variables on
density.

\setkeys{Gin}{width=70mm, height=70mm}
\begin{center}
\begin{figure}[th]
<<fig=TRUE, echo=FALSE>>=
library(secr)
par(mfrow=c(1,1), pty='s', mar=c(2,2,2,2), cex=1.2)
plot(sim.popn(D=5, core=make.grid(), buffer=150), cex=1.2)
plot(make.grid(),add=T, detpar=list(col = "red", pch = 3, cex = 1.2))
@

\caption{Hypothetical Poisson distribution of range centres
  near an array of detectors.}
\label{fig:poisson}
\end{figure}
\end{center}

\subsection*{Detection functions}
\addcontentsline{toc}{subsection}{Detection functions}

A detection model is based on one of several possible parametric
forms for the decline in detection probability with distance ($d$)
from the home-range centre (Table \ref{tab:detectfn},
Fig. \ref{fig:detectfn}). 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).

\begin{table}[h]
\caption{Various functions relating the
  probability of detection to distance ($d$)}
\vspace{6pt}
\begin{tabular}{ll}
\hline\noalign{\smallskip}
Halfnormal & $ g(d) = g_0 \exp \left(\frac{-d^2} {2\sigma^2} \right)$ \\
Exponential & $  g(d) = g_0  \exp \left( -\frac{d}{\sigma} \right) $ \\
Hazard-rate & $  g(d) = g_0 [1 - \exp\{ {-(\frac{d}{\sigma})^{-z}} \}] $ \\
\noalign{\smallskip}
\hline\noalign{\smallskip}
\end{tabular}
\label{tab:detectfn}
\end{table}

\begin{center}
\begin{figure}[h]
<<fig=TRUE, echo=FALSE>>=
par(mfrow=c(1,1), pty='s', mar=c(4,4,2,2), las=1, bty='l', xpd=T)
detectfnplot (detectfn = 0, pars=c(0.4, 30), xval=0:120, ylim=c(0,0.45), cex=1.3, lwd=2)
detectfnplot (detectfn = 1, pars=c(0.4, 50, 5), xval=0:120, add=T, cex=1.2, col='blue', lwd=2)
detectfnplot (detectfn = 2, pars=c(0.4, 30), xval=0:120, add = T, cex=1.2, col='green', lwd=2)
legend (68,0.45, lwd=2, col=c('blue', 'black','green'), cex=1.2,
    legend=c('hazard-rate','halfnormal','exponential'), bty='n')
@
\caption{Alternative shapes for a function relating the probability of
  detection to distance from range centre.}
\label{fig:detectfn}
\end{figure}
\end{center}

% \setkeys{Gin}{width=130mm, trim = 20mm 90mm 0mm 100mm, clip}
% \begin{figure}
% \includegraphics{detectionfn.pdf}
% \caption{Hypothetical Poisson distribution of range centres
%  near an array of detectors (left) and alternative shapes for a
%  function relating detection at a point to distance from range centre
%  (right).}
% \end{figure}

\subsection*{Detector types}
\addcontentsline{toc}{subsection}{Detector types}

Properties of the detectors are an important part of the observation
model.  Some common detectors (camera `traps' and hair snags for DNA)
do not capture animals but provide evidence of their passing, and can
be considered to act independently of each other. We call these
`proximity' detectors. With proximity detectors, each animal x
occasion `cell' of a detection history potentially contains several
positive records. In the simplest case each such observation is a
binary vector coding presence or absence at each detector. Recent
extensions include `proximity count' detectors (a vector of counts,
one per detector) and acoustic `signal strength' detectors (a binary
vector supplemented by measurements of signal strength, e.g. from an
array of microphones).

Detectors that are true traps do not act independently because capture
of an animal in one trap prevents capture in another (until the animal
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. However, density estimates using the multi-catch likelihood
for single-catch data appear only slightly biased (Efford, Borchers
and Byrom 2009).

\section*{Origins and outline of the package `secr'}
\addcontentsline{toc}{section}{Origins and outline of the package \textbf{secr}}

The program DENSITY (Efford et al. 2004, Efford 2009) 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 and is increasingly difficult to
maintain, its algorithms are not always transparent or
well-documented, it fits only homogeneous Poisson models, and it omits
some recent advances in SECR.

The R package \textbf{secr} was written to address these weaknesses
and allow for further development. It implements almost all the
methods and options described in Borchers and Efford (2008) and Efford
et al. (2009), and others yet to be published. \textbf{secr} uses
external C code for computationally intensive operations. Appendix 2
compares the features of DENSITY and \textbf{secr}. The major
functions of \textbf{secr} are listed in Appendix 3.

\subsection*{How secr works}
\addcontentsline{toc}{subsection}{How \textbf{secr} works}

\textbf{secr} defines a set of R classes\footnote{A `class' 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} and methods for data from
detector arrays. The essential classes are:

\vspace{6pt}

\begin{tabular}{l l}
  \texttt{traps} & locations of detectors; detector type (`proximity',
  `multi', etc.) \\
  \texttt{capthist} & spatial detection histories, including a \texttt{traps} object \\
  \texttt{mask} & points on habitat mask \\
  \texttt{secr} &	fitted SECR model.\\
\end{tabular}

\vspace{6pt}

To perform an SECR analysis you will construct each of these objects
in turn, using the functions provided (e.g.,
\texttt{make.grid}\footnote{Text in \texttt{teletype} font refers to R
  objects that are documented in online help for the \textbf{secr}
  package, or in base R. A good place to start is the page for
  \texttt{secr.fit}}, \texttt{make.capthist},
\texttt{secr.fit}). Fig. \ref{fig:schematic} summarizes the
relationships among the core object classes.  The classes
\texttt{traps}, \texttt{capthist} and \texttt{mask} may optionally
store covariates specific to detectors, animals and habitat points
respectively. Each set of covariates is saved in a dataframe that is
an attribute of the corresponding object; the \texttt{covariates} method
is used to extract or replace covariates.

\setkeys{Gin}{width=130mm, trim = 20mm 35mm 0mm 40mm,
clip}
\begin{figure}[!h]
%trim l b r t
\includegraphics{secr-schematic.pdf}
\caption{Essentials of the \textbf{secr} package. Each object class
  (shaded box) comes with methods to display and manipulate the data
  it contains (e.g. \texttt{print}, \texttt{summary}, \texttt{plot},
  \texttt{rbind}, \texttt{subset}). Detector coordinates
  (\texttt{traps}) are stored with attributes such as detector type
  and usage. Detection data (\texttt{captures}) are initially stored
  in a dataframe with one row per detection, but must be wrapped with
  the corresponding \texttt{traps} in a \texttt{capthist} object for
  analysis. If a habitat mask is not created manually (dashed arrow)
  it will be generated automatically by \texttt{secr.fit}. Any of the
  objects input to \texttt{secr.fit} may include a dataframe of
  covariates whose names may be used in a model formula. Fitted secr
  models may be further manipulated with the methods shown on the
  right. Additional functions (not shown) construct a regular detector
  array (e.g. \texttt{make.grid}, \texttt{make.circle}) or simulate
  detection of a known population (\texttt{sim.capthist}).}
\label{fig:schematic}
\end{figure}

\subsection*{Output}
\addcontentsline{toc}{subsection}{Output}

The output from the function \texttt{secr.fit} is an object of class
\texttt{secr}. This is an R list with many components. Assigning the
output to a named object (such as secr0 or secrb in the example) saves
both the fit and the data for further manipulation. Typing the name at
the R prompt invokes \texttt{print.secr} which formats the key
results. Functions are provided for further computations on
\texttt{secr} objects (e.g., density as a derived parameter,
profile-likelihood confidence intervals for beta parameters, AIC model
selection, model averaging, likelihood ratio and score tests). Some of
these are listed in Appendix 3.

\subsection*{Documentation}
\addcontentsline{toc}{subsection}{Documentation}

The primary documentation for \textbf{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.

The consolidated help pages are also distributed as a pdf file that
may be accessed from within R using

<<eval=FALSE>>=
RShowDoc ('secr-manual', package='secr')
@

Other documentation in the form of pdf files based on Sweave vignettes
will be added from time to time. The `overview' link in the package
help index lists available vignettes. To list vignettes for all
packages use
<<>>=
vignette()
@

The same function may be used to view a particular vignette, for example
<<eval=FALSE>>=
vignette('sound')
@

\vspace{12pt}
The web page www.otago.ac.nz/density should be checked for news of
bug fixes and new releases.

\section*{Models in secr}
\addcontentsline{toc}{section}{Models in \textbf{secr}}

A family of capture--recapture models, such as the Cormack-Jolly-Seber
models for survival, may include submodels\footnote{This use of
  `submodel' is non-standard -- maybe we'll find a better term} that
allow for contingent variation in core parameters, including the
effects of covariates. Annual survival, for example, may vary with the
severity of winter weather, so it often makes sense to include a
measure of winter severity as a covariate. Gary White's MARK software
has been particularly successful in packaging open-population models
for biologists, and \textbf{secr} aims for similar flexibility.

The language of generalised linear models is convenient for describing
submodels (e.g. Huggins 1989, Lebreton et al. 1992). Each parameter is
treated as a linear combination of effects on its transformed (`link')
scale. This is useful for combining effects because, given a suitable
link function, any combination maps to a feasible value of the
parameter. The logit scale has this property for probabilities in (0,
1), and the natural log scale works for positive parameters i.e. (0,
$+\infty$). These are the link functions used most often in \textbf{secr},
but there are others, including the identity (null) link.

Submodels are defined symbolically in \textbf{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 \textbf{secr} uses that term to reduce confusion.  Four
real parameters are commonly modelled in \textbf{secr} 1.3; these are
denoted D (for density), g0, sigma and z.  Only the last three real
parameters, which jointly define detection probability as a function
of location, can be estimated directly when the model is fitted by
maximizing the conditional likelihood (CL = TRUE in
\texttt{secr.fit}).  D is then a derived parameter that is computed
from an \texttt{secr} object with the function \texttt{derived}. `z'
is a shape parameter that is used only when the detection function has
the `hazard-rate' form (Hayes and Buckland 1983).

For each real parameter there is a linear predictor of the form
$\vec{y} = \vec{X} \vec{\beta}$, where $\vec{y}$ is a vector of
parameter values on the link scale, $\vec{X}$ is a design matrix of
predictor values, and $\vec{\beta}$ is a vector of coefficients.  Each
element of $\vec{y}$ and corresponding row of $\vec{X}$ relates to the
value of the real parameter in a particular circumstance (e.g. density
at a particular point in space, or detection probability of an animal
on a particular occasion). The elements of $\vec{\beta}$ are
coefficients estimated when we fit the model. In MARK these are called
`beta parameters' to distinguish them from the transformed `real'
parameter values in $\vec{y}$. \textbf{secr} acknowledges this usage,
but also refers to beta and real parameters as `coefficients' and
`fitted values', a usage more consistent with modelling in R.  $\vec{X}$
has one column for each element of $\vec{\beta}$.  Design matrices are
described in more detail in the next section.

\subsection*{Design matrices}
\addcontentsline{toc}{subsection}{Design matrices}

A design matrix is specific to a `real' parameter. Each design matrix
$\vec{X}$ contains a column of `1's (for the constant or intercept
term) and additional columns as needed to describe the effects in the
submodel for the parameter.  Depending on the model, these may be
continuous predictors (e.g. air temperature to predict
occasion-to-occasion variation in g0), indicator variables (e.g. 1 if
animal $i$ was caught before occasion $s$, 0 otherwise), or coded
factor levels.  Within \texttt{secr.fit}, each design matrix is
constructed automatically from the input data and the model formula in
a 2-stage process.

First, a data frame is built containing `design data' with one column
for each variable in the formula.  Second, the R function
\texttt{model.matrix} is used to construct the design matrix.  This
process is hidden from the user.  The design matrix will have at least
one more column than the design data; there may be more if the formula
includes interactions or factors with more than two levels.  For a
good description of this general approach see the documentation for
RMark (Laake and Rexstad 2008).  The necessary design data are either
extracted from the inputs or generated automatically as explained in
later sections.  `Real' parameters fall into two groups: density (D)
and detection (g0, sigma and z).  Density and detection parameters are
subject to different effects, so they use different design matrices as
described in the next three sections.

\subsection*{Detection submodels}
\addcontentsline{toc}{subsection}{Detection submodels}

For SECR, we want to model the detection of each individual $i$ on
occasion $s$ at detector $k$.  Given $n$ observed individuals on $S$ occasions
at $K$ detectors, there are therefore $nSK$ detection probabilities of
interest.  We treat these as elements in a 3-dimensional array.
Strictly, we are also interested in the detection probabilities of
unobserved individuals, but these are estimated only by extrapolation
from those observed so we do not include them in the array.

In a null model, all $nSK$ detection probabilities are assumed to be
the same.  The conventional sources of variation in capture
probability (Otis et al. 1978) appear as variation either in the n
dimension (`individual heterogeneity' h), or in the $S$ dimension (`time
variation' t), or as a particular interaction in these two dimensions
(`behavioural response to capture' b).  Combined effects are possible.
SECR introduces additional complexity.

Detection probability in SECR is no longer a scalar (even for a
particular animal-occasion-detector combination); it is described by a
`detection function'. The detection function may have two parameters
(e.g. g0, sigma for a half-normal function), three parameters
(e.g. g0, sigma, z for the Hayes and Buckland hazard-rate function),
or potentially more.  Any of the parameters of the detection function
may vary with respect to individual (subscript $i$), occasion
(subscript $s$) or detector (subscript $k$).

The full design matrix for each detection submodel has one row for
each combination of $i$, $s$ and $k$.  Allowing a distinct probability for
each animal (the $n$ dimension) may seem excessive, and truly
individual-specific covariates are feasible only when a model is
fitted by maximizing the conditional likelihood (cf Huggins
1989). However, the full $nSK$ array is convenient for coding both
group membership (Lebreton et al. 1992, Cooch and White 2008) and
experience of capture, even when pure individual-level heterogeneity
cannot be modelled.

The programming gets even more complex. Analyses may combine data from
several independent samples, dubbed `sessions'. This adds a fourth
dimension of length equal to the number of sessions.  When finite
mixture models are used for detection parameters there is even a fifth
dimension, with the preceding structure being replicated for each
mixture class. Fortunately, \textbf{secr} handles all this and the
user need be concerned only with the model specification, which we
describe next.

\subsection*{Specifying effects on detection parameters}
\addcontentsline{toc}{subsection}{Specifying effects on detection parameters}

Effects on parameters of detection probability are specified with R
formulae. The variable names used in formulae are either names for
standard effects (Table \ref{tab:autocov}) or the names of user-supplied covariates.

\begin{table}[h]
\caption{Automatically generated predictor variables used in detection
  models}
\vspace{6pt}
\begin{tabular}{l l p{7cm}}
\hline\noalign{\smallskip}
 Variable & Description & Notes\\
\hline\noalign{\smallskip}
 g & group & interaction of the capthist individual covariates listed in argument \texttt{groups} of \texttt{secr.fit} \\
 t & time factor & one level for each occasion \\
 T & time trend  & linear trend over occasions on link scale \\
 b & learned response & step change in parameter after first
 detection of animal \\
 B & transient response & parameter depends on detection at previous
 occasion (Markovian response) \\
 session & session factor & one level for each session \\
 h2 & 2-class mixture & finite mixture model with 2 latent classes \\
\hline\noalign{\smallskip}
\end{tabular}
\label{tab:autocov}
\end{table}

\begin{table}
\caption{User-provided covariates used in detection models. The names
  of columns in the respective dataframes may be used in model formulae}
\vspace{6pt}
\begin{tabular}{l p{5cm} l}
\hline\noalign{\smallskip}
Covariate type & Data source & Notes\\
\hline\noalign{\smallskip}
 Individual & \texttt{covariates(capthist)} & conditional likelihood \\
 Time & \texttt{timecov} argument &  \\
 Detector & \texttt{covariates(traps(capthist))} &  \\
 Session & \texttt{sessioncov} argument & \\
\hline\noalign{\smallskip}
\end{tabular}
\label{tab:usercov}
\end{table}

Any name in a formula that is not in Table \ref{tab:autocov} is assumed to refer to a
user-supplied covariate. \texttt{secr.fit} looks for user-supplied
covariates in data frames embedded in the \texttt{capthist} argument
or supplied in the \texttt{timecov} and \texttt{sessioncov} arguments,
using the first match (Table \ref{tab:usercov}).


The formula for any detection parameter (g0, sigma, z) may be constant
($\sim$1, the default) or some combination of terms in standard R
formula notation (see help(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
\ref{tab:examples} for other examples.

\begin{table}
  \caption{Some examples of the \texttt{model} argument in \texttt{secr.fit}}
  \begin{tabular}{l p{8cm}}

\hline\noalign{\smallskip}
    Model & Description \\
\hline\noalign{\smallskip}

    \texttt{g0 $\sim$ 1}  & g0 is constant across animals, occasions and detectors \\
    \texttt{g0 $\sim$ b}  & learned response affects g0 \\
    \texttt{list(g0$\sim$b, sigma$\sim$b)} & learned response affects both g0
    and sigma \\
    \texttt{g0 $\sim$ h2}  & 2-class finite mixture for heterogeneity in g0 \\
    \texttt{g0 $\sim$ b + T} & learned response in g0 combined with trend over
    occasions \\
    \texttt{sigma $\sim$ g} & detection scale sigma differs between groups \\
    \texttt{sigma $\sim$ g*T} & group-specific trend in sigma \\
    \texttt{D $\sim$ cover} & density varies with 'cover' given in
    \texttt{covariates(mask)} \\
    \texttt{list(D$\sim$g, g0$\sim$g)} & both density and g0 differ
    between groups} \\
    \texttt{D $\sim$ session} & session-specific density \\
\hline\noalign{\smallskip}

  \end{tabular}
  \label{tab:examples}
\end{table}

For other effects, the design matrix for detection parameters may also
be provided manually in the argument \texttt{dframe} of
\texttt{secr.fit}.  This feature is untested.

\subsection*{Density submodels}
\addcontentsline{toc}{subsection}{Density submodels}

The SECR log likelihood is evaluated by summing values at points on a
`habitat mask' (the \texttt{mask} argument of \texttt{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. Other spatial covariates should be named columns in the
\texttt{covariates} attribute of the habitat mask.

\subsection*{Model fitting and estimation}
\addcontentsline{toc}{subsection}{Model fitting and estimation}

Models are fitted in \texttt{secr.fit} by numerically maximising 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 \texttt{make.mask}
or implicitly via the \texttt{buffer} argument).

The default maximisation algorithm is Newton-Raphson in the function
\texttt{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. Use
\texttt{confint.secr} for profile likelihood intervals and
\texttt{simulate.secr} for parametric bootstrap intervals (slow).

\section*{References}
\addcontentsline{toc}{section}{References}

\noindent Borchers, D. L., Buckland, S. T. and Zucchini, W. (2002) \emph{Estimating
animal abundance: closed populations}. Springer, London.

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

\noindent Cooch, E. and White, G. (eds) (2008) \emph{Program MARK: A Gentle
Introduction}. 6th edition. Available online at http://www.phidot.org.

\noindent Efford, M. G. (2004) Density estimation in live-trapping
studies. \emph{Oikos} \textbf{106}, 598--610.

\noindent Efford, M. G. (2009) \emph{DENSITY 4.4: software for spatially
explicit capture--recapture}.  Department of Zoology, University of
Otago, Dunedin, New Zealand http://www.otago.ac.nz/density.

\noindent 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) \emph{Modeling Demographic Processes in Marked
Populations}. Springer. Pp 255--269.

\noindent Efford, M. G., Dawson, D. K. and Borchers, D. L. (2009)
Population density estimated from locations of individuals on a
passive detector array. \emph{Ecology} \textbf{90}, 2676--2682.

\noindent Hayes, R. J. and Buckland, S. T. (1983) Radial-distance
models for the line-transect method. \emph{Biometrics} \textbf{39}, 29--42.

\noindent Huggins, R. M. (1989) On the statistical analysis of capture
experiments.  \emph{Biometrika} \textbf{76}, 133--140.

\noindent Laake, J. and Rexstad E. (2008) Appendix C. RMark - an
alternative approach to building linear models in MARK. In: Cooch,
E. and White, G. (eds) \emph{Program MARK: A Gentle Introduction}. 6th
edition. Available online at http://www.phidot.org.

\noindent 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. \emph{Ecological
Monographs} \textbf{62}, 67--118.

\noindent Otis, D. L., Burnham, K. P., White, G. C. and Anderson,
D. R. (1978) Statistical inference from capture data on closed animal
populations. \emph{Wildlife Monographs} \textbf{62}.

\noindent Royle, J. A., Nichols, J. D., Karanth, K. U. and
Gopalaswamy, A. M. (2009). A hierarchical model for estimating density
in camera-trap studies. \emph{Journal of Applied Ecology} \textbf{46}, 118--127.

\newpage

\section*{Appendix 1. A simple secr analysis}
\addcontentsline{toc}{section}{Appendix 1. A simple \textbf{secr} analysis}

\vspace{12pt}

A simple analysis might look like this. We start by loading the
package and constructing an object \texttt{myCH} that contains both
the captures and the trap locations.

% suppress continuation prompts
<<echo=false>>=
options(continue=" ")
options(width=70)
@

<<>>=
library(secr)                                       # load library
mytraps <- make.grid(nx = 10, ny = 10,              # build detector array
    spacing = 30, originxy = c(365,365))
mycapt <- read.captures (file = 'capt.txt')         # import capture data
myCH <- make.capthist (mycapt, mytraps, fmt='XY')   # build capthist object

@

Next we fit two simple models and compare them with AIC. We set
\texttt{trace = FALSE} to reduce the volume of output, but the default
\texttt{trace = TRUE} is usually better.

<<eval=TRUE>>=
secr0 <- secr.fit(myCH, model = g0~1, trace = FALSE) # null model
secrb <- secr.fit(myCH, model = g0~b, trace = FALSE) # trap response model
AIC (secr0, secrb)                                   # compare
@

A model with learned trap response (g0$\sim$b) showed no improvement
in fit over a null model (g0$\sim$1).  In this instance the estimates
of density from the two models were also very close (not shown) and we
rely on the null model for estimation.

<<>>=
secr0                                                # display estimates
@

The density estimate is 5.48 ha\textsuperscript{--1} (95\% confidence
interval 4.35--6.90 ha\textsuperscript{--1}).  The calculation used a
default habitat mask with a buffer of 100 m around the detectors; this
is reasonable in the light of the estimate of sigma (29.4 m).


\newpage
\section*{Appendix 2. Software feature comparisons}
\addcontentsline{toc}{section}{Appendix 2. Software feature comparisons}

\vspace{6pt}
\textbullet \hspace{4pt} full
implementation; \textopenbullet \hspace{4pt} incomplete or inferior implementation.
\vspace{6pt}

\begin{table}[!h]
\begin{tabular}{p{7.3cm} c c c}
\hline\noalign{\smallskip}

Feature	& DENSITY 4.4 &	\textbf{secr} 1.2 & \textbf{secr} 1.3 \\
\hline\noalign{\smallskip}
\\
\emph{General} \\
Graphical interface & \textbullet & \textopenbullet & \textopenbullet \\
Inverse prediction (IP SECR) & \textbullet & \textbullet & \textbullet \\
Maximum likelihood estimation (ML SECR) & \textbullet & \textbullet & \textbullet \\
Non-spatial open-population models (CJS etc.)& \textbullet & & \\
Simulation of spatial sampling	& \textbullet & \textopenbullet & \textopenbullet \\
Build detector arrays	& \textbullet & \textopenbullet  & \textopenbullet \\
Control of random number generator	& \textopenbullet & \textbullet & \textbullet \\
\\
\emph{ML SECR} \\
Jackknife confidence intervals	& \textopenbullet & & \\
Profile likelihood confidence intervals & \textbullet & \textbullet & \textbullet \\
Set of detectors used may vary with occasion & \textbullet & \textbullet & \textbullet \\
Fixed parameters	& \textopenbullet & \textbullet & \textbullet\\
Parametric bootstrap	& \textopenbullet & \textbullet & \textbullet\\
Between-session models & \textbullet & \textbullet & \textbullet \\
Mixture models for individual heterogeneity & \textbullet & & \textbullet \\
Confidence ellipses & \textbullet &  & \textbullet \\
Formula-based model notation & & \textbullet & \textbullet\\
Density models (inhomogeneous 2-D Poisson) &  & \textbullet& \textbullet \\
Terminology consistent with MARK\footnotemark[1] & & \textbullet & \textbullet \\
Groups (e.g. males \& females)	&  & \textbullet & \textbullet\\
Score tests for model selection & & \textbullet & \textbullet \\
Model averaging	& & \textbullet & \textbullet\\
Within-session variation in hazard-rate z & & \textbullet & \textbullet\\
`pdot' criterion for region of integration & & \textbullet & \textbullet\\
Structural relationships between real parameters & & \textbullet & \textbullet \\
\\
\emph{Detector types} \\
Single-catch trap (not MLE) & \textopenbullet & \textopenbullet & \textbullet\\
Multi-catch trap & \textbullet & \textbullet & \textbullet\\
Proximity  & \textbullet & \textbullet & \textbullet\\
Signal strength (acoustic)\footnotemark[2]&&&\textbullet \\
Count\footnotemark[2] &&&\textbullet\\
Polygon\footnotemark[3]  &&&\textopenbullet\\
Transect\footnotemark[3]  &&&\textopenbullet\\
\hline\noalign{\smallskip}
\end{tabular}
\end{table}
\footnotetext[1]{`groups', `real' parameters, `beta' parameters}
\footnotetext[2]{Efford, Dawson \& Borchers (2009) \emph{Ecology}
  \textbf{90}, 2676--2682}
\footnotetext[3]{Efford in prep.}

\newpage
\section*{Appendix 3. Functions in \textbf{secr} arranged according to use}
This list groups the main functions of \textbf{secr} 1.3. Many
functions for data manipulation and plotting are omitted. S3 methods
are marked with an asterisk *
\addcontentsline{toc}{section}{Appendix 3. Functions in
  \textbf{secr} 1.3}

\begin{longtable}{l p{27mm} p{9cm}}
\multicolumn{3}{l}{\emph{Manipulate core objects}} \\[4pt]
& \texttt{make.grid}	& construct detector array \\
& 	\texttt{read.traps}	& input detector locations from text file \\
& 	\texttt{read.captures}	& input detection (capture) data in Density format \\
& 	\texttt{make.capthist}	& form \texttt{capthist} from \texttt{traps} and detection data \\
& 	\texttt{make.mask}	& construct habitat mask (mesh) \\
& 	\texttt{sim.capthist}	& simulate capture histories \\
& 	\texttt{verify}*	& check \texttt{capthist}, \texttt{traps} or \texttt{mask} for internal consistency \\[6pt]

\multicolumn{3}{l}{\emph{Extract or replace attributes of} \texttt{traps} \emph{object}} \\[4pt]
& 	\texttt{covariates}*	& detector-level covariates \\
& 	\texttt{detector}*	& detector type (`multi', `proximity' etc.) \\
& 	\texttt{usage}*	        & disable detectors (occasion- and detector-specific ) \\[6pt]

\multicolumn{3}{l}{\emph{Extract or replace attributes of} \texttt{capthist} \emph{object}} \\[4pt]
& 	\texttt{covariates}*	& individual-level covariates, including grouping factors \\
& 	\texttt{session}*	& session identifier(s) \\
& 	\texttt{traps}*	& embedded \texttt{traps} object(s) \\[6pt]

\multicolumn{3}{l}{\emph{Fit SECR model}} \\[4pt]
& 	\texttt{secr.fit}	& maximum likelihood fit; result is a fitted \texttt{secr} object \\
& 	\texttt{ip.secr}	& fit simple SECR model by simulation \& inverse prediction \\[6pt]

\multicolumn{3}{l}{\emph{Operate on fitted} \texttt{secr} \emph{object(s)}} \\[4pt]
& 	\texttt{AIC}*	& model selection, model weights \\
& 	\texttt{coef}*	& `beta' parameters \\
& 	\texttt{collate}	& tabulate estimates from several models \\
& 	\texttt{confint}*	& profile likelihood confidence intervals \\
& 	\texttt{derived}	& density from conditional likelihood models \\
& 	\texttt{deviance}*	& model deviance \\
& 	\texttt{df.residual}*	& degrees of freedom for deviance \\
& 	\texttt{LR.test}	& likelihood-ratio test of two models \\
& 	\texttt{model.average}	& combine estimates using AICc weights \\
& 	\texttt{plot}*		& plot detection functions with confidence bands \\
& 	\texttt{predict}*	& `real' parameters for arbitrary levels of predictor variables \\
& 	\texttt{score.test}	& model selection with score statistic using observed information \\
& 	\texttt{simulate}*	& generate realisations of fitted model \\
& 	\texttt{sim.secr}	& parametric bootstrap \\
& 	\texttt{vcov}*		& variance-covariance matrix of `beta'
or `real' parameters \\[6pt]
\pagebreak
\multicolumn{3}{l}{\emph{Miscellaneous}} \\[4pt]
& 	\texttt{autoini}	& generate starting values of D, g0 and sigma for \texttt{secr.fit} \\
& 	\texttt{counts}		& summary data from \texttt{capthist} object \\
& 	\texttt{dbar}		& a simple (and unreliable) home-range measure \\
& 	\texttt{distancetotrap}	& from an arbitrary set of points \\
& 	\texttt{nearesttrap}	& from an arbitrary set of points \\
& 	\texttt{pdot}		& location-specific net probability of detection \\
& 	\texttt{RPSV}		& another simple and unreliable home-range measure \\[6pt]

\multicolumn{3}{l}{\emph{Datasets [restore with} \texttt{data(xxx)}\emph{]}} \\[4pt]
& 	\texttt{rawdata}	& dataframes of raw data \\
& 	\texttt{captdata}	& \texttt{rawdata} as a \texttt{capthist} object \\
& 	\texttt{secrdemo}	& \texttt{secr.fit} applied to some simulated data \\
& 	\texttt{ovenbird}	& multi-year mist-netting study of
ovenbirds \emph{Seiurus aurocapilla} at a site in Maryland, USA. \\
& 	\texttt{ovensong}	& acoustic detections of ovenbirds (Dawson \& Efford \emph{Journal of Applied Ecology} \textbf{46}, 1201--1209) \\
& 	\texttt{possum}	& brushtail possum \emph{Trichosurus vulpecula} live trapping at Waitarere, North Island, New Zealand April 2002 (Efford et al. 2005 \emph{Wildlife Society Bulletin} \textbf{33}, 731--738) \\[6pt]
\end{longtable}

\end{document}
