nimbleSCR (version 0.2.1)

dmultiLocal_normal: Local evaluation of a multinomial SCR detection process

Description

The dmultiLocal_normal distribution is a NIMBLE custom distribution which can be used to model and simulate multinomial 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

dmultiLocal_normal(
  x,
  detNums = -999,
  detIndices,
  size,
  p0 = -999,
  p0Traps,
  sigma,
  s,
  trapCoords,
  localTrapsIndices,
  localTrapsNum,
  resizeFactor = 1,
  habitatGrid,
  indicator,
  lengthYCombined = 0,
  log = 0
)
rmultiLocal_normal(
  n = 1,
  detNums = -999,
  detIndices,
  size,
  p0 = -999,
  p0Traps,
  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 = p0 * 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 the getSparseY function; (ii) with the yCombined object as returned by getSparseY. Note that when the random generation functionality is used (rmultiLocal_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

umber 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

Number of occasions.

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.

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

Soumen Dey, Cyril Milleret

Details

The dmultiLocal_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 dmultiLocal_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
p0 <- 0.2
sigma <- 2
indicator <- 1 
# WE CONSIDER 2 INDIVIDUALS

y <- matrix(c(2, 1, 1,-1, 1, 4, -1,#id#1 detected 2 times at detector 1 and 4 
             2, 2,-1,-1, 3,-1, -1),#id#2 detected 2 times at detector 3
              ncol=7, nrow=2, byrow = TRUE)




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 
dmultiLocal_normal(x=y[i,]
                  ,
                  size=3
                  ,
                  p0 = p0
                  ,
                  sigma= sigma
                  , 
                  s=s[i,1:2]
                  ,
                  trapCoords=ScaledtrapCoords
                  ,
                  localTrapsIndices=TrapLocal$localIndices
                  ,
                  localTrapsNum=TrapLocal$numLocalIndices
                  ,
                  resizeFactor=TrapLocal$resizeFactor
                  ,
                  habitatGrid=TrapLocal$habitatGrid
                  ,
                  indicator=indicator
                  ,
                  lengthYCombined = ncol(y)
                  )
                                                               
 

# III. USING THE RANDOM GENERATION FUNCTION 
rmultiLocal_normal(n=1,
                  size=3,
                  p0 = p0,
                  sigma= sigma, 
                  s=s[i,1:2],
                  trapCoords=ScaledtrapCoords,
                  localTrapsIndices=TrapLocal$localIndices,
                  localTrapsNum=TrapLocal$numLocalIndices,
                  resizeFactor=TrapLocal$resizeFactor,
                  habitatGrid=TrapLocal$habitatGrid,
                  indicator=indicator,
                  lengthYCombined = ncol(y))