Warning: results with linear arrays may be highly biased if home ranges are elongated and aligned

F11 to toggle fullscreen

Spacing relative to sigma

Introduction

Design

Habitat mask

Costing

Simulation

Spacing

Summary

Options

Troubleshooting

References

Appendices

This Shiny application is an interactive interface to parts of the R package **secrdesign** (Efford 2019a). It focuses on the effect of detector layout and other design variables on the precision of density estimates, measured by the relative standard error (RSE, aka CV). Vary settings on the Design page to obtain an immediate “rule-of-thumb” approximation to RSE(\(\hat D\)), based on the expected numbers of recaptures and distinct individuals (Efford and Boulanger 2019). The current source code is available from https://GitHub.com/MurrayEfford/secrdesignapp.

The approximation is biased low for some layouts, especially when sample size is small. A correction factor may be applied to adjust the approximation. Refine the approximation by simulating data from the chosen design; this may take a long time. The correction factor is updated automatically from simulation results (see Options to suppress this). Use “Add to summary” to include the current scenario in a spreadsheet for export.

Documentation for **secrdesign** is available at www.otago.ac.nz/density. For example:

secrdesign-manual.pdf (details of each function)

secrdesign-tools.pdf (optimal spacing etc.)

secrdesign-Enrm.pdf (expected sample size)

Acknowledgement: Greg Trounson (Department of Mathematics and Statistics, University of Otago) has provided invaluable and continuing help by testing the app and maintaining it on the server.

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

TIP: you can run the latest version of secrdesignapp on your own machine directly from GitHub - see the link above.

IMPORTANT NOTE: Maximising precision is only one component of study design. Sampling must also be representative of the population in the region of interest. Linear arrays are unreliable when home ranges are elongated in a common direction (Efford 2019c).

*Use settings on this page to specify a detector layout, population and sampling parameters. The settings are interpreted in various plots and used for calculations shown in the Results window. They are also used for calculations on later pages (Costing, Spacing, Simulation).* \(\renewcommand{\vec}[1]{\mathbf{#1}}\)

Detector type | multi, proximity, or count |

Options for detector type follow **secr** (Efford (2019b)): “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.

The detector layout ('Array') may be specified as a rectangular grid or line (via `make.grid`

), read from a file, or as a systematic or random array within a region. Code for generating an array according to the current settings is shown on the Simulation page.

For a rectangular grid the options are:

rows | number of rows (ny) |

columns | number of columns (nx) |

row spacing | metres (spacey) |

column spacing | metres (spacex) |

hollow | detectors only on perimeter? |

The **secr** function `make.grid`

forms a rectangular detector layout. By default, column settings are equal to row settings; to alter this either change the column settings *after* the row setings, or see Options to uncouple rows and columns. The order of detectors is column-boustrophedonical (`make.grid`

argument ID = “numxb”), so connecting them in sequence gives a plausible route. See `?make.grid`

for more.

The 'Suggest spacing' button finds the spacing with \(\small \mbox E (n) = \mbox E ( r )\) and sets this for the current grid.

For a line the options are simply the number of detectors and the spacing. Lines are implemented with `make.grid`

as for grids. The 'Suggest spacing' button finds the spacing with \(\small \mbox E (n) = \mbox E ( r )\) and sets this for the current line.

This uses a text file in the format for **secr** function `read.traps`

. The file typically should have three columns (trapID, x, y) with no headers. Optional arguments separated by commas may be used to customise input (e.g., skip, which is passed through `read.traps`

to `read.table`

).

A region is a study area within which detectors will be placed either systematically on a square grid or at random. For both systematic and random options the elements may be a single detector or a cluster of detectors (Grid or Line). The region boundary may be provided as either

- a single text file (.txt) with two columns for the x and y coordinates of the perimeter, or
- a binary file saved from R (.RData, .Rda) in which the first object is a 2-column matrix or inherits from
**sp**class SpatialPolygons, or - a binary file saved from R (.RDS) in which the sole object is a 2-column matrix or inherits from
**sp**class SpatialPolygons, or - an ESRI polygon shapefile with at least three component files (.shp, .dbf and .shx) selected together.

See Options | Detector array to control the clipping of detector clusters that cross the boundary of the region.

A systematic array is specified by the cluster design, the spacing between cluster centres and the origin. By default the origin is fixed at (+sp/2, +sp/2) relative to the lower left corner of the bounding box of the region, where sp is the array spacing. Alternately the origin may be chosen at random within a square of side sp.

Two algorithms are offered for random placement - a simple random sample of points (SRS) or a balanced spatial sample as described by Stevens and Olsen (2004) and implemented in package **spsurvey** (Kincaid and Olsen 2018).

Detector clusters are rotated by the specified number of degrees (there's not much to gain from this).

Choosing a random origin or random array results in a set of locations that changes whenever one of the detector options changes. For repeatable randomisation set the random seed to an integer greater than zero.

Density | animals per hectare (multiply by 100 for animals per km^{2}) |

Detection function | HHN hazard halfnormal \( \small \lambda(d) = -\lambda_0 \exp\{-d^2/(2\sigma^2)\} \) |

HEX hazard negative exponential \( \small \lambda(d) = -\lambda_0 \exp(-d/\sigma) \) | |

lambda0 | intercept \(\lambda_0\) |

sigma | spatial scale \(\sigma\) |

Only two detection functions are supported: 'HHN' and 'HEX'. These relate an animal's hazard of detection at a particular detector on a particular sampling occasion (\(\lambda\)) to the distance \(\small d\) of the detector from its home-range centre. The corresponding probability of detection is \(\small g(d) = 1 - \exp \{ - \lambda(d)\}\).

See the Detectfn plot for the effect of given lambda0 and sigma.

Occasions | number of sampling occasions (times detectors were checked) |

Arrays | number of replicate identical arrays (not for Region array) |

Distribution | distribution of number detected |

A study may be extended by sampling on more occasions. The number of recaptures \(r\) increases indefinitely, but the number of distinct individuals \(n\) levels off.

Setting Arrays > 1 is a useful way to predict the outcome from multiple detector clusters when no region has been specified. Replicating the sampling effort at many independent locations within the same population increases both \(r\) and \(n\). Using multiple clusters (repeated arrays) is also a way to sample a large region. We assume detector clusters are far enough apart that no animal is detected on more than one cluster (array).

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 chosen distribution is used in simulations for both generating data and fitting a model.

The 'Auto refresh' box may be unchecked to delay updating until you have fully specified a scenario. This can save a lot of time.

Simulate | Simulate current scenario with settings on Simulation page |

Add to summary | Transfer scenario and results to summary table |

Reset all | Reset all input options to defaults (except file inputs) |

Bookmark | Creates a URL that allows you to take up your session where you left off (experimental) |

Simulation output is shown on the Simulation page and added to the Summary by default.

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

```
library(shiny)
runGitHub("secrdesignapp", "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, but not results on the Simulation or Spacing pages. 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`

.

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

Expected number of individuals^{1} |
\(n\) |

Expected number of recaptures^{1,2} |
\(r\) |

Expected number of movements^{1,3} |
\(m\) |

Median detectors per 95% home range^{4} |
across region for all non-zero points |

Overlap coefficient^{5} |
\( k = \sigma \sqrt D / 100 \) |

Effective sampling area^{6} |
\(a = \int_{R^2} p_\cdot(\vec x) \, d \vec x \) |

Rule-of-thumb RSE^{7} |
\( 100 . \mbox{CF} / \sqrt { \mbox{min} (n,r)} \) |

1. Formulae for the expected numbers of individuals, recaptures and movements are given in secrdesign-Enrm.pdf.

2. A recapture is any detection after an animal's first.

3. A movement is any recapture at a different detector to the previous one.

4. “home range”“ used here loosely; 95% radius from secr::circular.r; median is across mask, excluding non-overlapping points

5. \(k\) tends to fall in the range 0.3–1.1 (see Efford et al. 2016 for some examples). Scenarios with \(\sigma\) and \(D\) that result in \(k\) outside this range may be unrealistic. The coefficient is not computed when detectfn = "HEX” to prevent misleading comparisons.

6. \(\small p_\cdot(\mathbf x)\) is the probability an animal centred at \(\vec x\) is detected at
least once (Borchers and Efford 2008). \(a\) varies with the number of sampling occasions and \(\lambda_0\) as well as \(\sigma\).

7. See explanation below.

8. The diameter of an array is the greatest distance between two detectors. Arrays less than \(5\sigma\) in diameter may not be large enough to estimate sigma reliably.

Many of the Results require integration over possible animal locations. This is approximated by summing pixels in the 'habitat mask' defined in Habitat mask. The mask specification is usually not critical, but you may wish to play (e.g., cut nx to 32 for faster refresh).

The relative standard error RSE (aka CV) is a measure of estimator precision. \(\small \mbox{RSE}(\hat D) = \mbox{SE} (\hat D) / \hat D \). For a particular design the precision may be predicted approximately from the expected values of \(n\) and \(r\) – this is the “rule-of-thumb” RSE. The approximation is intended for Poisson-distributed \(n\) (see Distribution). Sampling variance is predictably less when \(n\) is binomial; the binomial \(\mbox{RSE}_B\) for a given Poisson \(\mbox{RSE}_P\) depends on the effective sampling area \(a\) and total mask area \(A\) as follows \[\mbox{RSE}_B = \sqrt {\mbox{RSE}_P^2 - 1 / (DA)}.\] This adjustment is applied whenever a binomial distribution is selected.

The raw “rule-of-thumb” RSE is further adjusted by a correction factor specified in Options. By default, the correction factor is also updated automatically to match the results from simulations whenever they are run.

The traffic light provides a quick and dirty indication of whether you are on the right track. Click on red or amber lights to see the reason. Thresholds are set in Options. The defaults are

- red – design is deemed pathological (expected number of detected movements E(m) < 5; array span < diameter of 95% activity circle) or predicted RSE > 20%.
- amber – predicted RSE in range 15–20%.
- green – predicted RSE <=15%

The suitability of these precision thresholds of course depends on the required power, and they are no more than a guide. Estimates from scenarios with RSE>20% may exhibit bias, so it is wise to aim for lower RSE even if you think that precision is sufficient.

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

A plot of the current detector layout. Coordinates may be viewed or output to a text file with the 'Save' link; the code used to generate the array is included in the header. The file is in a format suitable for `secr::read.traps`

. The summary text includes the ratio of the array diameter (grid diagonal) to the diameter of a 95% activity circle (HR95). HR95 is 2 x 2.45 sigma for detectfn = 'HHN' and 2 x 4.74 sigma for detectfn = 'HEX'.

Detection function on the hazard scale

One simulated realisation of a population with the 2-D distribution specified on the Simulation page. The 'Restrict to mask' option is available only when a Poisson 2-D distribution is specified.

Contours of the overall detection probability \(p_\cdot(\mathbf x)\) ('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.

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

1. 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 with the approximated RSE from the current design. Use the slider to vary this. Especially, consider adding a safety margin for underestimation of RSE.

It is likely that \(\small \mbox{RSE}(\hat D)\) will increase as density declines. By default, an adjustment is applied to the final RSE: \(\small \mbox{RSE}(\hat D_2) = \sqrt {D_1/D_2} \mbox{RSE}(\hat D_1) \). This may be removed by unticking the 'Adjust final RSE' box.

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

Settings here should be self explanatory. See secr-habitatmasks.pdf for background.

The mask may either be imported from a text file ('File') or built by buffering around the detector array from the Design page ('Build'). The format of the text file is that exported from **secr** >3.2.1with `write.mask`

(basically two columns, the x- and y-coordinates). The default buffer multiplier for the 'Build' option (4) may be inadequate when detectfn = 'HEX'.

dots | display mask points as dots rather than filled cells |

xpd | clip plot and suppress enclosing box |

show mask edge | use secr::plotMaskEdge to outline mask |

Travel per km $ | travel from detector to detector within an array |

Cost per array $ | one-off overheads for each array |

Cost per detector $ | one-off cost of purchase and installation |

Cost per detector visit $ | fixed cost per occasion, including set-up occasion |

Cost per detection $ | handling and lab costs |

Travel distance and per-visit costs are a function of the number of sampling occasions on the Design page. Usually there will also be travel and per-detector costs associated with a start-up visit; this may be excluded by un-ticking the “Include setup occasion” box.

Type | sequential, manual or sumspacing |

Return to start |

Travel cost depends on the length of the route taken to check detectors. If the layout lists detectors in the order they are to be visited then the default 'Sequential' option applies. However, this may not be the shortest route, especially if the route should return to the starting point.

The 'Manual' option allows the user to construct a route 'on the fly' by clicking near detectors at the turning points. Click on 'Define new route…' to start again.

The 'SumSpacing' option determines route length by summing inter-detector distances. This is unreliable if detectors are clustered and spacing is not uniform.

*This page optionally simulates the single scenario on the Design page. Simulations may be slow. You must close the application to abort them.*

A very approximate algorithm is used to predict the execution time from the product of

- number of mask points
- number of detectors
- number of sampling occasions
- expected number of detected animals, E(n)
- number of detector clusters
- number of replicates

with adjustments for the maximisation method (default “none”), detector type (default “proximity”) and fitting function (default `openCR.fit`

). If the predicted time exceeds 0.2 minutes a dialogue box allows the user to cancel simulations before they start.

Unfortunately, there is no elegant way to interrupt simulations once they have started. Close your browser window and start again.

Code is provided for users who want to go further. Multiple scenarios may be evaluated by providing vector arguments to `make.scenarios`

.

**secrdesign** >= 2.5.7 allows a choice between two functions for fitting closed-population SECR models: `secr.fit`

in package **secr** and `openCR.fit`

in package **openCR** (Efford 2019d). The default is to use the faster multi-threaded code in `openCR.fit`

(for this it is best to leave ncores = 1).

`Maximization method = 'none'`

by-passes likelihood maximization and evaluates the Hessian (and hence the variance-covariance matrix) at the true values of the parameters. This is a fast way to predict \(\small \mbox{RSE}(\hat D)\); it is apparently reliable and requires few replicates. Bias is not estimated.

If the 'Add to summary' box is ticked then simulation results are added automatically to the Summary table.

Function to fit model | choose between openCR.fit (fast) and secr.fit(slow), or bypass fitting |

Maximization method | method used for likelihood maximization by fitting function^{1} |

2-D distribution | model2D argument of sim.popn |

other details | free-form arguments passed in details list to sim.popn |

Replicates | number of replicate simulations^{2} |

Cores | number of cores for parallel processing^{3} |

Seed | random number seed^{4} |

1. The default 'none' does not estimate relative bias.

2. The default number is often enough for \(\small \mbox{RSE}(\hat D)\), but many more replicates are needed to estimate of \(\small \mbox{RB}(\hat D)\) reliably.

3. Simulations are spread across multiple cores if ncores > 1. There may be little gain in speed. The maximum number of cores is determined automatically with `parallel::detectCores`

.

4. Set a value greater than zero if you wish results to be repeatable. (Zero translates as NULL in the seed passed to `run.scenarios`

)

The 2-D (spatial) distribution of simulated activity centres is controlled in `sim.popn`

by the argument `model2D`

. These values are offered in secrdesignapp:

poisson | random uniform (Poisson) distribution |

cluster | clustered (Neyman-Scott) distribution controlled by parameters mu (mean number per cluster)
and hsigma (SD of bivariate normal within-cluster scatter)^{1} |

even^{2} |
systematic grid, each point jittered uniformly within its ‘cell’ |

1. The defaults mu=1 and hsigma=0 result in no clustering; vary these for a clustered distribution. The effect is shown in the Popn viewer on the Design page when 'Restrict to mask' is not selected.

2. Distribution of N (Ndist) coerced to 'fixed' in `sim.popn`

The Popn plot on the Design page displays realisations of the 2-D distribution specified on the Simulation page. The effect of varying the 2-D distribution on simulation results will only be apparent if a maximization method is specified (Newton-Raphson or Nelder-Mead).

Number of replicates | as input |

Time for simulations | seconds |

Number of animals (n) | mean and SE over replicates |

Number of detections (n+r) | mean and SE over replicates |

Number of moves (m)^{1} |
mean and SE over replicates |

Simulated \(\small \widehat{\mbox{RSE}}\) | mean and SE over replicates |

Empirical RSE^{2} |
Allows for clustered or even 2-D distribution |

Simulated RB^{3} |
mean and SE over replicates |

1. The number of moves is reported consistently with E(m) only for trap (multi) detectors.

2. Estimate of true RSE from variation in \(\small \hat D\) over replicates \( \small \mbox{SD}(\hat D / D) \).

3. Relative bias \( \small \mbox{RB}(\hat D) = (\hat D - D) / D \).

NOTE: If the 2-D distribution is not Poisson then the 'Simulated RSE' will be misleading because it is the average of the biased estimates of RSE reported when the model is fitted assuming a Poisson distribution. For a non-Poisson 2-D distribution, rely on the 'Empirical RSE', noting that this requires maximization of the likelihood as noted above. Empirical RSE will be highly variable between runs unless there are many replicates (a minimum of 20 is suggested).

This page evaluates the effect of detector spacing on precision and total cost. The array geometry is fixed on the Design page. A numerical search is performed for the array spacing that minimises the rule-of-thumb \(\small \mbox{RSE}(\hat D) \).

The Spacing tab is hidden when the detector array is of the File or Region types. The effect of using multiple detector clusters with a particular geometry may be emulated by setting the Array number.

This code shows how `optimalSpacing`

may be used to evaluate spacings. An internal version is executed when the button is clicked.

Optimal spacing (relative to sigma) |

Optimal spacing (absolute) |

Minimum RSE |

Use the 'Save' link to generate an RData file containing the object returned by `secrdesign::optimalSpacing`

. The object is named `spacingOutput`

with class `c('optimalSpacing', 'list')`

for which there is a plot method. Rule-of-thumb results are in component `rotRSE`

and simulation results, if any, are in component `simRSE`

. Use the results in an R session like this:

```
load("spacing.RData")
str(spacingOutput)
spacingOutput$rotRSE
plot(spacingOutput)
```

Rule-of-thumb RSE vs relative spacing. The spacing that minimises the rule-of-thumb RSE is shown with a dot.

Expected values of \(n\), \(r\), and \(m\) vs relative spacing (Design).

Costings follow the Costing page. Route length and expected number of detections vary with spacing. The cost components for travel and per-detection will therefore vary if their unit cost is greater than zero.

The table on this page has one column for each scenario; scenarios are added by clicking the 'Add to summary' button on the Design page, or automatically from Simulation. Fields from “simfn” onwards will have missing values if no simulation has been performed.

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

Here are some known pitfalls

This is a combined result of (i) when ncores = 1 all available cores are used for highly efficient multithreading by openCR.fit(), and (ii) parallel processing incurs substantial overheads of its own.

Run secrdesignapp from GitHub on your own machine for the best performance. See https://GitHub.com/MurrayEfford/secrdesignapp. You will need to install R packages secr, openCR, secrdesign, shiny and shinyjs.

At least .shp, .dbf and .shx.

This often happens when the boundary file for a large region is uploaded before setting the sigma parameter. With the default settings (Shape = Rounded, sigma = 25 m, nx = 32) there may well be no points in the mask. Fix this by increasing sigma.

This will happen when a rigid boundary is provided in Options | Habitat mask.

This is intended. The coefficient cannot be compared between HHN and HEX models, and the simplest way to prevent misunderstanding was to block for HEX.

A systematic or random array defined with a Region polygon may exclude sites that lie within other polygons (Options | Detector array | Excluded region). How is an exclusion applied to the habitat mask? Unfortunately the **secr** function `make.mask`

accepts only one polygon input, although this may represent either habitat or non-habitat. To combine habitat (inclusion) and non-habitat (exclusion) polygons you will first need to use GIS software (e.g., the `gDifference`

function in the R package **rgeos**) and save the result as a single SpatialPolygons object (e.g., as an .rds file).

```
library(rgdal)
library(rgeos)
setwd('d:/density secr 3.2/secrdesignapp')
region <- rgdal::readOGR(dsn = 'OVforest.shp')
# coordinates from text file
coord <- read.table('excltest.txt') # read boundary coordinates
excluded <- secr:::boundarytoSP(coord) # convert to SpatialPolygons
newpoly <- gDifference (region, excluded)
saveRDS(newpoly, file = 'newpoly.RDS')
```

The RDS file may then be used in Habitat mask | Mask polygon files.

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit
maximum likelihood methods for capture–recapture
studies. *Biometrics* **64**, 377–385.

Efford, M. G. (2019a) secrdesign: Sampling design for spatially explicit capture–recapture. R package version 2.5.7. https://CRAN.R-project.org/package=secrdesign

Efford, M. G. (2019b) secr: Spatially explicit capture–recapture models. R package version 3.2.1. https://CRAN.R-project.org/package=secr

Efford, M. G. (2019c) Non-circular home ranges and the estimation of population density. *Ecology* 100(2), e02580.

Efford, M. G. (2019d) openCR: Open population capture–recapture models. R package version 1.4.1. https://CRAN.R-project.org/package=openCR

Efford, M. G. and Boulanger, J. (2019) Fast evaluation of study designs for spatially explicit
capture–recapture. *Methods in Ecology and Evolution* (in press)

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.

Kincaid, T. M. and Olsen, A. R. (2018) spsurvey: Spatial Survey Design and Analysis. R package version 3.4. https://CRAN.R-project.org/package=spsurvey.

Stevens, D. L. Jr and Olsen, A. R. (2004) Spatially balanced sampling of natural resources.
*Journal of the American Statistical Association* **99**, 262–278.

CRAN.R-project.org/package=secrdesign

https://github.com/MurrayEfford/secrdesignapp