In r-glennie/openpopscr: Open Population Spatial Capture-Recapture

knitr::opts_chunk$set(
  collapse = TRUE,
  fig.width = 7, 
  fig.height = 7, 
  comment = "#>"
)

The ScrData class is an R6 class. R6 classes are used to create objects. Objects can have properties and functions. These objects are convenient because they can be stored and used as a single R object, but contain within them all the information and methods related to them.

In this vignette, I describe how spatial capture-recapture data can be stored within an R6 object of the ScrData class.

library(openpopscr)
library(secr)

Raw data

The secr package contains the functions read.traps, make.capthist, and make.mask. They can be used to convert raw data collected in SCR surveys into a capthist object and mask object. These functions are available in the openpopscr package also.

On a side note, I call the mask object a mesh. The terms are interchangable.

For this vignette, I will use the stoatDNA data available from the secr package. These data come from a DNA hair trapping survey on stoats.

# load data 
data("stoat")
captures <- stoat$captures
traps <- stoat$traps

# look at capture history structure 
str(captures)
# look at detector locations 
str(traps)

The read.traps function takes a data frame with x, y coordinates for each detector and creates the traps object. The detector type here is "proximity" because DNA hair traps only record whether the stoat was detected or not by the trap, not how many times it was detected (that would be a "count" type detector). Also, with proximity detectors it is possible for a single individual to be detected on more than one trap during a single occasion; if this is not the case, then the traps are called "multi" type.

 detectors <- read.traps(data = traps, detector = "proximity")

The make.capthist function creates the capthist object.

capthist <- make.capthist(captures, detectors)

This data does not have a custom mesh, so I create one using make.mask:

mesh <- make.mask(detectors)

If you do not know how to construct a mesh using the make.mask function, please read the help file from the secr package website. Similarly, a help file on how to input the capture and trap data may also be useful.

A simple ScrData object

The ScrData object requires at least the capthist and mesh objects. R6 objects are created using the $new function.

scrdat <- ScrData$new(capthist, mesh)

Typing the name of the object into the terminal will create a plot and capthist summary information from the secr package. In the plot, detectors are red crosses, the mesh points are grey, and captures are coloured by individual.

scrdat

The functions of the ScrData object can be used to extract the capture history, mesh, or other information:

# get number of unique individuals seen 
scrdat$n()

# get number of occasions in the survey 
scrdat$n_occasions()

# get number of traps in the survey 
scrdat$n_traps()

# get number of mesh points in the survey 
scrdat$n_meshpts()

# get total area of the mesh in square kilometres 
scrdat$area()

# get matrix of distances between each trap and each mesh point 
dist <- scrdat$distances()
# e.g. distances from trap 1 to first 6 mesh points 
head(dist[1,])

One thing to note is the area function, it returns the area in square kilometres, not hectares. Hectares is the standard unit of area for the secr package.

Time

Occasions may occur at irregular intervals. This information can be included in the ScrData object when it is created. For example, suppose the data were collected on $3$ days, then a week later, for $4$ days. The time index of each occasion in days would then be

time <- c(1:3, 10:13)

This is included in the ScrData object when $new is called.

scrdat <- ScrData$new(capthist, mesh, time = time)

It can be accessed using the command

scrdat$time()

When time is not specified, it is assumed that occasions occurred in regular intervals of duration $1$.

Covariates

The ScrData object can handle three kinds of covariates: detector-specific, temporal, or mesh.

Detector-specific covariates are called $j$ type covariates, because $j$ is typically the mathematical index used for detectors. Suppose there is a variable $x$ that could affect how detectors operate. I create imaginary variables here:

quality <- factor(sample(c("bad", "good"), size = nrow(detectors), replace = TRUE))
weather <- runif(scrdat$n_occasions())
habitat <- scrdat$covs()$x * 2 + scrdat$covs()$y * 0.5 - scrdat$covs()$x*scrdat$covs()$y*2

This is a factor variable that labels each detector as a "good" or "bad" detector.

The covariate can be included after creating the ScrData object, specifying the covariate name, the vector of values, and the type.

scrdat$add_covariate("quality", quality, "j")
scrdat$add_covariate("weather", weather, "k")
scrdat$add_covariate("habitat", habitat, "m")

Temporal and mesh covariates are added in the same way, except the cov_type is "k" or "m". You can also include covariates that vary by detector and time ("kj") or space and time ("km"). For "kj" covariates, you should supply a matrix with a row for each occasion and a column for each detector. For "km" covariates, you supply a matrix with a row for each occasion and a column for each mesh point.

Once covariates have been included, you can extract the covariates for any particular detector or time using the covs function. To list all covariates, just call the function with no arguments:

scrdat$covs()

Notice, that some covariates are automatically created, e.g., time 't', x coordinate 'x', y coordinate 'y'.

Covariates can be subset by detector or time or mesh point:

• Get covariates for detector 1 on occasion 2 mesh point 1

scrdat$covs(j = 1, k = 2, m = 1)

• Get quality covariate for detector 7 on all occasions

scrdat$covs(j = 7, m = 1)$quality

• Get covariates for detectors 1 to 7 on occasions 3 and 5 for mesh points 1,2

scrdat$covs(j = 1:10, k = c(3, 5), m = c(1, 2))

You can remove a covariate from the data object:

names(scrdat$covs())
scrdat$remove_covariate("weather")
names(scrdat$covs())

Mesh covariates can be plotted over the mesh:

scrdat$plot_mesh("habitat")

r-glennie/openpopscr documentation built on Oct. 9, 2021, 9:01 p.m.