The ascr package

The ascr (“acoustic spatial capture-recapture”) package provides software implementation for the fitting of spatial capture-recapture models for acoustic data.

This manual details a user interface which may be used to fit these models. This application was developed in partnership with IUCN SSC primate specialist group section on small apes. All source code is available here

Using the ‘ascr’ interface

Locally

Requirements: R and the ascr package.

  • Download the ascr_shiny folder.

  • Extract the files from the zipped folder

  • Open R run this script having set appDir <- "path/to/ascr_shiny" to the appropriate path.

Online

Follow this link

The ascr user interface

On launching the ascr you will be faced with an interactive web page, which will look like the screenshot below.

All controls for the ascr user interface are situated in the left-hand sidebar. Content and modeling output is displayed in the main-panel. The layout of the sidebar and the main-panel is designed to lead the user through the required steps in fitting an acoustic spatial capture-recapture model (i.e., data, mask, model).

A brief overview of the modelling requirements may be found on the Details tab of the interface. Output is displayed in one of the Data, Mask, or Model tabs.

Further details regarding each of the modelling steps are given below.

It should be noted that certain options in the sidebar will not be available to the user until the required preceding steps have been completed (e.g., one cannot fit a model without loading in data).

Read in and inspect data

Either load your own data or use example data included with the software. The trap location file must contain columns named x, y, and post identifying UTM coordinates and a numeric identifier of each trap. If the data contain multiple arrays the file must also contain a numeric column named array . The detections file must contain columns named occasion, group, and post that correspond to the occasion at which each group was heard by which trap (corresponding to the traps in the trap location file). If the data contain multiple arrays the file must also contain a column named array matching those in the trap location file. The detections file may also contain a column headed bearing or distance or both. These must refer to the estimated bearing of the call (in radians \(\in (0,2\pi)\) or degrees) and the estimated distance to the call (meters). If this is the case then additional parameters are estimated related to these distributions.

The example data included with the ascr package may be used by checking the *Use example data. Here use of the ascr user interface is demonstrated using a subset of the multi array data (includng bearing information) relating to northern yellow-cheeked gibbons Nomascus annamensis analysed in Kidney, D., Rawson, B. M., Borchers, D. L., Stevenson, B. C., Marques, T. A., & Thomas, L. (2016). An efficient acoustic density estimation method with human detectors applied to gibbons in Cambodia. PloS one, 11(5), e0155066.

On selecting the Data tab your data will be displayed. It is important to check that the data is displayed correctly (i.e., imported in correctly from the .csv file). If this is not the case the sidebar has certain options that dictate how the .csv file format is understood

The Traps tab will show the raw data and automatically plot the position of the traps. The locations of the traps are understood to be given by the x and y named columns of your data. In addition the traps should be identified by a numeric column named post. If you have multiple arrays your file must contain a column named array specifying the numbered arrays, which should match those array numbers given in your detections data.

The Detections tab will show the raw detection information and the constructed capture history matrix (the format ascr requires the data). The detections data must contain columns named occasion, group, and post that correspond to the occasion at which each group was heard by which trap (corresponding to the traps in the trap location data). The detections data may also contain a column headed bearing (rad) or distance (m) or both. These must refer to the estimated bearing of the call (radians \(\in (0,2\pi)\) or degrees) and the estimated distance to the call (meters). If this is the case then additional parameters are estimated related to these distributions. If you have multiple arrays your file must contain a column naed array specifying the numbered arrays, which should match those array numbers given in your traps data.

Multiple arrays

If your data contain multiple arrays please ansure that both your traps and detections files contain a column names array and that they contain the same numeric identifiers. If this is the case Please ensure you ckeck the Multiple box underneath Single or multi array buttons in the sidebar as below.

Once Multiple is chosen your data is split according to each array identifier and the model will treat the data as x separate arrays of traps. You will also, for illustration purposes only, see dropdown menues linked to illustrative output so that the chosen array data is displayed.

Constructing the mask

Acoustic spatial capture-recapture (ascr) (thus, of course spatially explicit capture-recapture (SECR)) modelling requires the use of a mask. The mask is a fine grid of coordinates around the trap locations which is used to provide a set of plausible locations for each detected call.

The two choices to be made when constructing your mask are the buffer (m) and the spacing (m). These can be chosen using the sliders under the Build mask heading in the sidebar (see below).

The buffer (m) gives the maximum distance between each mask point and the closest trap. It should to be large enough so that the region it covers all plausible locations for the detected calls—this will depend on the species being detected (e.g., for a gibbon group this is \(\sim\) 2km, whereas for a Western Cape moss frog this will be \(\sim\) 40m).

The spacing (m) gives the distance between adjacent mask points. Thus, the smaller the spacing the finer the mask resolution and the greater the number of mask points.

The Build mask button must be clicked to construct the mask. Once done the left hand main panel will display the mask/s.

Select the Mask tab to visualize the mask and asses if you think the buffer zone and spacing are appropriate.

Model data

Detection function

The Modelling section of the sidebar allows the user to choose one of three detection functions:

  • halfnormal—\(g(d;g0,\sigma) = g0 \; \text{exp}( \frac{-d^2} {2 \; \sigma^2 })\);

  • hazard-rate—\(g(d;g0,\sigma,z) = g0 \; ( 1 - \text{exp}( -\frac{d}{\sigma}^{-z} ))\);

  • threshold—\(g(d;\text{shape},\text{scale}) = 0.5 - 0.5 \; erf( \frac{d}{\text{scale}} - \text{shape})\).

Occasionally the you may want to fix a particular parameter, to do so check the corresponding check-box and and choose the value at which to fix. The image below shows the parameter g0 fixed an \(1\) for the halfnormal distribution. Advanced model fitting options are available under the Other (Advanced options) section and include selecting parameter starting values. Further details are given below.

Once you are happy with the mask and detection function clicking the Fit model button will initiate model fitting.

Model output

The Model (Output) tab will show the parameter estimates of the model and other model outputs. If the data provided includes one or both of bearing or distance columns the model will includes this information in the model fitting. Therefore if you do not want to include this information import a file that does not include these data.

As illustrated by the image below a table of parameter estimates is displayed. The parameters estimated will depend on the form of detection function chosen and the parameters fixed (i.e., here g0 is not estimated as it has been fixed to 1). Estimated parameters will always include:

  • D: A parameter related to calling group density. Divide this estimate the number of days your survey ran at each array to obtain an estimate of daily calling group density, in groups per hectare. This is the density of groups that call on a single day. Further dividing by the probability that a group calls on a day (estimated from external data) yields an estimate of gibbon group density, in groups per hectare.

Other parameters may include:

  • g0: Intercept for either the halfnormal or hazard-rate detection function,

  • \(\sigma\): Scale parameter for either the halfnormal or hazard-rate detection function,

  • z: Shape parameter of the hazard-rate detection function,

  • shape: Shape parameter of the threshold detection function,

  • scale: Scale parameter of the threshold detection function,

  • \(\kappa\): Concentration parameter of the bearings measurement error distribution (von Mises),

  • \(\alpha\): Shape parameter of the distance measurement error distribution (gamma).

In all cases the model log-Likelihood value and the AIC score will be displayed as well as the estimated detection function and detection surface. The sidebar includes functionality to display the estimated location of a call and the distance at which to plot the distance measurement distribution (if distance data is provided). By default these values are call 1 and 1m respectively. If bearing data is provided the bearing measurement error distribution is also plotted—centered at 0. These plots will refresh once a new model is fitted (i.e., Fit model is activated). Each plot may be downloaded by using the appropriate buttons in the sidebar.

One thing to note is the interactive nature of the Location estimate plot. This plot uses the model data to estimated the most probable location a call emanated from. If bearing and/or distance information is provided then these data are used to estimate the locations of the call. As both bearing and distance information is included in this example arrow direction and length represent the estimated bearing and distance of each call. The contours represent the area within which the call is estimated to have originated from.

As well as choosing a call number to display (see above) you may zoom in on areas of the Location plot (see below). To do so click and drag your pointer over the area you wish to inspect (center plot) and double-click to obtain a zoomed version (right hand plot). To reset the plot back to its original state use the Reset location plot button in the sidebar.

Other things to note

In addition to saving each of the plots resulting from mask construction and modelling a .html which includes an animation (see screenshot below) of the estimated call locations, the frame rate of which can be chosen (default is one per second). Note that this may take a few minutes and during the download the app will be disabled.

Any output plots may be downloaded using the appropriate download buttons. For the static loaction estimate plot there is also an option to chose the call umber to display. In addition if your data contain multiple arrays then the array to plot may also be set.

Advanced options

Other options of note are revealed upon checking the Advanced options check box. Here the user may,

  • change bearings from degrees to bearings—if the app recognizes that bearings are in degrees not radians you will be prompted to check this option,

  • increase the mask buffer size—the range of the mask buffer (m) slider is chosen based on the trap coordinates; however, occasionally the maximum may need to be increased (see below),

  • chose parameter starting values—the ascr package will by default chose starting values for the optimization. However, upon occasion the optimizer will fail and a convergence error will be thrown. In this case typically defining more appropriate starting values will solve the convergence problems. Checking this box will allow you to set starting values for the parameters in the model (see below the value of 1 is chosen as a starting value for the parameter \(\sigma\)). Note—if a parameter is fixed (above) one clearly cannot provide a starting value.

  • build finer mask for plotting—to obtain smoother contours on the Location estimate plots a finer spacing (m) may be chosen. This will only affect the plotting and not the modelling.