nk: Number per detector

Description

Functions described here compute the observed (nk) or expected (Enk) number of individuals detected at each detector.

The function chat.nk computes an erroneous estimate of the overdispersion of activity centres (Bischof et al. 2020; Efford and Fletcher 2025).

Enk uses exact formulae for 'multi', 'proximity' and 'count' detector types. Other types may be simulated by setting a positive value for 'nrepl', which should be large (e.g., nrepl = 10000).

Usage

nk(capthist)
Enk(D, mask, traps, detectfn = 0, detectpar = list(g0 = 0.2,
    sigma = 25, z = 1), noccasions = NULL, binomN = NULL,
    userdist = NULL, ncores = NULL, nrepl = NULL) 
chat.nk(object, nsim = NULL, ...)

Value

For nk, a vector of observed counts, one for each detector in traps(capthist).

For Enk, a vector of expected counts, one for each detector in traps.

For chat.nk, usually a list comprising --

expected.nk: expected number at each detector
nk: observed number at each detector
stats: vector of summary statistics: mean(expected.nk), var(expected.nk), mean(nk), var(nk), nu (=df), X2/nu
chat: \(\hat c\) (Fletcher or Wedderburn depending on `type')

There are two variations --

If `verbose = FALSE' then only the numeric value of \(\hat c\) is returned (a vector of 2 values if `type = "both"').

If chat.nk is called with `nsim > 0' then the output is a list comprising --

type: from input
nsim: from input
sim.chat: vector of simulated \(\hat c\)
chat: \(\hat c\) (Fletcher or Wedderburn depending on `type')
p: probability of observing \(\hat c\) as large as this (from rank of chat among sim.chat)

Arguments

capthist: secr capthist object
D: numeric density, either scalar or vector of length nrow(mask)
mask: single-session habitat mask
traps: traps object
detectfn: integer code for detection function q.v.
detectpar: a named list giving a value for each parameter of detection function
noccasions: number of sampling intervals (occasions)
binomN: integer code for discrete distribution (see secr.fit)
userdist: user-defined distance function or matrix (see userdist)
ncores: integer number of threads
nrepl: integer number of replicates for E(nk) by simulation (optional)
object: fitted secr model or dataframe (see Warnings for restrictions)
nsim: integer number of c-hat values to simulate (optional)
...: other arguments passed to Fletcher.chat (verbose, type)

Warning

The variance inflation factor given by chat.nk was shown by Efford and Fletcher (2025) to be inadequate and should not be used. For replicate spatial samples, chat.nj is a better alternative.

These functions are experimental and do not work with polygon-like and single-catch detectors. No allowance is made for modelled variation in detection parameters with respect to occasion, detector or animal; this includes mixture models (e.g., g0~h2).

Versions before 4.5.11 did not correctly compute expected counts for multi-catch detectors.

Details

If traps has a usage attribute then noccasions is set accordingly; otherwise it must be provided.

The environment variable RCPP_PARALLEL_NUM_THREADS determines the number of parallel threads. It is set to the value of ncores, unless that is NULL (see setNumThreads).

chat.nk may be used to simulate \(\hat c\) values under the given model (set nsim > 0). The ... argument may include 'ncores = x' (x>1) to specify parallel processing of simulations - the speed up is large on unix-like machines for which the cluster type of makeCluster is "FORK" rather than "PSOCK". If 'ncores' is not provided then the value returned by setNumThreads() is used.

References

Bischof, R., P. Dupont, C. Milleret, J. Chipperfield, and J. A. Royle. 2020. Consequences of ignoring group association in spatial capture--recapture analysis. Wildlife Biology wlb.00649. tools:::Rd_expr_doi("10.2981/wlb.00649")

Efford, M. G. and D. Fletcher. 2025. Effect of spatial overdispersion on confidence intervals for population density estimated by spatial capture-recapture. bioRxiv https://doi.org/10.1101/2024.03.12.584742

Fletcher, D. (2012) Estimating overdispersion when fitting a generalized linear model to sparse data. Biometrika 99, 230--237.

Wedderburn, R. W. M. (1974) Quasi-likelihood functions, generalized linear models, and the Gauss-Newton method. Biometrika 61, 439--47.

Examples

Run this code

# \donttest{
  temptrap <- make.grid()
  msk <- make.mask(temptrap)
  ## expected number of individuals per detector (multi-catch) 
  Enk (D = 5, msk, temptrap, detectpar = list(g0 = 0.2, sigma = 25),
    noccasions = 5)

# }

# useful plotting function for simulated chat (nsim>0)
plotchat <- function(chat, head = '', breaks = seq(0.5,2.5,0.05)) {
    hist(chat$sim.chat, xlim = range(breaks), main = head, xlab = 'c-hat',
        breaks = breaks, cex.main = 1, yaxs = 'i')
    abline(v = chat$chat, lwd = 1.5, col = 'blue')
}

Run the code above in your browser using DataLab