SPACECAP: Fits spatially-explicit capture recapture models

In SPACECAP: A Program to Estimate Animal Abundance and Density using Bayesian Spatially-Explicit Capture-Recapture Models

Description

Function SPACECAP is the workhorse of the pkgSPACECAP package. It opens a Graphical User Interface (GUI) where the user selects the files containing the capture-recapture data, selects options for the model to run, and specifies the variables for the MCMC estimation. MCMC samples from the posterior distributions of the parameters are generated and saved as files, together with summary statistics and kernel density plots.

Usage

SPACECAP()

Details

Installing SPACECAP Version 1.1.0

You must have a recent version (R 2.15.3 or higher) of program R installed on your computer. If necessary, go to http://www.r-project.org/, select a mirror, then download and install R for your platform.

Launch R, and at the ">" prompt type

install.packages("SPACECAP")

and press Enter. SPACECAP must be upper case and in quotes. You will be asked to select a CRAN mirror and may need to confirm that R should create a personal library for your packages. SPACECAP depends on coda, and that should be installed automatically at the same time. You only need to install SPACECAP once.

SPACECAP stores its output in subfolders of R's working directory. You can set the working directory with the File > Change dir... option in the console or by typing setwd(choose.dir()) and browsing to the folder you want the output to go to.

To launch the SPACECAP GUI, you need to have R open, then at the ">" prompt enter

library(SPACECAP)
SPACECAP()

Note the empty parentheses () after SPACECAP in the second line.

You will not be able to work in the R Console while the the SPACECAP GUI is open. If you want to work in R while the analysis is running, you can open another instance of the R Console. You can even have several SPACECAP analyses running at the same time, by launching them from different R instances, and they will use different cores on a multicore computer.

SECR Analysis using SPACECAP

Running an SECR Analysis in SPACECAP involves four steps:

1. Setting up the input files
2. Selecting the appropriate model combination
3. Selecting the Markov chain Monte Carlo (MCMC) settings
4. Clicking "Run" on the main menu bar.

STEP 1: SETTING UP THE INPUT FILES FOR ANALYSIS

SPACECAP requires three input files:

1. Animal Capture File (Animal ID, trap ID, capture occasion)

2. Trap Deployment File (Trap ID, location and deployment record)

3. State-space File (the Potential Animal Home Range Center locations and habitat suitability indicator for these home range centers)

See the Example files page for more details and examples.

These three data files can be created using spreadsheet applications such as Microsoft EXCEL or LibreOffice Calc. They must be saved in ASCII comma separated format (.csv), because SPACECAP can only read these types of input files.

INPUT FILE 1: Animal Capture Details

This is a table with 3 columns: Location Number, the Animal Identity Number and the Sampling Occasion number, in that order. Note that these are all "number" fields: use simple integer numbers.

Each individual captured should be given a unique identification number, ranging from 1 to n, where n is the total number of individuals included in this file. In the example below, the records have been sorted by ANIMAL_ID to facilitate checking that no numbers are missing.

Location Numbers must correspond to the numbers in the Trap Deployment file.

If only 6 animals were photo-captured and identified, the INPUT FILE 1 for SPACECAP might look like this:

LOC_ID	ANIMAL_ID	SO
11	1	14
15	2	12
9	3	20
1	4	17
5	5	13
7	6	17
8	6	16

For example, the first row of data tells us that Animal ID no 1 was captured at Location ID 11 on the 14th sampling occasion.

The first row of the file must have the exact column headings as shown above, or it will not be recognized by SPACECAP.

INPUT FILE 2: Trap Deployment Details

The first column of this file has the Location Number. The next two columns have the X and Y coordinates of the trap location: see the example below. Use a projected coordinate system (ie, in meters, not degrees), such as UTM (Universal Transverse Mercator) or your national grid system.

After these first three columns, there is one column for each trapping occasion. Here, "1" means that a trap was operating at that location on that occasion, "0" means that no trap was operating. You do not have to have a trap at every location for the whole period. In particular, trap malfunction, theft, vandalism, etc. can be accounted for.

An example TRAP DEPLOYMENT DATA file is shown below. This file has 16 locations, but there were only 4 traps, which were moved between locations.

LOC_ID	X_Coord	Y_Coord	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20
1	619303	1325966	1	1	1	1	1	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
2	624151	1325013	1	1	1	1	1	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
3	624722	1323864	1	1	1	0	1	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
4	621806	1322453	1	1	1	1	1	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
5	622451	1320137	0	0	0	0	0	1	1	1	1	1	0	0	0	0	0	0	0	0	0	0
6	622599	1317937	0	0	0	0	0	1	1	1	1	1	0	0	0	0	0	0	0	0	0	0
7	623179	1315941	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
8	625156	1315587	0	0	0	0	0	1	1	1	1	1	0	0	0	0	0	0	0	0	0	0
9	626022	1314224	0	0	0	0	0	0	0	0	0	0	1	1	1	1	1	0	0	0	0	0
10	627568	1315494	0	0	0	0	0	0	0	0	0	0	1	1	1	1	1	0	0	0	0	0
11	619604	1324739	0	0	0	0	0	0	0	0	0	0	1	1	0	1	1	0	0	0	0	0
12	621478	1324515	0	0	0	0	0	0	0	0	0	0	1	1	1	1	1	0	0	0	0	0
13	623317	1323989	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	1	1	1	1	1
14	624406	1321603	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	1	1	1	1	1
15	624482	1320577	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	1	1	1	1
16	629229	1319793	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	1	1	1	1	1

The table shows that the first four locations were operational during sampling occasions 1-5, except that the trap at location 3 was not working on occasion 4. No traps were operational at these sites on occasions 6 to 20.

Again, the first row must have column headings as shown in the example above.

INPUT FILE 3: Potential Home Range Centers

This file contains the locations of possible home range centers for all the animals which might be detected by our traps. These are represented by a large number of equally spaced points or pixels in the form of a grid. This grid can be produced by GIS software such as ArcView or QGIS. See the figure on the Example files page.

To generate this file, you need to decide (1) the extent of the state space, (2) the size of the pixels, and (3) what habitat would be suitable as a home range center for your species.

The extent of the area covered by the file must be big enough to include the home ranges of animals with a reasonable probability of being captured. Under the Gaussian hazard model, animals with home range centers more than 3 or 4 times the detection function scale parameter, sigma, from the nearest trap have a negligable probability of being caught. For the negative exponential model we think 3-4x sigma should also be adequate but recommend checking this for specific data sets. Use a guestimate of the home range radius for a preliminary run, and check against the value of sigma produced (see Things to check below).

In principle, the state space cannot be too large, but in practice a large area will need a higher value for data augmentation (see below) and will run more slowly. Note that the estimate of density does not depend on the area of the state space, provided that is large enough.

Pixel size is related to home range size. For the animals captured, the software will estimate the location of the home range center, but has only pixel centers to choose from. This clearly would not work well if pixels were larger than home ranges. Pixel areas roughly (1/16) - (1/32) of a typical home range area would be appropriate.

Note the area of the pixel used, as that must be entered when running SPACECAP and a mistake there will result in a wrong answer for the density.

The potential home-range centers data file consists of a 3 column table. The first two columns are the X and Y coordinates (using the same coordinate system as the trap location file) of the center of each pixel in the state-space. The third column is a habitat suitability indicator, with "1" if the pixel centre lies within suitable habitat or with "0" otherwise. The first few rows of such a file is given below (the actual file will have thousands of rows):

X_COORD	Y_COORD	HABITAT
611734	1299581	1
612301.6	1299583	1
612869.2	1299585	0
613436.9	1299587	0
614004.5	1299589	0
614572.2	1299591	0
615139.8	1299593	0
615707.5	1299595	1
616275.1	1299597	1
616842.8	1299600	0
617410.4	1299602	1
617978.1	1299604	1
618545.7	1299606	1

Again, the column headings in the first row must be exactly as shown in the example.

Entering the file names in SPACECAP

The "Input Data" panel is the top left portion of the SPACECAP window. Use the Browse buttons to select each of the three input files in turn.

Enter the area of the pixels created for the potential home range centers file (in sq km) in the box below the file names.

Click on "OK" in the "Input Data" panel and check the frame at the bottom of the window for status or error messages. To edit your selection, just click on the "Edit" button and start the selection all over again.

STEP 2: SELECTING THE APPROPRIATE MODEL COMBINATION FOR ANALYSIS

The Model Definition panel of SPACECAP consists of a set of options to select an appropriate model combination for the Spatial-Capture Recapture Analysis. Model options that are "grayed out" are not available with the current version of SPACECAP.

The model choices are:

1. Trap response present OR Trap response absent The "Trap response present" option implements a local or "trap-specific" behavioral response under which the probability of encounter in a trap increases (or decreases) after initial capture in that specific location. This is in contrast to the conventional "global" behavioral response which implies a response to all traps everywhere after being caught once.

2. Spatial Capture-Recapture OR Non-spatial Capture-Recapture Select "Spatial Capture-Recapture" for running a spatially explicit capture-recapture analysis, or "Non-spatial Capture-Recapture" for running a conventional capture-recapture analysis (this is equivalent to the Null Model "M0" in non-spatial CR analysis)

Note that including a location-specific trap response in a non-spatial model may lead to spurious results, as the trap response coefficient will pick up the spatial structure in the data.

3. Half Normal OR Negative Exponential

See the discussion of detection functions on the Model and Priors help page. The half normal detection function is generally a good fit to the data. This has no effect for non-spatial analysis.

4. Bernoulli (binary) OR Poisson encounter process Currently the analysis is run with the Bernoulli encounter model in which the probability of success is derived as the probability of a positive response under a Poisson encounter rate model. This motivates use of the complementary log-log link which relates encounter probability to distance and other covariates.

After the model definition is complete, click on "OK" and check the frame at the bottom for status or error messages. To edit your selections, just click on the "Edit" button, change your model definition and click on "OK" again.

STEP 3: SETTING THE MARKOV-CHAIN MONTE CARLO (MCMC) PARAMETERS

SPACECAP uses a Markov-Chain Monte Carlo simulation algorithm written in R to estimate the parameters of the SECR models of Royle et al (2009). (Wikipedia has a short page on Markov chain Monte Carlo methods.) The relevant settings can be set in the MCMC simulation settings panel of SPACECAP.

No of iterations - This defines the total number of MCMC iterations for the analysis.

Burn-in - This defines the number of initial values to discard during the MCMC analysis. The Geweke diagnostic (see below) will indicate if this is adequate.

Thinning - This defines the proportion of iterations included in the output. If thinning = 10, only 1 in 10 of the iterations will be stored.

The number of values returned will be (iterations - burn-in) / thinning. The goodness-of-fit calculations are run for each value returned, and these are slow, so you should aim for about 10,000 values returned.

It is a good idea to do short runs to begin with (say 10,000 iterations with 5,000 burn-in) and do a much longer run to get your final results (at least 100,000 iterations with enough burn-in to give adequate Geweke statistics).

Data augmentation - This is the maximum number of uncaught animals in the whole state space, and sets an upper limit to the estimate of N for the MCMC run. If it is too low, the estimate of N and (hence the density) will be incorrect. On the other hand, the run time increases linearly with the data augmentation value. Try an initial value of 5 to 10 times the number of animals captured, and check the output (see the Things to check section below) and rerun with a higher value if necessary.

See the Priors for N and psi section of the Model and Priors page.

After the MCMC simulation values have been specified, click on "OK" and check the frame at the bottom for status or error messages. To edit these settings, just click on the "Edit" button, edit these values and click on "OK" again. You are now all set to start the analysis.

STEP 4: Running the analysis

Click on "Run" in the top menu bar. This will start the analysis and you will see a progress bar indicating the status of the analysis. Samples from the MCMC chain are reported in the bottom panel in the SPACECAP window and in the R Console.

Currently, an analysis of the example data set with the default model, 50,000 iterations, 20,000 burnin, thinning by 10, and data augmentation of 350 takes about 9.5 hours on a fast computer.

Results

The posterior density estimates along with standard errors appear as a table in the middle panel of the SPACECAP window and in the R Console when the analysis is complete. This table also reports estimates of parameters lam0, sigma, and psi. For a non-spatial analysis, sigma will be reported as NA. If the analysis was run with trap response present, beta, p1, and p2 are reported; the probability of capture (if trap to home range center distance is zero) = p1 before the first capture and p2 afterwards. With no behavioural response, these will be equal, and beta will be zero.

SPACECAP produces a number of files which you will find in a folder called "output_<timestamp>" in your working directory (use getwd() so see your working directory path):

info_<timestamp>.txt	a text file with background information and diagnostics.
param_val_<timestamp>.csv	the full MCMC chain for each parameter
summary_stats_<timestamp>.csv	summary statistics for each parameter
pixeldensities_val_<timestamp>.csv	estimates of density for each of the pixels in the potential home-range centers input file (for spatial models)
detectionFunction_<timestamp>.jpg	a plot of the detection function (spatial models)
density_lam0_<timestamp>.jpg	a density plot for the lam0 parameter
density_N_<timestamp>.jpg	a density plot for N
density_psi_<timestamp>.jpg	a density plot for psi
density_sigma_<timestamp>.jpg	a density plot for sigma (spatial models)
density_beta_<timestamp>.jpg	a density plot for beta (behavioural response models)

Things to check

Data augmentation: Check the density plot for psi; the right-hand tail should not get up to 1. The same applies to the density plot for N; the tail should not approach the upper limit of the prior. If it does, rerun the analysis with a higher value for data augmentation.

State-space extent: For spatial models, check the detection function plot and the detection probability for the smallest trap to state space edge distance. The detection probability for any animals with home ranges outside must be very small.

Convergence: The Geweke test (see geweke.diag) compares the means of the first 10% and the last 50% of the values in the chains. The z-scores are in the info file and should all be between -1.6 and +1.6. If not, rerun with a longer burn-in period.

Sample size: The values in the chain are not independent, and successive values are correlated. The effective sample size is the sample size adjusted for this autocorrelation (see effectiveSize). Effective sizes of several hundred are adequate for point estimates (mean or median), but many thousand are needed to get good estimates of the 95% HDI and to get smooth density curves. If necessary, run with more iterations (and higher thinning).

Model fit: Values of the Bayesian P-value (Royle et al. 2011) close to 0 or 1 imply that the model is inadequate. No simple solution to this, you will have to think of a better model!

Author(s)

Arjun M. Gopalaswamy, Jeffrey A. Royle, Michael E Meredith, Pallavi Singh, Devcharan Jathanna, N. Samba Kumar and K. Ullas Karanth

References

Geweke, J. 1992. Evaluating the accuracy of sampling-based approaches to the calculation of posterior moments. In: Bayesian Statistics, 4 (Bernardo, J. M. et al., Eds), 169-193. Oxford University Press.

Royle, J. A., K. U. Karanth, A. M. Gopalaswamy and N. S. Kumar. 2009. Bayesian inference in camera trapping studies for a class of spatial capture-recapture models. Ecology 90(11), 3233-3244.

Royle, J. A., M. Kery and J. Guelat. 2011. Spatial capture-recapture models for search-encounter data. Methods in Ecology and Evolution 2:602-611.

Examples

SPACECAP()

SPACECAP documentation built on May 2, 2019, 9:17 a.m.