R: Local evaluation of a Poisson SCR detection process

dpoisLocal_normal {nimbleSCR}

R Documentation

Local evaluation of a Poisson SCR detection process

Description

The dpoisLocal_normal distribution is a NIMBLE custom distribution which can be used to model and simulate Poisson 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 function of the distance between the individual's activity center (s) and the trap location. All coordinates (s and trapCoords) should be scaled to the habitat (see scaleCoordsToHabitatGrid)

Usage

dpoisLocal_normal(
  x,
  detNums = -999,
  detIndices,
  lambda = -999,
  lambdaTraps,
  sigma,
  s,
  trapCoords,
  localTrapsIndices,
  localTrapsNum,
  resizeFactor = 1,
  habitatGrid,
  indicator,
  lengthYCombined = 0,
  log = 0
)

rpoisLocal_normal(
  n = 1,
  detNums = -999,
  detIndices,
  lambda = -999,
  lambdaTraps,
  sigma,
  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 (rpoisLocal_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.
`lambda`	Baseline detection rate used in the half-normal detection function.
`lambdaTraps`	Vector of baseline detection rate for each trap used in the half-normal detection function. When lambdaTraps is used, lambda should not be provided.
`sigma`	Scale parameter of the half-normal 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

The dpoisLocal_normal 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 dpoisLocal_normal distribution requires x- and y- detector coordinates (trapCoords) and activity centers coordinates (s) 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 detection function : p = lambda * exp(-d^2 / 2 \sigma^2).

Author(s)

Cyril Milleret, Soumen Dey

Examples

# 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
lambda <- 0.2
sigma <- 2
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 
dpoisLocal_normal(x=SparseY$y[i,,1],
                   detNums=SparseY$detNums[i],
                   detIndices=SparseY$detIndices[i,,1],
                   lambda = lambda,
                   sigma= sigma, 
                   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
dpoisLocal_normal(x=SparseY$yCombined[i,,1],
                   lambda = lambda,
                   sigma= sigma, 
                   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 
rpoisLocal_normal(n=1,
                   lambda = lambda,
                   sigma= sigma, 
                   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]