Introduction
Main screen
Habitat mask
Summary
Options
References
This Shiny application is an interactive interface to parts of the R package secr (Efford 2024a). The current source code is available from https://GitHub.com/MurrayEfford/secrapp. The step-by-step guide overlaps in scope with this document and may ultimately replace it.
Documentation of secr is available at www.otago.ac.nz/density. For example:
secr-manual.pdf (details of each function)
secr-datainput.pdf
secr-overview.pdf
The analyses available through the Shiny app are a subset of those in secr. Support for multi-session analyses is limited.
TIP: on small displays, running your browser in full-screen mode will avoid the need to scroll down (often F11 will get you there; otherwise try the options menu of the browser).
Version 2.0 (November 2024) has these user-visible changes:
Use settings on this page to input data and fit simple models.
By default, input is from two text files, one for the detector layout and one for detections (‘captures’) of known individuals. Excel files may also be used. Alternatively, secrapp may read the complete secr capthist object from a .rds file, or use one of the builtin datasets.
The detector layout file typically should have three columns (trapID, x, y) with no headers. These may optionally be followed by binary usage codes (0/1), one per occasion. Columns after a ‘/’ are interpreted as detector covariates. Headers are required for input from Excel files.
Options for detector type follow secr (Efford 2024a): “multi” refers to a multi-catch trap; “proximity” to binary proximity detectors, and “count” to detectors that yield integer counts. Counts are assumed to be Poisson-distributed. Data from searches of areas or transects use the types “polygon”, “polygonX”, “transect” or “transectX” (Efford 2011; see also secr-polygondetectors.pdf).
If detector covariates are included then one or more covariate names should be provided (without quotes, separated by commas).
Optional arguments separated by commas may be used to customise input (e.g., skip
, which is passed through read.traps
to read.table
).
Two formats are allowed, as in DENSITY or secr; ‘trapID’ uses four columns (Session, AnimalID, Occasion, TrapID) and ‘XY’ uses five (Session, AnimalID, Occasion, X, Y). Supplementary columns are interpreted as individual covariates.
If individual covariates are included then the correct number of covariate names should be provided (without quotes, separated by commas).
Optional arguments separated by commas may be used to customise input (e.g., skip
, which is passed to read.table
).
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. 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 text input disappears. It is best to enter the filter criterion before browsing to the captures file or spreadsheet.
Table. 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 =. |
occasions | sampling occasions | occasions = 1:3 |
limit to first 3 occasions |
traps | detectors | 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 be specified by their number. Arguments occasions
, traps
and sessions
should be named, but may be shortened (e.g. occ = 1:3
). Criteria may be combined (separated by commas).
Selecting individuals (argument subset) can be problematic, especially from multi-session data. If covariates(ch)
has more than one column then specify with, e.g., covariates(ch)$sex == "M"
.
To select individuals 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 with individual covariate ‘Sex’ (named in the ‘Covariate names’ input) we might select males with function(x,sex) covariates(x)$Sex==sex, sex = "M"
. If filtering fails then check the covariate names, including capitalisation.
The Summary table includes the filter text unless that summary field is deselected.
Detection function | HN | halfnormal | \( \small g(d) = -g_0 \exp\{-d^2/(2\sigma^2)\} \) |
HR | hazard rate | \( \small g(d) = -g_0 (1 - \exp(-(d/\sigma)^{-z})) \) | |
EX | negative exponential | \( \small g(d) = -g_0 \exp(-d/\sigma) \) | |
HHN | hazard halfnormal | \( \small \lambda(d) = -\lambda_0 \exp(-d^2/(2\sigma^2)) \) | |
HHR | hazard hazard rate | \( \small \lambda(d) = -\lambda_0 (1 - \exp(-(d/\sigma)^{-z})) \) | |
HEX | hazard negative exponential | \( \small \lambda(d) = -\lambda_0 \exp(-d/\sigma) \) |
Likelihood | maximize full likelihood or likelihood conditional on \( \small n\) |
Distribution | distribution of number detected \( \small n\) |
Mixture hcov | name of individual covariate |
The supported detection functions are a subset of those allowed in secr (currently ‘HN’, ‘HR’, ‘EX’, ‘HHN’, ‘HHR’, ‘HEX’). These relate either the probability (g(d)) or hazard (( \small \lambda)) of detection at a particular detector on a particular sampling occasion to the distance ( \small d) of the detector from its home-range centre. The probability of detection is ( \small g(d) = 1 - \exp { - \lambda(d)}).
The Distribution radio button toggles between two models for the number of detected individuals \(n\). The “Binomial” option corresponds to fixed number \(N\) in the masked area and a binomial point process for the distribution of activity centres. The “Poisson” option corresponds to Poisson \(N\) and a Poisson point process for activity centres.
The Mixture hcov select input allows the user to choose a variable defining a 2-level mixture class from among the individual covariates. This is passed to secr.fit
as the argument ‘hcov’. The covariate should take two non-missing values (e.g., ‘F’,‘M’); missing values are allowed. The mixing proportion ‘pmix’ is included in the model automatically when hcov is specified. To estimate mixture-specific values of a parameter include \(\sim\)h2 in its formula (e.g., lambda0$\sim$h2). See secr-finitemixtures.pdf for more.
Other arguments separated by commas may be used to customise the call to secr.fit
. Attempts here to change ‘capthist’, ‘mask’, ‘model’ or ‘detectfn’ are ignored, and ‘trace’ is always FALSE.
Model formulae may be edited using pre-defined predictors or covariate names as described in secr-overview.pdf. Time covariates (‘timecov’) and session covariates (‘sessioncov’) may be specified in Other arguments. There is no provision for time-varying detector covariates.
The Habitat mask box reports attributes of the mask currently defined on the Habitat mask screen; use the edit link to vary these.
The application is designed for small- to medium-sized models. An internal algorithm predicts the execution time by evaluating the likelihood once and making a simple extrapolation. The prediction is quite rough. When the predicted time exceeds a lower threshold (‘timewarning’, default 0.5 minutes) a dialog box asks the user for confirmation before proceeding. If the predicted time exceeds an upper threshold (‘timelimit’, default 10 minutes) then execution aborts, with a notification at the lower right of the screen. The thresholds may be changed in the R code of the app.R file (near the top).
Fit model | Fit closed-population SECR model |
Reset all | Reset all input options to defaults |
Bookmark | (see Bookmarking) |
‘Reset all’ does not delete Summary results from the current session. Use the ‘Clear’ link on the Summary page to remove summaries. Summary results will be lost if you close the application without downloading to a local file.
The option ‘Switch to secrdesign’ appears once a model has been fitted if the detection function is HHN or HEX and the detector type is multi, proximity or count. This opens ‘secrdesignapp’ on the Otago University server in a new browser window. Settings and parameter estimates are transferred automatically. Detector locations are not transferred; they should be provided either by selecting the file in secrdesignapp, or by the usual options (Grid, Line, Region).
Values in the Results window are updated automatically when the inputs change.
The default ‘results’ vary depending on the inputs
ch
) or fitted model (fitted
), or displaying a help topic from ‘secr’ (e.g., ?detectfn).Once a model has been fitted it is possible to select
predict
derived
(Horvitz-Thompson) estimatesThe ‘hide’ button temporarily suppresses the summary output.
Plots update automatically. Any plot may be saved by right-clicking on the image.
R statements for the main operations. These expand once you browse to specific detector and capture files.
The statements may be copied and pasted into an R session. It is assumed that input files are in the current folder; you may need to change this with setwd()
.
A plot of the current detector layout. Detections are overplotted if they have been uploaded.
By default, the locations of one animal are highlighted and its ID, number of detections and observed range length (ORL) appear in a box. Suppress this by selecting animal ‘0’. Click on the plot to select an individual.
A session selector is shown for multi-session data. Changing the session changes the plot displayed on this tab, and on some others (Buffer, Pxy, Dxy); it does not affect model fitting.
Once a model has been fitted, ticking ‘fxi contour’ displays a contour plot of probability density contours for the activity centre of the current animal. This may fail if the mask spacing is too small.
Histogram of distances between the successive detections of each animal. The bar width is determined internally from an integer value provided to the ‘breaks’ argument of hist
. You can vary the ‘Nominal breaks’ setting (small changes have no effect because of the algorithm used by hist
).
Summary statistics appear in a box to the right. “Approx HN sigma” is computed with the secr function RPSV(capthist, CC = TRUE)
; the approximation is an underestimate, especially when the detector array is small.
Non-exclusive detector types (proximity, count etc.) allow multiple detections on a single occasion, and the order of these detections is unknown. The distances then depend on the arbitrary within-occasion ordering of detections.
For multi-session data the displayed histogram is for the current session (see Array tab), unless ‘Combine sessions’ has been selected on the Options screen. When sessions are combined, the default is to include session-session movements. This may be changed on the Options screen.
Fitted detection function on the hazard and probability scales.
Predicted effect of buffer width on density estimates. The plot is generated with esa.plot(fit)
. A red vertical line indicates the buffer that was used (there is no line when the mask has been read from a file).
Contours of the overall detection probability ( \small p_\cdot(\mathbf x)) under the fitted model (‘Pxy’ is the label that has been used for this quantity in the Windows application Density). Settings in Options toggle the display between filled and unfilled contour plots, and determine whether contours are labelled. The requested contour levels are 0.1, 0.2, …, 0.9, but higher contours may be missing. Click on the plot to find the value at a point.
A plot of the fitted density model with various optional overlays:
Two styles of plot are offered (see Options | Power plot)
Probability of detecting a change in density in a 2-survey comparison as a function of effect size for a given expected ( \small \mbox{RSE}(\hat D)). See Efford and Boulanger (2019) for the computation method.
Effect size is the ratio of final density ( \small D_2) to initial density ( \small D_1) expressed as a percentage. The alpha level is specified in Options (default ( \small \alpha = 0.05)).
The curve is initially computed for the rule-of-thumb RSE from the current design. Use the slider to vary this. Especially, consider adding a safety margin for underestimation of RSE.
The default method assumes that ( \small \mbox{RSE}(\hat D)) is the same in the initial and final surveys. It is more likely that ( \small \mbox{RSE}(\hat D)) will increase as density declines. An adjustment is applied to the final RSE when the ‘Adjust RSE’ box is ticked: ( \small \mbox{RSE}(\hat D_2) = \sqrt {D_1/D_2} \mbox{RSE}(\hat D_1) ).
As an alternative to conventional power analysis we can construct intervals for the estimated ratio of densities, given the true ratio and the sampling errors. The interval is the region between the upper and lower curves for a given true population change on the x axis.
Either construct a habitat mask from scratch (‘Build’) or read mask coordinates from a text file (‘File’).
The ‘Suggest width’ button runs the secr function suggest.buffer
which is currently available only for point detectors (not polygon types). The algorithm requires that captures have been loaded.
A mask built by buffering around a detector array may include known non-habitat. Polygon data from an ESRI shapefile may be used to include or exclude sites from the mask.
Mask covariates are used to build spatial models of density (D). Covariate data may be added from a spatial data source - either a polygon shapefile, a spatial data source (sf or SpatialPolygonsDataFrame) stored in an .rds file, or a text file in the format used for habitat masks (below). Covariate values at each mask point are inferred from spatial overlap (shapefile, sf or SpatialPolygonsDataFrame) or the nearest source point (mask file).
A mask text file should have a header line. The first two columns (‘x’, ‘y’) are read as the x- and y-coordinates. Further columns are assumed to represent covariates and their names may be used in formulae for density.
The table on this page has one column for each model fit or other summary; summaries are added automatically when models are fitted.
The displayed table includes only selected analyses. Users should ensure AIC comparisons are valid across the selected analyses (use same data and compatible model structure).
The table may be downloaded as a comma-separated text file or in the RDS format (use readRDS
to restore in R). The table is transposed on download so that scenarios become rows.
These should be self-explanatory. Experiment if in doubt.
The default (Newton-Raphson in function nlm
) is generally OK. Nelder-Mead in function optim
is slower and somewhat more robust with difficult likelihood surfaces.
Multithreading allows some operations to be performed in parallel for faster model fitting. The number of cores (ncores argument of secr::secr.fit
) may be set manually. The maximum allowed by secrapp is the smaller of 24 and the number of cores available (including virtual cores)[1]. The default number of cores is half the maximum.
[1] The limit of 24 is arbitrary. It stops a user from hogging a vast number of cores in some environments.
A model will not be fitted if the predicted time exceeds a limit, currently 10 minutes. The prediction is quite rough as there is no obvious way to anticipate the number of likelihood evaluations that will be required.
NOTE: Bookmarking is disabled in secrapp 2.0 owing to a problem in Shiny.
Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximum likelihood methods for capture–recapture studies. Biometrics 64, 377–385.
Efford, M. G. (2011) Estimation of population density by spatially explicit capture–recapture analysis of data from area searches. Ecology 92, 2202–2207.
Efford, M. G. (2024a) secr: Spatially explicit capture–recapture models. R package version 5.0.0. https://CRAN.R-project.org/package=secr
Efford, M. G. (2024b) secrdesign: Sampling design for spatially explicit capture–recapture. R package version 2.9.2. https://CRAN.R-project.org/package=secrdesign
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.
Pebesma, E. (2018) Simple Features for R: Standardized Support for Spatial Vector Data. The R Journal 10, 439–446. https://doi.org/10.32614/RJ-2018-009