## Detector array

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

Requires text file with detector ID and x-y coordinates in three columns, as for secr::read.traps

## Actions

F11 to toggle fullscreen

## Results

p.(x) is the probability an animal at point x will be detected at least once

## Summary

## Results

## Standalone R code

See Simulation for options

## Results

## Spacing plot

Spacing relative to sigma

# Introduction

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, based on the expected numbers of recaptures and distinct individuals. 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 rule-of-thumb. Refine the approximation by simulating data from the chosen design; this may take a long time. 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).

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

# Design

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 array

 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.

### Grid

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.

### Line

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.

### File

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

### Region

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 clusters that cross the boundary of the region.

A region based on an ESRI shapefile cannot at present be restored from a bookmark (see Troubleshooting).

#### Systematic

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.

#### Random

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

#### Rotation

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

#### Random seed

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.

## Parameters

 Density animals per hectare (multiply by 100 for animals per km2) 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.

## General

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

## Actions

 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. ## Results Values in the Results window are updated automatically when the inputs change.  Expected number of individuals1 $$n$$ Expected number of recaptures1,2 $$r$$ Expected number of movements1,3 $$m$$ Median detectors per 95% home range4 across region for all non-zero points Overlap coefficient5 $$k = \sigma \sqrt D / 100$$ Effective sampling area6 $$a = \int_{R^2} p_\cdot(\vec x) \, d \vec x$$ Rule-of-thumb RSE7 $$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. ## Traffic light 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. • red – design is deemed pathological (fewer than 5 movements expected, 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. ## Tabbed plots Plots update automatically. Any plot may be saved by right-clicking on the image. ### Array 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'. ### Detectfn Detection function on the hazard scale ### Popn One simulated realisation of a uniformly distributed population. ### Pxy 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. ### 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 Appendix 1 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 Settings here should be self explanatory. See secr-habitatmasks.pdf for background. The default buffer multiplier (4) may be inadequate when detectfn = 'HEX'. # Costing ## Unit cost  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.

## Route

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.

# Simulation

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 detectors
• number of sampling occasions
• expected number of detected animals, E(n)
• number of 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.

## Standalone R code

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

## Simulation control

### Fit simulated data

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.

### simulation controls

 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 function1 Replicates number of replicate simulations2 Cores number of cores for parallel processing3 Seed random number seed4

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)

## Results

 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 RSE mean and SE over replicates Simulated RB2 mean and SE over replicates

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

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

# Spacing

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 clusters with a particular geometry may be emulated by setting the Array number.

## Standalone R code

This code shows how optimalSpacing may be used to evaluate spacings. An internal version is executed when the button is clicked.

## Results

 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)


## Tabbed plots

### RSE

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

### nrm

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

### Cost

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.

# Summary

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.

# Options

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

# Troubleshooting

Here are some known pitfalls

## Bookmark fails with shapefile polygons

This is a known bug that cannot be addressed immediately. It is avoided by saving SpatialPolygons as .rds or .rdata files.

## Slow simulations when ncores > 1

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.

## Components of a shapefile must be selected and uploaded together

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.

## Detector array extends beyond mask with File input and factor > 1

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

## Overlap coefficient k disappears when detectfn = 'HEX'

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.

## No exclusion option for habitat mask

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(rgos)
setwd('d:/density secr 3.2/secrdesignapp')
# coordinates from text file
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.

# 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. (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.0. 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.3.4. https://CRAN.R-project.org/package=openCR

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.

# Appendix 1. Power calculation for comparison of two density estimates

We want to predict the power of a comparison between two independent surveys as a function of the effect size ($$\small D_{21}$$ = final density as fraction of initial density) and the predicted precision of the estimates, expressed as relative standard error RSE. The power calculation assumes log-normal errors in both the initial and final surveys. Log-normal errors are natural for estimates of density (we use a log link function for maximising the likelihood, and rely on symmetrical Wald intervals on the log scale).

For a log normal distribution the variance on the log scale is $$\small \sigma^2 = \log (1 + \mbox{CV}^2)$$ where CV is the coefficient of variation on the arithmetic scale (equivalent here to RSE).

The mean $$\mu$$ on the log scale is related to the mean $$m$$ on the arithmetic scale by $$\small \mu = \log \frac{m}{\sqrt { 1 + \mbox{CV}^2}}$$.

We conduct a $$z$$-test on the log scale. The effect size is $$\small \mu_2 - \mu_1$$. In general we must allow for differing RSE in the two surveys, which affects both the effect size and its variance, as follows.

$\small \mu_2 - \mu_1 = \log \frac{m_2}{\sqrt {1 + \mbox{CV}_2^2}} - \log \frac{m_1}{\sqrt {1 + \mbox{CV}_1^2}}.$ This reduces to $\small \mu_2 - \mu_1 = \log \frac{m_2}{m_1} + \log \frac{\sqrt {1 + \mbox{CV}_1^2}}{\sqrt {1 + \mbox{CV}_2^2}}.$ For equal CV the second term drops out.

The variance of the effect on the log scale is approximated by the sum of the respective variances:

$\small \sigma_{21}^2 = \log(1 + \mbox{CV}_1^2) + \log(1 + \mbox{CV}_2^2).$ The standardised difference on the log scale $$\frac{\mu_2 - \mu_1}{\sigma_{21}}$$ is compared to a standard normal variate at the desired alpha level.

In our application we replace $$\small m_2 / m_1$$ by $$\small D_{21}$$ and $$\small \mbox{CV}_1$$ by RSE.

To adjust for density-dependent RSE we assume that a difference in RSE between surveys is inversely proportional to the square root of $$\small D_{21}$$ (this follows the logic of the rule-of-thumb in which both $$n$$ and $$r$$ scale with density). Thus $$\small \mbox{CV}_2 = \mbox{RSE} / \sqrt{D_{21}}$$.