getSparseY {nimbleSCR}

Sparse Matrix Preparation

Description

R utility function to turn a two or three-dimensional detection array into a sparse matrix representation (see Turek et al., 2021 <doi.org/10.1002/ecs2.3385> for more details). Used in the implementation of the dbinomLocal_normal and dpoisLocal_normal functions.

Usage

getSparseY(x, noDetections = -1, nMaxTraps = NULL)

Arguments

x

A two- or three-dimensional observation data array with dimensions : number of individuals, number of traps, (and number of detection occasions/sessions).

noDetections

The value indicating no detection. Defaults to -1.

nMaxTraps

The maximum number of traps at which detections can occur. It is necessary to artificially augment the sparse detection array when using the random generation functionality of the rbinomLocal_normal or rpoisLocal_normal functions. When simulating detection data, augmenting the size of the detection array is necessary to avoids artificially limiting the number of detectors at which individuals can be detected. Default value is maxDetNums * 2, which doubles the maximum number of traps at which an individual can be detected. We generally recommend using numLocalIndicesMax obtained from getLocalObjects when aiming at randomly generating detections from rbinomLocal_normal or rpoisLocal_normal.

Details

The getSparseY function is used in advance of model building to create a sparse matrix representation of the observation data. It creates and returns a list of objects:

Value

A list of objects which constitute a sparse representation of the observation data:

• detNums A matrix with number of traps at which each individual (in rows) was detected at each occasions/sessions (in columns).

• maxDetNums The maximum number of traps at which an individual was detected (i.e., the maximum of detNums).

• detIndices An array of dimensions n.individuals, maxDetNums, and number of occasions/sessions, which contains the IDs of the traps where each individual was detected.

• y An array of dimensions n.individuals, maxDetNums, and occasions/sessions, which contains the number of observations of each individual at the traps it was detected at.

• yCombined An array that combines detNums, y, and detIndices by columns (in that specific order). Note that y, and detIndices are augmented before combining, such that the maximum number of detectors at which an individual can be detected is equal to nMaxTraps Consequently, the number of columns of lengthYCombined is 2*nMaxTraps + 1.

• lengthYCombined Dimension of the augmented lengthYCombined object to be specified as the argument lengthYCombined of the dbinomLocal_normal or dpoisLocal_normal functions when simulating detection data.

Author(s)

Cyril Milleret

Examples

y.full <- matrix(rbinom(5000, 5, 0.02), ncol = 100)

y <- getSparseY(y.full)