Description Usage Details Author(s) References Examples

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.

1 | ```
SPACECAP()
``` |

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

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

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.

1 | ```
SPACECAP()
``` |

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.