R: Local evaluation of a binomial SCR observation process

dbinomLocal_normalPlateau {nimbleSCR}

R Documentation

Local evaluation of a binomial SCR observation process

Description

The dbinomLocal_normalPlateau distribution is a NIMBLE custom distribution which can be used to model and simulate binomial observations (x) of a single individual over a set of traps defined by their coordinates trapCoords the distribution assumes that an individual’s detection probability at any trap follows a half-normal plateau function of the distance between the individual's activity center (s) and the trap location. With the half-normal plateau function, detection probability remains constant with value p0 for a plateau of width w before declining with scale sigma.

Usage

dbinomLocal_normalPlateau(
  x,
  detNums = -999,
  detIndices,
  size,
  p0 = -999,
  p0Traps,
  sigma,
  w = 2,
  s,
  trapCoords,
  localTrapsIndices,
  localTrapsNum,
  resizeFactor = 1,
  habitatGrid,
  indicator,
  lengthYCombined = 0,
  log = 0
)

rbinomLocal_normalPlateau(
  n = 1,
  detNums = -999,
  detIndices,
  size,
  p0 = -999,
  p0Traps,
  sigma,
  w = 2,
  s,
  trapCoords,
  localTrapsIndices,
  localTrapsNum,
  resizeFactor = 1,
  habitatGrid,
  indicator,
  lengthYCombined = 0
)

Arguments

`x`	Vector of individual detection frequencies. This argument can be provided in two formats: (i) with the y object as returned by `getSparseY`; (ii) with the yCombined object as returned by `getSparseY` Note that when the random generation functionality is used (rbinomLocal_normal), only the yCombined format can be used. The yCombined object combines detNums, x, and detIndices (in that order). When such consolidated representation of the detection data x is used, detIndices and detNums arguments should not be specified.
`detNums`	Number of traps with at least one detection recorded in x; from the detNums object returned by the `getSparseY` function. This argument should not be specified when the yCombined object (returned by `getSparseY`) is provided as x and when detection data are simulated.
`detIndices`	Vector of indices of traps where the detections in x were recorded; from the detIndices object returned by the `getSparseY` function. This argument should not be specified when x is provided as the yCombined object (returned by `getSparseY` ) and when detection data are simulated.
`size`	Vector of the number of trials (zero or more) for each trap (trapCoords).
`p0`	Baseline detection probability (scalar) used in the half-normal detection function. For trap-specific baseline detection probabilities use argument p0Traps (vector) instead.
`p0Traps`	Vector of baseline detection probabilities for each trap used in the half-normal detection function. When p0Traps is used, p0 should not be provided.
`sigma`	Scale parameter of the half-normal detection function.
`w`	Length of plateau of the half-normal plateau detection function.
`s`	Individual activity center x- and y-coordinates scaled to the habitat (see (`scaleCoordsToHabitatGrid`).
`trapCoords`	Matrix of x- and y-coordinates of all traps scaled to the habitat (see (`scaleCoordsToHabitatGrid`).
`localTrapsIndices`	Matrix of indices of local traps around each habitat grid cell, as returned by the `getLocalObjects` function.
`localTrapsNum`	Vector of numbers of local traps around all habitat grid cells, as returned by the `getLocalObjects` function.
`resizeFactor`	Aggregation factor used in the `getLocalObjects` function to reduce the number of habitat grid cells to retrieve local traps for.
`habitatGrid`	Matrix of local habitat grid cell indices, from habitatGrid returned by the `getLocalObjects` function.
`indicator`	Binary argument specifying whether the individual is available for detection (indicator = 1) or not (indicator = 0).
`lengthYCombined`	The length of the x argument when the (yCombined) format of the detection data is provided; from the lengthYCombined object returned by `getSparseY`
`log`	Logical argument, specifying whether to return the log-probability of the distribution.
`n`	Integer specifying the number of realizations to generate. Only n = 1 is supported.

Details

All coordinates (s and trapCoords) should be scaled to the habitat (see scaleCoordsToHabitatGrid)

The dbinomLocal_normalPlateau distribution incorporates three features to increase computation efficiency (see Turek et al., 2021 <doi.org/10.1002/ecs2.3385> for more details):

A local evaluation of the detection probability calculation (see Milleret et al., 2019 <doi:10.1002/ece3.4751> for more details)
A sparse matrix representation (x, detIndices and detNums) of the observation data to reduce the size of objects to be processed.
An indicator (indicator) to shortcut calculations for individuals unavailable for detection.

The dbinomLocal_normalPlateau distribution requires x- and y- detector coordinates (trapCoords) to be scaled to the habitat grid (habitatGrid) using the (scaleCoordsToHabitatGrid function.)

When the aim is to simulate detection data:

x should be provided using the yCombined object as returned by getSparseY,
arguments detIndices and detNums should not be provided,
argument lengthYCombined should be provided using the lengthYCombined object as returned by getSparseY.

Value

The log-likelihood value associated with the vector of detections, given the location of the activity center (s), and the half-normal plateau detection function : p = p0 when d < w and p = p0 * exp(-(d-w)^2 / \sigma^2) when d >= w.

Author(s)

Soumen Dey

References

Dey, S., Bischof, R., Dupont, P. P. A., & Milleret, C. (2022). Does the punishment fit the crime? Consequences and diagnosis of misspecified detection functions in Bayesian spatial capture–recapture modeling. Ecology and Evolution, 12, e8600. https://doi.org/10.1002/ece3.8600

Examples

# A user friendly vignette is also available on github: 
# https://github.com/nimble-dev/nimbleSCR/blob/master/nimbleSCR/vignettes/
# Vignette name: Fit_with_dbinomLocal_normalPlateau_and_HomeRangeAreaComputation.rmd

# I. DATA SET UP 
coordsHabitatGridCenter <- matrix(c(0.5, 3.5,
                                    1.5, 3.5,
                                    2.5, 3.5,
                                    3.5, 3.5,
                                    0.5, 2.5,
                                    1.5, 2.5,
                                    2.5, 2.5,
                                    3.5, 2.5,
                                    0.5, 1.5,
                                    1.5, 1.5,
                                    2.5, 1.5,
                                    3.5, 1.5,
                                    0.5, 0.5,
                                    1.5, 0.5,
                                    2.5, 0.5,
                                    3.5, 0.5), ncol=2,byrow = TRUE)
colnames(coordsHabitatGridCenter) <- c("x","y")
# CREATE OBSERVATION WINDOWS
trapCoords <- matrix(c(1.5, 1.5, 2.5, 1.5, 1.5, 2.5, 2.5, 2.5), nrow = 4, byrow = TRUE)
colnames(trapCoords) <- c("x","y")
# PLOT CHECK
plot(coordsHabitatGridCenter[,"y"]~coordsHabitatGridCenter[,"x"],pch=16) 
points(trapCoords[,"y"]~trapCoords[,"x"],col="red",pch=16) 

# PARAMETERS
p0 <- 0.25
sigma <- 1
w <- 1.5
indicator <- 1 
# WE CONSIDER 2 INDIVIDUALS
y <- matrix(c(0, 1, 1, 0,
              0, 1, 0, 1),ncol=4,nrow=2)
s <- matrix(c(0.5, 1,
              1.6, 2.3),ncol=2,nrow=2)

# RESCALE COORDINATES 
ScaledtrapCoords <- scaleCoordsToHabitatGrid(coordsData =  trapCoords,
                                             coordsHabitatGridCenter = coordsHabitatGridCenter)
ScaledtrapCoords<- ScaledtrapCoords$coordsDataScaled
habitatMask <- matrix(1, nrow = 4, ncol=4, byrow = TRUE)


# CREATE LOCAL OBJECTS 
TrapLocal <- getLocalObjects(habitatMask = habitatMask,
                                   coords = ScaledtrapCoords,
                                   dmax=2.5,
                                   resizeFactor = 1,
                                   plot.check = TRUE
)

# GET SPARSE MATRIX 
SparseY <- getSparseY(y)

# II. USING THE DENSITY FUNCTION 
 # WE TAKE THE FIRST INDIVIDUAL
i=1
  # OPTION 1: USING THE RANDOM GENERATION FUNCTIONNALITY 
dbinomLocal_normalPlateau(x=SparseY$y[i,,1],
                   detNums=SparseY$detNums[i],
                   detIndices=SparseY$detIndices[i,,1],
                   size=rep(1,4),
                   p0 = p0,
                   sigma= sigma, 
                   w = w,
                   s=s[i,1:2],
                   trapCoords=ScaledtrapCoords,
                   localTrapsIndices=TrapLocal$localIndices,
                   localTrapsNum=TrapLocal$numLocalIndices,
                   resizeFactor=TrapLocal$resizeFactor,
                   habitatGrid=TrapLocal$habitatGrid,
                   indicator=indicator)
                                                                
  # OPTION 2: USING RANDOM GENERATION FUNCTIONNALITY 
  # WE DO NOT PROVIDE THE detNums AND detIndices ARGUMENTS
dbinomLocal_normalPlateau(x=SparseY$yCombined[i,,1],
                   size=rep(1,4),
                   p0 = p0,
                   sigma= sigma, 
                   w = w,
                   s=s[i,1:2],
                   trapCoords=ScaledtrapCoords,
                   localTrapsIndices=TrapLocal$localIndices,
                   localTrapsNum=TrapLocal$numLocalIndices,
                   resizeFactor=TrapLocal$resizeFactor,
                   habitatGrid=TrapLocal$habitatGrid,
                   indicator=indicator,
                   lengthYCombined = SparseY$lengthYCombined)

# III. USING THE RANDOM GENERATION FUNCTION 
rbinomLocal_normalPlateau(n=1,
                   size=rep(1,4),
                   p0 = p0,
                   sigma= sigma, 
                   w = w,
                   s=s[i,1:2],
                   trapCoords=ScaledtrapCoords,
                   localTrapsIndices=TrapLocal$localIndices,
                   localTrapsNum=TrapLocal$numLocalIndices,
                   resizeFactor=TrapLocal$resizeFactor,
                   habitatGrid=TrapLocal$habitatGrid,
                   indicator=indicator,
                   lengthYCombined = SparseY$lengthYCombined)

[Package nimbleSCR version 0.2.1 Index]