nimbleSCR (version 0.2.1)

dpoisLocal_normal: 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
)

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)\).

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.

Author

Cyril Milleret, Soumen Dey

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):

1. A local evaluation of the detection probability calculation (see Milleret et al., 2019 <doi:10.1002/ece3.4751> for more details)

2. A sparse matrix representation (x, detIndices and detNums) of the observation data to reduce the size of objects to be processed.

3. 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:

1. x should be provided using the yCombined object as returned by getSparseY,

2. arguments detIndices and detNums should not be provided,

3. argument lengthYCombined should be provided using the lengthYCombined object as returned by getSparseY.

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)