FAQ (frequently asked questions) for program DENSITY and the R package secr


Postby egc » Fri Mar 19, 2010 7:53 pm


This FAQ provides general information on the software packages DENSITY and secr for spatially explicit capture-recapture analysis and answers a few common technical questions. We will occasionally edit, update and tweak the FAQ. For this reason, these comments are not to be cited. Before posting on the forum, please digest the answer to General question #6.

General questions

1. What is ‘spatially explicit capture-recapture’?

Spatially explicit capture-recapture (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. 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 type of detector used and the locations of detectors figure in the fitted model.

2. Why two packages?

The program DENSITY provides a graphical interface to SECR methods that has been accepted by many biologists since it was first released in 2003. 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 secr was written to address these weaknesses and enable further development. It implements almost all the methods and options described in Efford (2004), Borchers and Efford (2008) and Efford, Dawson & Borchers (2009), and others yet to be published. If you already use R from the command prompt, or can afford some time to learn how, then secr is the way to go. See an Appendix in the overview pdf (link below) for a comparison of features. DENSITY does admittedly have a few nice features not in secr, particularly direct use of ESRI shapefiles as habitat masks and some simulation options.

3. What kind of computer do I need?

SECR is computer-intensive so get as fast a machine as you can. DENSITY requires a recent version of Windows (e.g., XP, Vista or Windows 7); it may run under other OS in a Windows emulator, but this has not been tested. secr should run on any system with R 2.10.0 or a later version (please report any problems).

4. Where can I get the software?

For DENSITY, follow the download link on the DENSITY homepage http://www.otago.ac.nz/density.
For secr point your browser at http://www.cran.r-project.org or use the menu in your R GUI to install the package directly from CRAN. Binaries are provided on CRAN for Windows and Mac operating systems; on other systems you may need to install from the tar.gz source file (seek help from your local R expert, not here). Remember to load the package each time you want to use it (e.g. library(secr)).

5. How do I get started?

You’ll need some background on how SECR works. Efford, Borchers & Byrom (2009) is a starting point with citations of earlier papers; some pdfs are available at http://www.otago.ac.nz/density/publications.html. DENSITY has a built-in help system: follow the ‘Getting started’ and ‘Main screen’ links at the end of the Introduction page. You’ll find descriptions of the text file formats for data input (or double-click on the filename boxes in DENSITY to see the default data sets). Files in these formats may also be used with secr.

If you are taking the plunge into secr then read the document http://www.otago.ac.nz/density/pdfs/secr-overview.pdf. Once you have installed and loaded the package in R, read the help page for the function secr.fit and try some examples. Using help in R is simple: just type a question mark followed by the function name (?secr.fit in this case). If you don’t know where to start, try a double question mark followed by a keyword or phrase (??'model-average'). There is an index to the help pages: find a link to the index on the very last line of any help page (assuming you are viewing the help in an html browser). Documentation is installed in a folder that may be accessed through the ‘overview’ or ‘browse directory’ links at the top of the index. This currently includes tutorial ‘vignettes’ on acoustic models and finite mixture models.

6. How and when should I post a question to the forum?

This is really about observing general forum etiquette, posing your question so it has the best chance of getting answered, and not irritating those who volunteer support. First, try hard to find the answer in the documentation provided. Use the excellent forum search facility to check previous posts. Make your question short and specific. Briefly state the context (study animal, study design, objective), the operating system (e.g. Windows XP) and the version of the software you are using (e.g. DENSITY 4.4.4). If you think you have found a bug in secr (there are some) then cut and paste the output from sessionInfo() into your posting. If your question is more general than ‘just’ SECR (e.g. about philosophies of model selection) then send it to the ‘General questions’ forum.

7. How should I cite DENSITY or secr?

For DENSITY see the Recommended citation near the end of Contents in the built-in help. For secr, type citation(secr) at the R prompt.

8. What about Bayesian methods?

In DENSITY and secr, models are fitted mostly by numerically maximising the likelihood (the exception is the ‘simulation and inverse prediction’ method for data from single-catch traps). Andy Royle and collaborators have recently shown how data augmentation and Markov chain Monte Carlo methods may also be used to fit SECR models (e.g., Royle & Young 2008, Royle et al. 2009, and the SPACECAP package in R). Some models, particularly those with non-independence between animals, are easy to fit by a simulation-based approach such as MCMC, but impossible or very hard to fit by maximizing the likelihood (no such ‘difficult’ models are included in SPACECAP). Where likelihood-based methods do work they are probably cleaner (less subject to numerical issues, easier model selection etc.) and faster. Both approaches and their associated software will continue to evolve, so don’t expect a final answer on which is superior!

Technical Questions

1. I cannot open the DENSITY help file. What is wrong?

Check that there is a file density4.chm in the folder with density4.exe. density4.chm is a compiled Windows help file, created with the Microsoft HTML help compiler V 1.4. It is seen by the operating system as an executable file, and treated by some systems as a security risk. This is the most likely cause of your problem. In Windows XP, try opening the help file from Windows Explorer and overriding any security warning, or right-click on the help file, select Properties, click Unblock and Apply. This gets harder in later versions of Windows, and it may even be impossible when you are accessing the program over a network. Ultimately, seek local IT assistance as there’s little we can do to help.

2. How many captures and recaptures do I need to use SECR?

It is critical to get enough recaptures. To estimate density at all by SECR you will probably need at least 10 recaptures, and 20 is a safer minimum. Aim for many more than the minimum! Precision improves with more recaptures, initially rapidly and then more slowly over 50 or so recaptures (e.g. Efford, Dawson & Robbins 2004 Fig. 2). Some studies have many recaptures of few animals (<20 individuals); estimation is possible, but confidence intervals will be very wide because of inherent spatial uncertainty (see below). To fit complicated models with covariates, finite mixtures, trends etc. you will need more data.

3. How large should I make the buffer?

First, note that the trap layout buffer (DENSITY) or the buffer argument of secr.fit (secr) is just a means to an end. It is one way to indicate a region containing the home-range centres of all potentially detected animals. The region is called a ‘mesh’ in DENSITY and a ‘mask’ in secr. The likelihood for SECR estimates of density is evaluated by integrating over this region. There are other ways to define the region - see Options | Computation and Options | Habitat mask in DENSITY, and make.mask in secr. Making the region too large should not noticeably affect the final estimate because range centres distant from the detectors contribute very little to the likelihood (but see next paragraph). A suitable buffer is typically 3 to 5 times the detection scale (sigma) of a half-normal detection model. This assumes some prior knowledge of sigma. Sigma is usually a bit less than the trap-revealed range statistic RPSV (calculated by both DENSITY and secr), so a buffer 4 times RPSV is fairly safe. If you have doubts then simply fit models with varying buffer width to verify that it does not affect the result. A shortcut in DENSITY is to use Tools | ML SECR log likelihood (main menu) to vary the buffer over a range of values and view the effect on the computed log likelihood.

Using a very large buffer does raise a problem. Integration of the likelihood is done by summing over points in the mask. By default the number of points is fixed, so increasing the extent of the mask also increases the coarseness of the mask grid (pixel size). When the grid is too coarse, numerical maximisation of the likelihood may be affected in unpredictable ways. An obvious solution is to fix the pixel size or grid spacing, but this would have to be tuned to the behaviour of each species. Either way, users need to be aware of the issues and make sure that the extent of the mask and the implied pixel size make sense for their study, possibly using the tools in DENSITY to determine that these arbitrary choices do not noticeably affect the likelihood or the parameter estimates. Attributes of the mask (extent and spacing of points) should be reported in the Methods when publishing estimates of density.

4. What is the connection between the buffer width and conventional ‘boundary strip width’?

There is none. Conventionally a boundary strip equal to one home range radius was wrapped around a trap layout to estimate an ‘effective trapping area’. SECR replaces the ‘effective trapping area’ with a more rigorous probabilistic model of detection. A buffer strip is sometimes used in SECR to define the area in which home-range centres may lie (see preceding FAQ).

5. Why are my confidence intervals for estimated density so wide?

Ultimately: because you have too few data. More constructively: What is the basis for your comparison? If you are tempted to compare SECR estimates with those from D-hat = N-hat/A-hat, make sure you allow for uncertainty in A-hat as well as N-hat (see Calculator on 'ETA density tab' in DENSITY). Also, the intervals reported by DENSITY are spatially unconditional; that is, they include spatial variation in population density that is 'conditioned out' of conventional ETA estimates (N-hat/A) (but not estimates by conventional distance sampling). DENSITY provides an approximation to the conditional intervals (see Adjusted SE in the Help index). And remember that your estimate of N-hat will have spurious precision if it does not model individual heterogeneity due to home range location - this is automatic in SECR.

6. How do I calculate the goodness-of-fit of an SECR model?

In principle, one may perform a parametric bootstrap on the deviance or the deviance divided by the residual degrees of freedom. See the help page for sim.secr for an example of how to do this in secr. There are major drawbacks to this ‘obvious’ method – it can take an extremely long time (depending on the bootstrap sample size), and it’s not established that this is a sensitive or meaningful test, given the inherent sparseness of spatial capture histories. For those of you with a MARK background: there is no established method in SECR for estimating overdispersion (c-hat) and hence calculating QAIC for multi-model inference. We’re hoping these issues will catch the attention of a creative statistician!

7. Why do I get different answers from secr and DENSITY?

Strictly this should not happen if you have specified the same model and likelihood, although you may see a little variation due to the different maximization algorithms (compare Options | Computation in DENSITY and the ‘method’ argument of secr.fit in secr). Likelihoods (and estimates) may differ if you use different integration meshes (habitat masks), which can easily happen because the programs differ in how they set up the mesh. If you want to make a precise comparison, save the Density mesh to a file and read it into secr, or vice versa.
Extreme data, especially rare long-distance movements, may be handled differently by the two programs. The 'minprob' component of the 'details' argument of secr.fit sets a threshold of probability for capture histories (smaller values are all set to minprob), whereas Density has no explicit limit. In the current version of secr, minprob defaults to 1e-50. If you find a discrepancy with Density it may be worth lowering minprob even further.

8. I keep getting warning messages in secr. Should I be worried?

As a rule, no. Warnings mostly remind you that you have relied on a default value for an important function argument, such as the type of detection function. They are for your information, rather than to raise alarm. If they really bug you then change the option ‘warn’ (e.g. options(warn=-1) for no warnings) or wrap the call of the offending function with suppressWarnings().

9. I cannot find some secr functions.

Method functions for S3 classes cannot be listed in the usual way by typing the function name at the R prompt because they are 'hidden' in a namespace. Get around this with getAnywhere. For example: getAnywhere(print.secr).

10. How should I model data from single-catch traps?

When animals can be caught in only one trap at a time the likelihood is intractable and we are reduced to (i) using simulation-based methods or (ii) using a likelihood designed for multi-catch traps and hoping estimation is robust to model mis-specification. The simulation-based method proposed in Efford (2004) is ‘inverse prediction’; it is available in both DENSITY (as ‘IP SECR’) and secr (function ip.secr). It works well for simple data, but does not allow the fitting of complex models or support any sort of model selection. The alternative, to use the multi-catch likelihood, does seem robust and is recommended at least when trap saturation is low or one is interested only in estimates of density and detection scale. The trouble with using the multi-catch likelihood is that estimates of the intercept of the detection function (g0) will be biased downwards, perhaps substantially (see e.g. Efford, Borchers & Byrom 2009). This is only a problem if you need to use those estimates, for example to simulate variations on the trap layout.

Alert users have asked the follow-on question: are the results of model selection reliable in this case? Does the basic model mis-specification invalidate other comparisons such as between multi-catch models with and without a learned trap response? This question has yet to be answered empirically. We expect on intuitive grounds (!) that such comparisons are fairly safe, even if not 100%.

11. In DENSITY, why do some parameters default to an ‘Identity’ link and how do I obtain estimates (predicted or ‘real’ values) for when covariates are not at their base level?

The DENSITY implementation of within-session models treats the ‘beta’ parameter for the intercept differently to other coefficients of the linear predictor. The intercept (constant) has a direct relation via the link function to the base level of the corresponding real parameter. Hence the row in the log table for the intercept ‘beta_0’ parameters gives the link function for the linear predictor and an inverse-transformed ‘Estimate’ that is the value of the named parameter when all covariates are zero (or there are no covariates). Other beta parameters cannot be interpreted in isolation as estimates of real parameters on the untransformed scale. They are assigned an ‘Identity’ link and left on the transformed scale. The link that matters is the one next to the intercept beta parameter, which is named for the corresponding ‘real’ parameter (g0, sigma etc.).

To estimate a ‘real’ parameter for a non-zero value of a covariate (i.e. not at the base level), form the linear predictor using the coefficients in the ‘Value’ column and untransform using the link function for the intercept parameter. Consider, for example, a ‘learned response’ model for g0:

Code: Select all
Parameter    Value SE.Value     Link   Par.Name  Estimate …
        1 -0.95317  0.22699    Logit         g0   0.27825 …
        2  3.38024  0.04443      Log      Sigma  29.37795 …
        3 -0.03162  0.23448 Identity g0[b] beta  -0.03162 …   

We use g0(x) = inverse logit (beta_0 + beta_1 * x), where x is an indicator variable for whether an animal has been caught before (x = 1) or not (x = 0). In the example, beta_0 = –0.95317 and beta_1 = –0.03162. The inverse logit function is f(y) = 1/(1+exp(–y)). This gives g0 = 1/(1 + exp(0.95317)) = 0.27825 for a naïve animal, and g0 = 1/(1 + exp(0.95317 + 0.03162)) = 0.27194 for an animal that has been caught before. These data were simulated without a learned response, so it’s reassuring the difference is small.


Borchers DL, Efford MG 2008. Spatially explicit maximum likelihood methods for capture–recapture studies. Biometrics 64: 377–385.

Efford MG 2004. Density estimation in live-trapping studies. Oikos 106, 598–610.

Efford MG, Borchers DL, Byrom AE 2009. Density estimation by spatially explicit capture-recapture: likelihood-based methods. In: DL Thomson, EG Cooch, MJ Conroy (eds) Modeling Demographic Processes in Marked Populations. Springer, New York. Pp. 255–269.

Efford MG, Dawson DK, Borchers DL 2009. Population density estimated from locations of individuals on a passive detector array. Ecology 90: 2676–2682.

Efford MG, Dawson DK, Robbins CS 2004. Density: software for analysing capture-recapture data from passive detector arrays. Animal Biodiversity and Conservation 27: 217–228.

Royle JA, Young KV 2008 A hierarchical model for spatial capture–recapture data. Ecology 89: 2281–2289.

Royle JA, Nichols JD, Karanth KU, Gopalaswamy AM 2009. A hierarchical model for estimating density in camera-trap studies. Journal of Applied Ecology 46: 118–127.
Site Admin
Posts: 163
Joined: Thu May 15, 2003 3:25 pm

Return to FAQ

Who is online

Users browsing this forum: No registered users and 0 guests