Getting started with secrapp 1.3
Murray Efford
2020-09-09
- Introduction
- Example data
- Step 1. Data preparation (text files)
- Step 2. Main screen – orientation
- Step 3. Data input and summary
- Step 4. Specify and fit a model
- Step 5. Review and evaluate results
- Advanced
- Troubleshooting
- Limitations
- References
- Appendix 1. A general description of SECR data and models
Introduction
This tutorial is a guide for those taking their first steps in fitting spatially explicit capture–recapture (SECR or SCR) models with the Shiny application secrapp 1.3, an interface to the R package secr. The application runs simple SECR analyses on a University of Otago machine through your web browser. No setup is required. You can also run it on your own machine directly from GitHub.
See Appendix 1 for an introduction to SECR models with a list of key assumptions and data requirements. See the tutorial secr-tutorial.pdf if you want to use secr from the R command line.
Thanks to Greg Trounson for supporting secrapp at the University of Otago, and to Ian Durbach for suggesting various improvements.
Example data
We use the Alaskan snowshoe hare data of Burnham and Cushwa as an example. This dataset was first presented by Otis et al. (1978) and has been much used in the exploration of models for heterogeneous capture probability.
“In 1972, Burnham and Cushwa (pers. comm.) laid out a livetrapping grid in a black spruce forest 30 miles (48.3 km) north of Fairbanks, Alaska. The basic grid was 10 x 10, with traps spaced 200 feet (61 m) apart. Trapping for snowshoe hares was carried out for 9 consecutive days in early winter. Traps were not baited for the first 3 days, and therefore we have chosen to analyze the data from the last 6 days of trapping.”
Otis et al. (1978:36)
The raw data are available from www.otago.ac.nz/density/examples as either an Excel spreadsheet hareCH6.xlsx or two text files hareCH6trap.txt and hareCH6capt.txt.
Step 1. Data preparation (text files)
Raw data may be provided in text files or Excel spreadsheets (here we use text files). Full details are in secr-datainput.pdf. Data files should be prepared in a text editor (not Word) or Excel before you start secrapp. To follow along with this tutorial you should first download the example data files hareCH6trap.txt and hareCH6capt.txt to a folder on your machine.
Two text files are needed: one with coordinates of the detector locations, and the other with detections (captures) of marked animals at particular times and detectors. Lines starting with the comment character “#” are ignored (column headings are shown here just for clarity).
1a. Detector layout
Each line in the detector (‘trap’) file has the identifier, x- and y-coordinates of one detector. For example
# Burnham and Cushwa snowshoe hare trap layout
# Detector x y
0101 0 0
0201 60.96 0
0301 121.92 0
...In the hare example, the first detector (trap) has identifier ‘0101’ and is located at the (relative) coordinates (0,0). Further columns are used when not all detectors are used on each sampling occasion, or to add covariates (see secr-datainput.pdf). secr will assume distances are in metres.
Relative coordinates usually suffice for small geometric arrays. Geographic coordinates (latitude and longitude from GPS) should be projected to a Cartesian coordinate system such as UTM. If you’re familiar with R then the functions project or spTransform in package rgdal may help. For a 2-column matrix (longitude, latitude) and known UTM zone (18) and hemisphere (north):
longlat <- cbind(-76.817, 39.054)
rgdal::project (longlat, "+proj=utm +zone=18 +north")## [,1] [,2]
## [1,] 342777 43243401b. Captures
Each row in the detection (‘capture’) file corresponds to one event - either a detection (capture) or a re-detection (recapture). The first column identifies a ‘session’ or independent block of data - a simple study may have just one session. “ID” is an alphanumeric individual identifier (e.g., a tag number). Here animal “1” was detected on occasion 2 at detector “0201”.
# Burnham and Cushwa snowshoe hare captures
# Session ID Occasion Detector
wickershamunburne 1 2 0201
wickershamunburne 19 1 0501
wickershamunburne 72 5 0601
...Step 2. Main screen – orientation
On starting secrapp version 1.3 you will see an Introduction screen with links to various resources. It helps to use full-screen mode in your browser - F11 on your keyboard will probably toggle this.
Move directly on to the Main screen.
The Main screen has almost everything you need to load data and fit SECR models, but it’s a bit complex. Take some time to locate the following sections –
- Navigation panel (secr app 1.3)
- Data input
- Model specification
- Action buttons
- Results (read-only)
- Code (read-only)
- Notification (‘waiting for input’)
Step 3. Data input and summary
The best way to see how this all works is to load some real data, first the detector layout and then the captures.
3a. Detector layout
Load the locations of the traps by selecting ‘hareCH6trap.txt’ with the ‘Browse’ button. (Of course you may substitute files you have prepared for your own study, but we follow through here with the snowshoe hare example).
Specifying the correct ‘Detector type’ is important for later analyses. The common options are listed below; see secr-overview.pdf for more. Hares were caught in single-catch traps, so select detector type ‘single’.
Table 1. Common detector types
| Detector type | Description | Example |
|---|---|---|
| single1 | traps that catch one animal at a time | Longworth trap |
| multi | traps that may catch more than one animal at a time | Ugglan trap, mist net, pitfall trap |
| proximity | records presence at a point without restricting movement | automatic camera, DNA hair snag |
| count2 | proximity detector allowing >1 detection per animal per occasion | automatic camera |
| polygon3 | perimeter(s) of one or more areas searched for cues | quadrat searched for scat |
| polygonX3 | perimeter(s) of one or more areas searched for animals | area searched for animals |
1. There is strictly no SECR model for this data type; the ‘single’ detector type is switched automatically to ‘multi’ at the time a model is fitted. Estimates of the detection parameter g0 are biased, but density estimates are essentially unbiased (Efford et al. 2009).
2. Counts also arise when a binary proximity dataset is collapsed from several occasions to one occasion. Each count is then a binomial variable with size equal to the number of collapsed occasions. This happens automatically by default when proximity data are analysed unless there is a reason not to (e.g., need to model between-occasion variation in detection). Use the fastproximity details setting to switch this off.
3. Area search uses the ‘polygon’ or ‘polygonX’ detector type. Each row in the detector file then defines a vertex of the searched polygon(s); see secr-datainput.pdf for directions. With polygonX detectors an individual may be recorded only once per occasion.
When the detector file loads you will see a summary of the detector array in the Results panel, and a map appears on the Array tab.
3b. Captures
Next browse to the capture file ‘hareCH6capt.txt’. Do this only after selecting the Detector file. Change the ‘Format’ field from ‘trapID’ to ‘XY’ if your capture file uses that format (it’s needed for detector types ‘polygon’ and ‘polygonX’).
The ‘show file’ link lets you review the text file (useful to check format or covariates). The ‘filter’ link lets you restrict analysis to a subset of the input (see Advanced – filtering).
3c. Data verification
Some checks are performed as data are loaded (e.g., Do all detectors in the capture file match the detector file?). You should also review the loaded data with the tools we describe here.
Once the capture file loads, the Results panel provides a summary of the full capthist object, relating each capture to the coordinates in the detector file. Pay particular attention to the table of counts:
The last column (‘Total’) is a simple sum over other columns except for M(t+1), which is the cumulative total of u.
The counts ‘n’, ‘u’, ‘f’ and ‘M(t+1)’ will make perfect sense if you are familiar with Otis et al. (1978), but just in case you’re not…
Table 2. Summary counts
| Count | Description |
|---|---|
| n | number of distinct individuals detected on each occasion t |
| u | number of individuals detected for the first time on each occasion t |
| f | number of individuals detected on exactly t occasions |
| M(t+1) | cumulative number of detected individuals on each occasion t |
The Array tab now maps the detectors with the detections overlaid. Captures on different occasions are spread radially from the detector location to reduce overlap; see Options | ‘Radial displ.’ to adjust the spread.
Check both the summary and the array plot to be sure secrapp has interpreted your data correctly and there are no gross errors in data entry.
Use ‘Select animal’ to scroll through animals, highlighting one at a time and connecting its successive detections. ORL stands for ‘observed range length’, the maximum distance between detections.
The Moves tab shows the distribution of distances between detections; this can reveal data errors and help you decide whether SECR models are suitable for your data (See Appendix 1).
Step 4. Specify and fit a model
Once you’re comfortable that the data have loaded correctly you can specify and fit a model.
4a. Model specification
The key settings are
Detection function – HN (halfnormal) or EX (negative exponential) will usually suffice, but see secr-overview.pdf or the Help screen.
Likelihood – ‘Full’ likelihood includes density as a parameter in the model. ‘Conditional’ likelihood (conditional on n - see next) estimates only the detection parameters; density may be estimated as a derived parameter. The choice constrains the types of variation that can be included (density covariates require Full likelihood; individual detection covariates mostly require Conditional likelihood).
Distribution of n – ‘n’ here is the variable corresponding to the number of detected individuals (confusingly, also called M(t+1) above). Binomial-n implies fixed number of animals in the masked area, whereas Poisson-n treats that number as variable. Poisson-n has some advantages (robustness to the choice of likelihood, independence of mask area), but leads to (slightly) less precise estimates of density.
Model – A formula for each parameter, representing possible variation in that parameter that may be of inherent interest (e.g., D ~ session) or improve fit by relaxing assumptions of the detection model (e.g., g0 ~ bk for a change in detection intercept after first capture at a detector). The default is no modelled variation (~ 1); consult secr-overview.pdf and a later sections for other options.
See Advanced for other options.
4b. Habitat mask
SECR typically considers animals in a region extending some ‘buffer’ distance from the detectors. The region is represented by a fine mesh of points called the habitat mask. If the buffer is too small then density will be overestimated.
A note in the Model panel indicates the current (default) buffer width and the number and spacing of points on the habitat mask. These may be wildly inappropriate. To change them and view the mask use the ‘Habitat mask’ screen (you can get there via the navigation panel or the edit link of the Model panel).
Spacing is controlled by variable ‘nx’, the number of cells in the x-direction. Increasing buffer width increases the spacing of points.
For the snowshoe hares we suggest a buffer width of 250 m (about 4x the spatial scale parameter sigma). Use the ‘edit’ link to access the Habitat mask screen and set ‘Buffer width’ to 250 m.
Setting a buffer width for your own data will require some homework to understand the tradeoffs involved (following box). For speed secrapp defaults to a coarser spacing of mask points (nx = 32) than the secr function make.mask (nx = 64); for serious analyses it may pay to increase nx.
SECR calculations become tractable when we restrict ourselves to a region near the detectors. The region (‘area of integration’, ‘habitat mask’ or sometimes ‘state space’) should exclude non-habitat; otherwise, it is only necessary that it exceed some minimum extent related to the scale of detection: too small and density estimates will be biased. As far as we know, the snowshoe hare traps were surrounded by suitable habitat. Specifying the buffer width is therefore sufficient to define the habitat mask (see the Habitat mask screen for other options and graphics). Buffers and habitat masks are covered at length in secr-habitatmasks.pdf.
A good starting point for the buffer width is 4 x sigma, where sigma is the spatial scale parameter of the half-normal detection function. This is not just the tail probability of a normal deviate; think about how the probability of an individual being detected at least once changes with (i) the duration of sampling (ii) the density of detector array.
4c. Model fitting
Once you have defined a model, click the Fit model action button. With luck this will immediately fit the model and display the results.
The current version of secrapp will not attempt to fit a model if fitting is expected to take more than 10 minutes. Timing is predicted from the time for a single evaluation of the likelihood multiplied by the likely number of evaluations to maximize the likelihood (guessed from the number of coefficients to be estimated). Use secr and the R command line for larger models.
Step 5. Review and evaluate results
5a. Numerical results
When a model fits correctly a summary is posted in the scrollable Results panel. This includes the model coefficients or ‘beta’ parameters on the link scale (coef) and estimates of the ‘real’ parameters on the natural scale (predicted).
Density is expressed in animals per hectare so in this case the estimate is 1.47 / ha (95% CI 1.14–1.89/ha). Multiply by 100 for animals per square km.
The default summary may not be quite what you want. Two other canned options are provided via the radio buttons:
The ‘predict’ button reproduces just the table of the real parameter estimates, with one important difference: the ‘all.levels’ argument is set to TRUE so that estimates are shown for each level of any covariate input.
The ‘derived’ button computes Horvitz-Thompson estimates of density from the fitted detection model. This is useful when you have selected the conditional likelihood. The output table includes the relative standard error (RSE) of the estimate (labelled CVD for historical reasons) along with its components due to uncertainty in n and the effective sampling area (esa).
The ‘other’ button is explained below.
5b. Graphical output
The tabs below the Results panel expand to include several useful plots for a fitted model. Consider each of these in turn.
Detection function
The x-axis here is the distance between a detector and an animal activity centre. The probability of detection g(d) refers to a single detector and a single occasion, ignoring competing detectors or individuals. The alternate y-axis is the hazard of detection lambda(d) = -log(1-g(d)).
This plot is nice to look at, but particulars such as the intercept g0 should not be taken too literally (see later comparison of detection functions). The effective sampling area (esa) is another summary of the detection process (see Results - derived).
Buffer width
We used buffer = 250 to fit the snowshoe hare model, without explanation. Choosing a suitable buffer in advance can involve guesswork, so it’s good to verify it with the fitted model. The program may display a warning “predicted relative bias exceeds 0.01 with buffer = X” if the buffer appears to be inadequate, but this uses an approximate and unpublished algorithm bias.D.
We could rigorously check that the chosen buffer was adequate by re-fitting the model many times for different buffer widths. The Buffer plot uses a shortcut method based on a single fit (see ?esa.plot in secr). This suggests that the estimated density has easily reached a plateau at the chosen buffer width (dashed red line):
Pxy site-specific detection probability
The essence of SECR is that animals with activity centres away from the detectors are less likely to appear in the sample. The site-specific probability may be mapped for a given study design (detector layout and number of occasions) once we fit an observation model to estimate the parameters of the detection function. This is such a map. The code (not shown) uses the secr function pdot.contour.
Density surface
The default density model in secrapp is a flat surface (D~1), so the default map of expected density is a uniform colour. Here we depict a more interesting model for the hare data, a smooth surface with D ~ s(x,y, k = 6) (see ?Smooths and secr-densitysurfaces.pdf). As an exercise you should try fitting the two models (uniform and smooth) to see which is better supported (hint: check Summary).
The tabbed plot also invites you to overlay a random realization of the population from the fitted density model. The particular point pattern of one realization should not be interpreted as ‘real’. The number of points (here N = 94) is the realized number in the masked area - it depends on the buffer size. N is constant across realizations when the distribution of n is Binomial, but varies when n is Poisson.
Power
The power plot is there to remind you that small samples give very little power to measure change in density between two surveys. The plot opens with the relative standard error (RSE) of density from the fitted model; the slider allows you to assess the effect of varying RSE(D-hat). The changes to the study design (e.g. duration) needed to achieve a certain improvement in RSE(D-hat) can be assessed in the sister application secrdesignapp. See Efford and Boulanger (2019) for more.
5c. Summary screen
The Summary screen compiles a comparative table of the models you have fitted in the current session. The fields mostly correspond in an obvious way to inputs or parameter estimates. The more obscure fields are described below. The single estimate of each parameter cannot be relied on for non-constant models (see ‘predicted’ on Main screen for the model fitted most recently). For models that maximize the conditional likelihood, the reported density (D) is the derived (Horvitz-Thompson) estimate. Use the ‘Select’ button under ‘Analyses’ to restrict comparisons to a subset of fitted models.
Table 3. Obscure field names on Summary screen
| Field | Description |
|---|---|
| note | user-provided description from Options screen |
| usagepct | percent of detectors x occasions with non-zero detector usage |
| dAIC | difference in AIC between current model and the model with lowest AIC |
| RSE.D | relative standard error (CV) of density estimate D-hat |
| k | overlap index sigma-hat * sqrt(D-hat) / 100 (Efford et al. 2016; halfnormal only) |
| proctime | execution time in seconds |
We later use the summary table to compare detection models by AIC. The Summary screen calculates dAIC across all selected models without checking that they are compatible.* Compatible analyses use exactly the same data and the same likelihood (Full/Conditional), hcov, fastproximity etc. Be careful!
* The secr function AICcompatible cannot be applied because it compares the full datasets and models (only the summary is retained by secrapp).
Advanced
Filtering captures
A filter may be applied to captures loaded from text files or spreadsheets. Clicking on the ‘filter’ link in the Captures panel opens an additional text input ‘Filter’. Text entered in this box should be one or more valid argument(s) for the secr function subset.capthist. Filtering is switched off when ‘filter’ is clicked again, and the box for text input disappears. It is best to enter the filter criterion before browsing to the captures file or spreadsheet.
Table 4. Filtering criteria (main arguments of subset.capthist)
| Argument | Selects | Example | Note |
|---|---|---|---|
| subset | individuals | covariates(ch) == "M" |
assuming one individual covariate with values “F”,“M”; == not =. |
-c(15,16) |
drop the 15th and 16th individuals | ||
| occasions | sampling occasions | occasions = 1:3 |
limit to first 3 occasions |
| traps | detectors and associated detections | traps = traps(ch)$x < 500 |
only western part of array |
| sessions | sessions | sessions = 1 |
may select one or more sessions |
Each argument is a vector of subscripts that may be logical- (length equal to the relevant dimension of ch), character- or integer-valued, except that occasions should always be specified by their number.
For filtering individuals, the argument name ‘subset’ may be omitted as in the example. Negative integer values are interpreted to mean the corresponding rows (animals) should be dropped.
Arguments occasions, traps and sessions should be named, but the name may be shortened (e.g. occ = 1:3). Criteria may be combined (separated by commas).
If covariates(ch) has more than one column then name the covariate, e.g., covariates(ch)$sex == "M".
To select individuals or traps from multi-session data on the basis of a covariate it is best to specify the subset as a function. This is illustrated in the Examples for subset.capthist. Given a dataset like ovenCHp with individual covariate ‘sex’ (named in the ‘Covariate names’ input) we might select males with
subset = function(x) covariates(x)$sex == "M".
Or for part of the skink trapping grid used in infraCH,
traps = function(x) x$x > 2487460.
The function argument x here refers to a single-session capthist object (individuals) or a single-session traps object (traps); either may have covariates. If filtering fails then check the covariate names, including capitalisation.
The Summary table includes the filter text unless that summary field is deselected.
Input from Excel spreadsheets
The detector layout and captures may be read from separate .xls or .xlsx files, or from a single file in which they appear on separate sheets. By default, values in the first row are treated as column names, and if there are no column names then the first row is effectively discarded. This may be circumvented by including col_names = FALSE in ‘Other arguments’. Supplementary columns (beyond the 4 or 5 required by the trapID and XY formats) should be used only to specify detector usage or detector covariates.
Model – choosing a detection function
The detection function describes the change in probability of detection at a particular detector at increasing distances from the activity centre of an animal. Different functions represent subtley different observation models, and it sometimes matters to select the right one, so we start with some background.
secr offers several different shapes of detection function (see the list at ?detectfn). All except ANN and HAN decline monotonically with distance. Three are only used for acoustic data (BSS, SS, SSS). The simplest UN is not available for maximum likelihood model fitting, and several are frankly exotic and almost never used (CHN, WEX, CLN, CG), as are ANN and HAN.
That leaves the half-normal, negative exponential, and hazard rate functions (HN, EX, HR) These differ primarily in the length of their tails i.e. the probability they assign to very distant detections. The half-normal makes distant detections very improbable, the negative exponential less so; The ‘hazard-rate’ function requires a third parameter and potentially has a very long tail indeed.
For some of the detection functions there is a further option, to model not the probability of detection g(d) but the hazard of detection lambda(d). The hazard functions are parameterized with lambda0 instead of g0. Specifying the detection probability at a particular distance also specifies the hazard (there is a hard-wired relationship), but the overall shape of a half-normal hazard function implies a curve of detection probability vs distance that is different to a half-normal probability function.
Background out of the way, we take a look at the effect of selecting different functions and how to evaluate them.
Start by fitting each of these functions to the snowshoe hare data (use a fairly wider buffer = 400 m to allow for longer tails; we also decrease the spacing of mask cells by changing nx from 32 to 64):
- detectfn HN
- detectfn EX
- detectfn HR
How do the models compare? Refer to the Summary screen for a side-by-side comparison of the models (here we show only relevant rows of the table).
The last fit (detectfn = ‘HR’) raised a warning from the post-fitting bias check that we discuss more below.
Note how similar the density estimates are from HN and EX; HR not so much. The parameter named ‘sigma’ means a different thing for each function, so do not compare. To my mind this also applies to the function-specific ‘g0’.
Formal model comparison by AIC places the longer-tailed functions EX and HR ahead of HN (better models have smaller AIC).
The selection of HR is a worry because it has some annoying properties as we can see from the Buffer plot on the main screen.
Although the density estimates from HN and EX reach a plateau fairly promptly with increasing buffer width, the estimates from HR do not. That means that estimates of density remain sensitive to buffer width out to quite large distances. The sensitivity explains why the bias check raised a warning. It is an argument for not using HR except where there is a natural boundary (check out habitat islands in secr-habitatmasks.pdf). There is an unresolved research question here: Do real animals have such long tails?
Provisionally rejecting HR, we are left with EX as the preferred model for these data. HN delivers essentially the same estimate of density.
Model – ‘Other arguments’
The ‘Other arguments’ box allows you to customize the call to secr.fit. Here are some suggestions
verify = FALSE
Suppresses automatic checking of input data (useful if there is a known glitch that can be ignored)
details = list(fastproximity = FALSE)
Suppresses automatic collapsing of data from proximity detectors to a single-occasion count
sessioncov = data.frame(early = c(T,T,F,F,F))
The session covariate early may then be used in a model for multi-session data (e.g., ovenCHp) to distinguish first two sessions from later sessions. Session covariates in the sessioncov argument may be used to group sessions in other ways, or as session-specific continuous covariates.
Model – modelling detection parameters
Our initial model assumed that the detection of all individuals is governed by the same detection vs distance curve at all detectors on all occasions. The ‘model’ argument allows this assumption to be relaxed in particular ways.
Note: Although this is a longish section, and one that can occupy a lot of time, be warned: only trivial improvements in the estimates may result from exhaustively pursuing the last sliver of improvement in fit of the detection model. We rely on the robustness of SECR models. The potential effects of most importance are learned responses and individual heterogeneity.
The ‘model’ argument allows us to specify variation in each of the ‘real’ detection parameters (i.e. g0, lambda0 for hazard models, sigma). In the default model each real parameter is constant (g0 ~ 1, sigma ~ 1), but the constant indicator ‘1’ in each formula may be replaced by a predictor, or perhaps a combination of predictors.
For detection parameters (g0, lambda0, sigma) each predictor may be
- a code for an automatically generated predictor, or
- the name of an individual, trap or session covariate.
Codes for automatically generated predictors are listed in secr-models.pdf, and we show a subset in Table 3. The most important in terms of an effect on estimates of density are those for learned responses and unmodelled individual heterogeneity. Heterogeneity raises multiple issues that we do not have space for here, but see secr-finitemixtures.pdf.
Table 5. Automatic predictors commonly used to model detection parameters.
| Code | Description |
|---|---|
| b | permanent global learned response |
| bk | permanent detector-specific learned response |
| t | time factor (one level for each occasion) |
| T | time trend (integer covariate 0:(S-1)) |
| h2 | 2-class finite mixture model for individual heterogeneity |
| session | session factor (one level for each session) |
Model – modelling density
The default density surface is flat (D~1), but models may include variation across sessions or across space (see secr-densitysurfaces.pdf). Trends may be fitted with regression spline smooths s(x, y, ...) or polynomial functions of the coordinates. Alternatively, the model may relate density to habitat covariates that vary among pixels in the mask. Spatial covariates for density should be defined on the Habitat mask screen.
Table 6. Predictors used to model density.
| Code | Description |
|---|---|
| session | session factor (one level for each session) |
| [covariatename] | mask covariate or session covariate |
| s(x,y, k = 5) | smooth term with up to 4 degrees of freedom |
| x | x-coordinate |
| y | y-coordinate |
| x2 | x-coordinate^2 |
| y2 | y-coordinate^2 |
| xy | x-coordinate x y-coordinate |
More on Results
The Results radiobutton ‘Other’ lets you enter your own R code to extract information from objects available in the current session, particularly ch and fitted.
| Object | Class | Description | Examples | Notes |
|---|---|---|---|---|
ch |
capthist | spatial capture histories | table(ch) |
distribution of detections per detector & occasion |
RPSV(ch, CC = TRUE) |
biased approximate \(\sigma\) | |||
fitted |
secr | fitted model | vcov(fitted) |
variance-covariance matrix of coefficients |
names(fitted) |
components of fitted model | |||
fitted$fit |
details of maximization | |||
sapply(derived(fitted), '[[', 2,1) |
derived density by session | |||
secr.fit(ch, mask = mask(), model = fitted$model, start = fitted, method = 'none') |
check SE (nlm code 3) |
fit is the component of a fitted secr model that holds output from the likelihood maximization function (nlm for Newton-Raphson method, optim for other methods). Use names(fitted) to find other components.
RPSV(ch, CC = TRUE) provides a biased estimate of the spatial scale \(\sigma\), ignoring the problem that movements are truncated by the edge of the grid. This number is reported as ‘Approx HN sigma’ alongside the Moves plot.
Undocumented reactive values from the Shiny app are also available. Some that may be useful are mask, density, n, r, References to these values should include “()” (e.g, nrow(mask())).
Troubleshooting
The Results window may be slow to refresh when secrapp is used on the Otago University server. Try clicking on different options (e.g., hide then summary).
Close your browser window to cancel a runaway operation, or if the screen locks up. There is no other way to interrupt the Shiny app. It is better to start again than to use the Reload option of your browser if the session disconnects from the server.
Errors can sometimes be diagnosed from the message in the notification window (bottom right of screen).
If data fail to load there may be a formatting error (view each text file with the ‘show file’ link) or you may have selected an inappropriate detector type (e.g., ‘multi’ for ‘polygon’ data, or vice versa).
The notification “failed to compute expected time” may be due to an error or inconsistency in the capthist object as loaded. Check this by typing ‘verify(ch)’ to the right of the Results buttons and clicking ‘other’:
A report appears in the Results window. If the errors are innocent (e.g., occasional extra detections at nominally binary detectors) then suppress the verification that usually precedes model fitting by typing ‘verify = FALSE’ in the Model Other arguments input.
If a model fails to fit (e.g., all estimates NA) then
- The default buffer width may be grossly inadequate. Set the buffer width manually on the Habitat mask screen, or with the ‘suggest buffer’ link (not for polygon detectors).
- The automatic starting values for likelihood maximization may be inadequate. You can set these manually by specifying, e.g.,
start = list(D = 0.1, g0 = 0.1, sigma = 500)in ‘Other arguments’ under Model. For multisession data the default is to compute starting values automatically from the first session, which may be inadequate. Use e.g.,details = list(autoini = 2)to choose a new session (in this case session 2).
Other pitfalls
- Components of an ESRI shapefile must be selected and uploaded together (at least .shp, .dbf and .shx).
Limitations
SECR methods are like other capture–recapture methods: they require substantial datasets and rigorous data collection. Spatial sampling should be representative of the region of interest, and at the very least you must know where sampling was conducted. There should be plenty of recaptures - at least 20 is a good rule-of-thumb. More pointers are given at the end of the Appendix.
Many features of secr are not implemented in secrapp 1.3. These include
- Varying detector layout by session
- Model averaging
- Non-euclidean distances (userdist function)
- Mark-resight
- File input of session-specific habitat masks
If you need one of these, take the plunge and run your analyses directly on the R command line! See the commandline tutorial secr-tutorial.pdf for help, and build on the code displayed by secrapp.
The Summary screen does not cope well with multi-session analyses: parameter estimates are shown only for the first session. Use the Results options on the main screen for more detail, especially Predict, Derived and Other,
References
Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximum likelihood methods for capture–recapture studies. Biometrics 64, 377–385.
Efford, M. G. (2012) DENSITY 5.0: software for spatially explicit capture-recapture. Department of Mathematics and Statistics, University of Otago, Dunedin, New Zealand. https://www.otago.ac.nz/density.
Efford, M. G., Borchers D. L. and Byrom, A. E. (2009) Density estimation by spatially explicit capture–recapture: likelihood-based methods. In: D. L. Thomson, E. G. Cooch and M. J. Conroy (eds) Modeling Demographic Processes in Marked Populations. Springer. Pp. 255–269.
Efford, M. G. and Boulanger, J. (2019) Fast evaluation of study designs for spatially explicit capture–recapture. Methods in Ecology and Evolution 10, 1529–1535.
Efford, M. G., Dawson, D. K., Jhala, Y. V. and Qureshi, Q. (2016) Density-dependent home-range size revealed by spatially explicit capture-recapture. Ecography 39, 676–688.
Lebreton, J.-D., Burnham, K. P., Clobert, J. and Anderson, D. R. (1992) Modeling survival and testing biological hypotheses using marked animals: a unified approach with case studies. Ecological Monographs 62, 67–118.
Otis, D. L., Burnham, K. P., White, G. C. and Anderson, D. R. (1978) Statistical inference from capture data on closed animal populations. Wildlife Monographs No. 62.
Appendix 1. A general description of SECR data and models
SECR data are observations of marked animals at known locations. Observations result from a well-defined regime of spatial sampling. Sampling is most commonly done with traps, cameras, or some other type of passive detector.
The purpose of the analysis is to estimate parameters of the animal population, particularly the population density. Density is defined as the intensity of a spatial point pattern, where each point stands for the ‘average’ location of an animal: its activity center, roughly speaking. In order to estimate density from a sample of captures we must account for the sampling process.
Key assumptions and data requirements are listed below.
Model
A SECR model combines a model for the point process (the state model) and a model for distance-dependent detection (the observation model). We obtain an unbiased estimate of population density (D) and the parameters of the detection process by jointly fitting the state and observation models.
In SECR the detection process is spatial: each animal is more likely to be detected near its activity centre and less likely to be detected further away. We typically use two parameters to describe that relationship - here g0 for the intercept and sigma for the spatial scale.
These ideas extend to sampling of open populations, but in this document (and throughout the secr package) we are concerned only with closed populations. A closed population is one in which the composition of the population and the activity distributions of individuals can be assumed fixed for the duration of sampling.
Data
Spatial capture–recapture data are usually collected by sampling at known points in space (the detector locations). The relative locations of detectors must be known. The analysis does not assume a particular configuration of detectors (a regular grid layout is optional), but there are constraints on the spacing and extent of the detector array (e.g., Efford and Boulanger 2019). Each animal receives an individual mark* when it is first detected, and this is recorded whenever the animal is detected. Sampling may be repeated on multiple occasions (although multiple occasions are not always needed). The data comprise a set of spatial detection patterns, one for each known individual. With temporal replication the result is a set of individual spatial detection histories.
* some sampling methods use pre-existing natural marks, or the individual’s unique DNA
Figure 1. Layout of a hypothetical trap array and spatial detection histories for notional animals with ID 1–5 when the array was operated for 4 occasions. The histories are shown on the right in the column format used by secr. Detector types that allow multiple detections per occasion result in histories with multiple observations per cell in the central panel, and multiple rows per ID and occasion on the right.
Habitat mask
The activity centre of each animal that is recorded at a detector may lie either within the perimeter of the detector array or somewhere else, outside the array. Except in the case of a habitat island there is no definite limit to ‘somewhere else’. However, the probability of inclusion in our sample declines with distance, and beyond some distance the probability of inclusion is so small that the effect on density estimates is negligible. Calculations for SECR are therefore routinely restricted to a buffered area around the detector array that is often represented by a set of small pixels. In the secr package this is referred to as the habitat mask, but you may also see it described as the ‘region of integration’ or (in Bayesian implementations) the ‘state space’. It is natural to exclude from the mask any known non-habitat - estimated density then relates to the habitat fraction of the landscape.
Figure. 2. Habitat mask (grey dots) delimited by a buffer of width w around a detector array (red squares). Activity centres (circles) are distributed uniformly across the wider area, but the activity centres of all detected animals are assumed to lie inside the habitat mask (filled circles).
See secr-habitatmasks.pdf for more.
Link functions, beta parameters and real parameters
SECR models tend to have a nested structure. Variation in each of the ‘real’ parameters (typically D, g0 and sigma) may be captured by a linear model, potentially involving covariates or other predictors, that is parameterized by its coefficients or ‘beta’ parameters. In the simplest case D~1, g0~1, sigma~1 there is one beta parameter for each real parameter, and no covariates or other factors intervene. More generally, there may be several beta parameters for each real parameter.
The relationship between the predictors and each real parameter is modelled as linear only on a transformed (link) scale - the idea should be familiar from logistic regression and generalised linear models. Estimates of real parameters and their confidence limits are back-transformed from the linear predictor (sum of beta terms) on the link scale. For constant models (~1) the linear predictor is simply the unique beta parameter. Transformation has various benefits (restricting the parameter space to feasible values, better asymmetric confidence intervals). Standard errors generally require a delta-method approximation (Lebreton et al. 1992).
This explains the two summary tables that appear in Results:
$coefshows the fitted beta parameters$predictedshows the real parameter estimates evaluated for specific levels of the predictors where the model is not a constant.
The machinery of link functions in secr has a lot in common with the MARK software for which there is excellent documentation online (Cooch and White 2019). The terminology of ‘beta’ and ‘real’ parameters comes from MARK.
Covariates
A covariate is a measured variable that can inform the models for density or detection. Covariates are of several types (table). Detector or individual covariates may be provided as additional columns in the usual input files (secr-datainput.pdf).
Table. Types of covariate available to model a notional capthist object ‘ch’ with habitat mask ‘mask’.
| Level | Typically entered via | Stored as | Parameters | Examples |
|---|---|---|---|---|
| Density | addCovariates(mask, source) | covariates(mask) | D | vegetation cover |
| Session | secr.fit(ch, …, sessioncov = ) | [any] | ||
| Occasion | secr.fit(ch, …, timecov = ) | g0, lambda0, sigma | daily max. temperature | |
| Detector | detector file | covariates(traps(ch)) | g0, lambda0, sigma | trap type |
| Individual | captures file | covariates(ch) | g0, lambda0, sigma | sex |
Covariates may be used in a linear model on the link scale for one or more of the real parameters.
Individual covariates in secr require the ‘conditional’ likelihood. A partial exception is the hybrid mixture approach in which a binary individual covariate such as sex is used in the ‘hcov’ argument to define mixture classes - see secr-finitemixtures.pdf.
Density covariates require the ‘full’ likelihood, as otherwise density D does not appear in the model. The density covariate must exist for every point on the habitat mask.
Varying detection effort over time or space can often be accommodated without a covariate model, via detector ‘usage’ (Efford, Borchers and Mowat 2013).
Assumptions and data requirements
We informally note some key assumptions and data requirements for spatially explicit capture–recapture.
Spatially representative sampling
The (vicinity of) detector array(s) should be spatially representative of the region of interest. A serious study should therefore consider systematic or other spatially balanced sampling designs.
Marks are recorded correctly and not lost
secr does not include models for uncertain identity e.g., Augustine et al. (2018).
Population closed during sampling
Each animal in the population is assumed to have a stable home range, but density estimates may be quite robust to movement (Royle et al. 2015). If sampling is protracted there is a risk of violating the closed-population assumption of no births or deaths during sampling. This may not be critical.
Detection parameters do not vary
Capture–recapture formally assumes that all animals at all times share the same probability of detection, except for variation specifically included in the model. In practice we rely on a certain degree of robustness to variation (e.g., bias due to unmodelled individual heterogeneity at first increases only gradually as heterogeneity increases; Efford and Mowat 2014).
Detections independent
The probability model in SECR requires that observations are statistically independent. This assumption is violated if animals travel in groups. It is also probably violated when an animal is detected multiple times in quick succession: the short elapsed time then ensures serial correlation of locations. The effect is reduced by treating field counts as binary data.
Mild non-independence (overdispersion) has the effect of underestimating sampling variance (SE of estimates). It may help to apply a correction for overdispersion (Bischof et al. 2020).
Shape of home ranges
Although the SECR model formally assumes circularity of home ranges, this assumption is critical only if ranges are both elongated and aligned with the detector array (Efford 2019).
Sufficient extent of detector array
The spatial parameter of the detection function may be underestimated, and density overestimated, if the array is too small in total extent: it should span at least one home range.
Home ranges span more than one detector
The extreme case that re-detections occur only at the original detector does not allow the spatial parameter to be estimated.
Sufficient data
The precision of density estimates is mostly controlled by the number of re-detections. Typically, more than 20 re-detections are needed to achieve RSE(D-hat) < 20% (i.e. CV(D-hat) < 20%). Other aspects of an analysis (model selection and variance estimation) are also less reliable with small samples.
References
Augustine, B. C., Royle, J. A., Kelly, M. J., Satter, C. B., Alonso, R. S., Boydston, E. E. and Crooks, K. R. (2018) Spatial capture–recapture with partial identity: an application to camera traps. Annals of Applied Statistics 12, 67–95.
Bischof, R., Dupont, P., Milleret, C., Chipperfield, J. and Royle, J. A. (2020) Consequences of ignoring group association in spatial capture–recapture analysis. Wildlife Biology wlb.00649, 1–10. https://doi.org/10.2981/wlb.00649.
Cooch, E. and White, G. (eds) (2019) Program MARK: A Gentle Introduction 19th edition. Available online at http://www.phidot.org/software/mark/docs/book/.
Efford, M. G. (2019) Non-circular home ranges and the estimation of population density. Ecology 100(2) e02580. https://esajournals.onlinelibrary.wiley.com/doi/10.1002/ecy.2580
Efford, M. G., Borchers D. L. and Mowat, G. (2013) Varying effort in capture–recapture studies. Methods in Ecology and Evolution 4, 629–636.
Efford, M. G. and Boulanger, J. (2019) Fast evaluation of study designs for spatially explicit capture–recapture. Methods in Ecology and Evolution 10, 1529–1535.
Efford, M. G. and Mowat, G. (2014) Compensatory heterogeneity in spatially explicit capture–recapture data. Ecology 95, 1341–1348.
Royle, J. A., Fuller, A. K. and Sutherland, C. (2015) Spatial capture–recapture models allowing Markovian transience or dispersal. Population Ecology DOI 10.1007/s10144-015-0524-z.