help.rmd

---
title: "secr app 2.1"
author: "Murray Efford"
date: '2024-11-26'
output:
  html_document:
    toc: yes
    toc_depth: 2
---

# An interactive app for spatially explicit capture--recapture

# Contents
  [Introduction](#introduction)  
  [Main screen](#main)  
  [Habitat mask](#habitatmask)  
  [Summary](#summary)  
  [Options](#optionspecs)  
  [References](#references)  
  
----------------------------------------------------

# Introduction  <a name="introduction"></a>

This Shiny application is an interactive interface to parts of the R package **secr** ([Efford 2024a](#references)). 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:

* requires **secr** >= 5.1.0
* new dataset blackbearCH
* habitat mask buffer width 'suggest' link on the Main screen
* 'Clear' link on the Summary screen
* spatial data processing uses package **sf** ([Pebesma 2018](*references)), replacing defunct rgdal

Version 2.1 (November 2024) has these user-visible changes:

* new Re-fit action
* re-styled <u>Habitat mask</u> box on main tab
* option to specify mask spacing instead of nx
* optional 'method' field in Summary
* user control of summary prefix (e.g. 'Analysis')
* improved notifications

# Main screen  <a name="main"></a>

*Use settings on this page to input data and fit simple models.*

## Data input

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.

### Detector layout

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 <u>detector type</u>  follow **secr** ([Efford 2024a](#references)): "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`). 

### Captures

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"; &nbsp; == 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.

## Model

<table style="width:800px">
    <colgroup>
       <col span="1" style="width: 20%;">
       <col span="1" style="width: 7%;">
       <col span="1" style="width: 25%;">
       <col span="1" style="width: 48%;">
    </colgroup>
  <tr>
    <td> Detection function </td>
    <td> HN </td> 
    <td> halfnormal </td>
    <td> \( \small g(d) = -g_0 \exp\{-d^2/(2\sigma^2)\} \) </td>
  </tr>
  <tr>
    <td> </td>
    <td> HR </td>
    <td> hazard rate</td>
    <td> \( \small  g(d) = -g_0 (1 - \exp(-(d/\sigma)^{-z})) \) </td>
  </tr>
  <tr>
    <td> </td>
    <td> EX </td> 
    <td> negative exponential</td>
    <td> \( \small  g(d) = -g_0 \exp(-d/\sigma) \) </td>
  </tr>
  <tr>
    <td> </td>
    <td> HHN </td> 
    <td> hazard halfnormal</td>
    <td> \( \small  \lambda(d) = -\lambda_0 \exp(-d^2/(2\sigma^2)) \) </td>
  </tr>
  <tr>
    <td> </td>
    <td> HHR </td>
    <td> hazard hazard rate </td>
    <td> \( \small  \lambda(d) = -\lambda_0 (1 - \exp(-(d/\sigma)^{-z})) \)  </td>
  </tr>
  <tr>
    <td> </td>
    <td> HEX </td>
    <td> hazard negative exponential</td>
    <td> \( \small  \lambda(d) = -\lambda_0 \exp(-d/\sigma) \) </td>
  </tr>
</table> 
  
<br>
<table style="width:600px">
    <colgroup>
       <col span="1" style="width: 27%;">
       <col span="1" style="width: 73%;">
    </colgroup>
  <tr>
    <td>Likelihood</td>
    <td>maximize full likelihood or likelihood conditional on \( \small n\)</td>
  </tr>
  <tr>
    <td>Distribution</td>
    <td>distribution of number detected \( \small n\)</td>
  </tr>
  <tr>
    <td>Mixture hcov</td>
    <td>name of individual covariate</td>
  </tr>
</table> 

<br>

The supported <u>detection functions</u> 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)\}\).

<a name="distribution"></a>

The <u>Distribution</u> 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. 

<a name="hcov"></a>

The <u>Mixture hcov</u> 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 <u>Other arguments</u>. There is no provision for time-varying detector covariates.

The <u>Habitat mask</u> box reports attributes of the mask currently defined on the Habitat mask screen; use the edit link to vary these. 

## Time limits

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).

## Actions

<table style="width:600px">
    <colgroup>
       <col span="1" style="width: 27%;">
       <col span="1" style="width: 73%;">
    </colgroup>
  <tr>
    <td>Fit model</td>
    <td>Fit closed-population SECR model</td>
  </tr>
  <tr>
    <td>Reset all</td>
    <td>Reset all input options to defaults</td>
  </tr>
  <tr>
    <td>Re-fit model</td>
    <td> Re-fit the model, possibly changing the 'method' argument.</td>
  </tr>
</table> 

<br>

'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.

'Re-fit model' repeats the call to secr.fit() with all current settings except that (i) existing parameter estimates are used as starting values, and (ii) the "method" argument is taken from the Options tab. Re-fitting a model with method "none" merely re-computes variance estimates, and may correct missing SE and confidence limits.

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).

## Results  <a name="results"></a>

*Values in the Results window are updated automatically when the inputs change.*

The default 'results' vary depending on the inputs

* summary of detector layout only
* summary of capthist object (detector layout + detections)
* summary of fitted model
* user-specified code, possibly referencing the capthist (`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 

* summary of fitted model
* table(s) of estimates from `predict`
* table of `derived` (Horvitz-Thompson) estimates

The 'hide' button temporarily suppresses the summary output.

## Tabbed code and plots

*Plots update automatically. Any plot may be saved by right-clicking on the image.*

### Code

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()`.

### Array

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.

### Moves

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. 

### Detectfn   <a name="detectfnplot"></a>

Fitted detection function on the hazard and probability scales.

### Buffer   <a name="esaplot"></a>

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).

### Pxy

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.

### Dxy

A plot of the fitted density model with various optional overlays:

* detector locations (red crosses)
* petal plot of detections
* one simulated population from the fitted model
* circles with 95% home range for each centre in the simulated population

### Power

Two styles of plot are offered (see Options | Power plot)

#### Power for test of null hypothesis 

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) \).

#### Confidence interval for population change

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. 

----------------------------------------------------

# Habitat mask  <a name="habitatmask"></a>

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.

----------------------------------------------------

# Summary  <a name="summary"></a>

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.

----------------------------------------------------

# Options  <a name="optionspecs"></a>

*These should be self-explanatory. Experiment if in doubt.*


## Model fitting

### Maximization method

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.

### Number of cores

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. 

### Time limit

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. 

----------------------------------------------------

<!-- # Bookmarking  <a name="bookmark"></a> -->

<!-- NOTE: Bookmarking is disabled in secrapp 2.0 owing to a problem in Shiny. -->

<!-- Bookmarking creates a URL that allows you to take up your session where you left off.  -->

<!-- Bookmarking can be tricky. When running from GitHub on a local machine your should specify the arguments `port` and `destdir` both in the initial session that you bookmark and later when you restore it, e.g., -->

<!-- ```{r, eval = FALSE} -->
<!-- library(shiny) -->
<!-- runGitHub("secrapp", "MurrayEfford", port = 8000, destdir = "d:/myworkingfolder") -->
<!-- ``` -->

<!-- The port number is arbitrary. Bookmarks are stored in a subdirectory of destdir. The URL generated by pressing the Bookmark button may be entered into your browser once you have started a new session with the same 'port' and 'destdir'. This restores all input settings and the Summary table. Also consider setting `options(shiny.port = xxxx)`. The port used by a local bookmark is saved in the values.rds file of the bookmark; if you forget it, try `readRDS("values.rds")$port`. -->

----------------------------------------------------

# References <a name="references"></a>

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

----------------------------------------------------

[secrdesign-Enrm.pdf]: http://www.otago.ac.nz/density/pdfs/secrdesign-tools.pdf
[secr-polygondetectors.pdf]: http://www.otago.ac.nz/density/pdfs/secr-polygondetectors.pdf
[secr-finitemixtures.pdf]: http://www.otago.ac.nz/density/pdfs/secr-finitemixtures.pdf
[secr-manual.pdf]: http://www.otago.ac.nz/density/pdfs/secr-manual.pdf
[secr-datainput.pdf]: http://www.otago.ac.nz/density/pdfs/secr-datainput.pdf
[secr-overview.pdf]: http://www.otago.ac.nz/density/pdfs/secr-overview.pdf

[bias.D]: https://www.otago.ac.nz/density/html/suggest.buffer.html
[detectfn]: https://www.otago.ac.nz/density/html/detectfn.html
[pdotContour]: https://www.otago.ac.nz/density/html/contour.html
[esa.plot]: https://www.otago.ac.nz/density/html/esaplot.html
[subset.capthist]: https://www.otago.ac.nz/density/html/subset.capthist.html

[step-by-step guide]: https://www.otago.ac.nz/density/pdfs/secrapp-tutorial.html