| Title: | Simulations of Overdispersion in SECR |
|---|---|
| Description: | Code used to simulate overdispersion for paper by Efford and Fletcher. |
| Authors: | Murray Efford [aut, cre] (ORCID: <https://orcid.org/0000-0001-5231-5184>) |
| Maintainer: | Murray Efford <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.0.2 |
| Built: | 2026-05-27 10:47:43 UTC |
| Source: | https://github.com/MurrayEfford/overdispsim |
Code used to simulate overdispersion for paper by Efford and Fletcher.
| Package: | overdispsim |
| Type: | Package |
| Version: | 1.0.2 |
| Date: | 2025-05-19 |
| License: | GNU General Public License Version 2 or later |
Type vignette('Overview', 'overdispsim') to see the overview vignette.
Intended for plot of summary results.
addCL(x, summ, cov = "COV", nrepl = 1000, ...)addCL(x, summ, cov = "COV", nrepl = 1000, ...)
x |
numeric x values |
summ |
dataframe from summary_M etc. |
cov |
character statistic to plot e.g. RB |
nrepl |
integer number of replicates for binomial interval for COV statistic |
... |
other arguments passed to Bucl, Blcl |
A binomial interval is computed for COV. Intervals are otherwise +/- 2SE.
None returned
Expand a single list of arguments using all combinations of values.
extend(baseargs, values)extend(baseargs, values)
baseargs |
list of arguments for |
values |
list of value vectors |
The vectors in 'values' refer to 'details' arguments of sim.popn.
List of argument lists for sim.popn.
localpar <- setparameters() basepopargs3 <- list(D = randomDensity, core = localpar$mask, buffer = 0, model2D = "IHP", details = list(D = localpar$D, p=0.5, A=0.25, rescale=TRUE)) # vary A, p arguments of randomDensity popargs3 <- extend(basepopargs3, values = list(A = c(0.25,0.5), p = c(0.25, 0.5)) ) # view details sapply(popargs3, '[[', 'details')localpar <- setparameters() basepopargs3 <- list(D = randomDensity, core = localpar$mask, buffer = 0, model2D = "IHP", details = list(D = localpar$D, p=0.5, A=0.25, rescale=TRUE)) # vary A, p arguments of randomDensity popargs3 <- extend(basepopargs3, values = list(A = c(0.25,0.5), p = c(0.25, 0.5)) ) # view details sapply(popargs3, '[[', 'details')
Functions to extract summary statistics from each replicate.
Used by run_all in call to run.scenarios.
extract_n(ch, distribution = "poisson") extract_M(fit, chatmin = 1) extract_MCL(fit)extract_n(ch, distribution = "poisson") extract_M(fit, chatmin = 1) extract_MCL(fit)
ch |
secr capthist object |
distribution |
character |
fit |
fitted secr model |
chatmin |
numeric threshold of c-hat for adjustment of variance |
The value of 'distribution' may be set to "binomial" for fixed-N(A).
For extract_n, a numeric vector
| n | number of detected individuals |
| chatnk | Fletcher's c-hat |
| N | number of simulated individuals |
| localD | detection-weighted local density |
For extract_M, a list with components:
| N | number of simulated individuals |
| n | number of detected individuals |
| chatnk | Fletcher's c-hat |
| pred | table of estimates from predict() |
| predF | table of estimates with variance adustment using Fletcher's c-hat |
| predW | table of estimates with variance adustment using Wedderburn c-hat |
| trueD | detection-weighted true density |
For extract_MCL, a list with components:
| N | number of simulated individuals |
| n | number of detected individuals |
| chatnk | Fletcher's c-hat |
| derived | table of estimates from derived() |
| trueD | detection-weighted true density |
A wrapper for commands to plot chat vs the empirical variance/mean ratio for n. A log scale is used for both axes.
plotnsum(nsum, ny = 5, by.y = FALSE, xlim = c(0.75, 120), ylim = xlim, label = "", labelx = 0.15, type = c("Fletcher", "Wedderburn"), ...)plotnsum(nsum, ny = 5, by.y = FALSE, xlim = c(0.75, 120), ylim = xlim, label = "", labelx = 0.15, type = c("Fletcher", "Wedderburn"), ...)
nsum |
matrix output by |
ny |
integer number of levels |
by.y |
logical; see Details |
xlim |
numeric vector of limits on x-axis |
ylim |
numeric vector of limits on y-axis |
label |
character optional label |
labelx |
numeric label offset |
type |
character type of c-hat |
... |
other arguments passed to points() |
Used for text and appendix figures in Efford & Fletcher (2024).
Each column of nsum is of length ny*nx (nx inferred). Internally the columns for 'varration' and 'chatF' (or chatW) are formed into ny x nx matrices. Then lines are plotted either for each column (by.y = TRUE) or each row of these matrices.
none
A wrapper for secrdesign function run.scenarios().
run_all(nrepl, popargs, CH.function = "sim.capthist", detargs = list(savepopn = TRUE), fit = FALSE, distribution = c("poisson", "binomial"), CL = FALSE, start = NULL, byscenario = FALSE, extractfn = NULL, seed = 12345, ...)run_all(nrepl, popargs, CH.function = "sim.capthist", detargs = list(savepopn = TRUE), fit = FALSE, distribution = c("poisson", "binomial"), CL = FALSE, start = NULL, byscenario = FALSE, extractfn = NULL, seed = 12345, ...)
nrepl |
integer number of replicates |
popargs |
list of named arguments to
|
CH.function |
character name of function to simulate capthist |
detargs |
list of named arguments to
|
fit |
logical; model fitted if TRUE |
distribution |
character distribution of n in fitted model ("poisson" or "binomial") |
CL |
logical; if TRUE fitting maximises the conditional likelihood |
start |
'start' argument for secr.fit |
byscenario |
logical (see secrdesign) |
extractfn |
function to extract statistics from each replicate |
seed |
integer random seed |
... |
additional arguments for extractfn |
Arguments generally follow run.scenarios.
The number of threads is determined by .local$maxncores (see code).
By default, 'extractfn' is chosen depending on fit and CL:
| fit | CL | extractfn |
| FALSE | ------- | extract_n |
| TRUE | FALSE | extractfn_M |
| TRUE | TRUE | extractfn_MCL |
See run.scenarios. Depends on extractfn.
Several variables are used by multiple functions and it is tidier to store them in an environment that is internal to the package but shared among functions. This function assigns values to the variables.
setparameters(lambda0 = 0.5, sigma = 1, detectfn = 'HHN', noccasions = 5, traps = make.grid(12, 12, detector = "proximity", spacing = 2), maskspacing = 0.5, maskbuffer = 4, N = 256, maxncores = 18)setparameters(lambda0 = 0.5, sigma = 1, detectfn = 'HHN', noccasions = 5, traps = make.grid(12, 12, detector = "proximity", spacing = 2), maskspacing = 0.5, maskbuffer = 4, N = 256, maxncores = 18)
lambda0 |
numeric detection parameter |
sigma |
numeric detection parameter |
detectfn |
secr |
noccasions |
integer |
traps |
secr traps object |
maskspacing |
numeric spacing of generated mask |
maskbuffer |
numeric buffer width of generated mask |
N |
integer expected population size in masked area |
maxncores |
integer available cores for parallel processing |
A mask is generated. The derived variables 'detectpar', 'D', 'pd' and 'enk' are also computed (see vignette).
setparameters is called by 'on.attach()' and may be called again to replace values.
'maxncores' is capped at the number available, as given by parallel::detectCores().
Invisibly returns the environment as a list with these components (order varies) -
lambda0 |
intercept of HHN detection function |
sigma |
spatial scale of intercept of HHN detection function |
traps |
secr 'traps' object |
detectpar |
list with components lambda0 and sigma* |
N |
population size in mask area |
D |
density* |
mask |
secr 'mask' object* |
maxncores |
maximum number of threads to use |
noccasions |
number of sampling occasions |
detectfn |
secr |
pd |
numeric overall probability of detection of AC at each mask point* |
enk |
numeric vector: expected number of individuals detected at each detector* |
En |
numeric expected number of individuals detected* |
Evarn |
numeric expected variance of binomial n* |
* computed by setparameters(); other values are as input
Simulates detection of a clustered population with cohesion of detection sensu
Bischof et al. (2020). The main use is to replace sim.capthist
in the secrdesign function run.scenarios, as called by
run_all.
sim.cohesion(traps, popn, detectfn = 0, detectpar = list(), noccasions = 5, savepopn = FALSE, gamma = 1, ...)sim.cohesion(traps, popn, detectfn = 0, detectpar = list(), noccasions = 5, savepopn = FALSE, gamma = 1, ...)
traps |
secr traps object |
popn |
popn object output by |
detectfn |
integer or character value for shape of |
detectpar |
list of detection parameter values |
noccasions |
integer number of occasions |
savepopn |
logical passed to |
gamma |
numeric within-cluster cohesion 0-1 (Bischof et al. 2020) |
... |
other arguments passed to |
The argument gamma controls the degree of cohesion.
The popn argument should be a clustered population with saved attributes ‘parents’ and ‘parentid’.
A capthist object.
Bischof, R., Dupont, P., Milleret, C., Chipperfield, J., and Royle, J. A. (2020) Consequences of ignoring group association in spatial capture–recapture analysis. Wildlife Biology wlb.00649. doi:10.2981/wlb.00649
Custom summary functions for output from run_all.
summary_n(sims, binomial = FALSE) summary_M(sims, true = NULL) summary_MCL(sims, true = NULL, truea = 0.0635256)summary_n(sims, binomial = FALSE) summary_M(sims, true = NULL) summary_MCL(sims, true = NULL, truea = 0.0635256)
sims |
output from |
binomial |
logical; if TRUE then expected variance is .local$Evarn |
true |
true density |
truea |
true value of effective sampling area a |
Table with one row per scenario. Columns are defined as follows -
summary_n
| [var, scale etc.] | Parameters specific to the scenarios | |
| varration | Ratio var(n) / mean(n) | |
| chatF | Mean 'Fletcher-chat' for count |
|
| chatW | Mean 'Wedderburn-chat' for count |
|
| Nsim | number of datasets simulated | |
| N | mean number of individuals in simulated population | |
| varN | variance of number of individuals in simulated population | |
| n | mean number of individuals detected | |
| varn | variance of number of individuals detected | |
| localD | mean of detection-weighted density | |
| varlocalD | variance of detection-weighted density | |
| VRlocalD | variance ratio from localD : (varlocalD/localD^2 + 1/En) / (1/En) |
summary_M
| [var, scale etc.] | Parameters specific to the scenarios | |
| n | mean number of individuals detected | |
| N | mean number of individuals in simulated population | |
| nvalid | number of successful simulations | |
| estimate | mean estimated density | |
| SE.estimate | mean SE of estimate | |
| RSE | ratio of preceding | |
| trueD | true density; either detection-weighted (default) or global as specified by the 'true' argument | |
| RB | estimated relative bias relative to trueD | |
| seRB | SE of RB | |
| COV | unadjusted coverage of 95% interval relative to trueD | |
| COVF | adjusted coverage | |
| chatF | mean 'Fletcher-chat' for count |
|
| varration | Ratio var(n) / mean(n) |
summary_MCL
| [var, scale etc.] | Parameters specific to the scenarios | |
| n | mean number of individuals detected | |
| nvalid | number of successful simulations | |
| estimate | mean estimated density | |
| SE.estimate | mean SE of estimate | |
| RSE | ratio of preceding | |
| trueD | true density; either detection-weighted (default) or global as specified by the 'true' argument | |
| RB | estimated relative bias relative to trueD | |
| COV | unadjusted coverage of 95% interval relative to trueD | |
| chatF | mean 'Fletcher-chat' for count |
|
| varration | Ratio var(n) / mean(n) | |
| a | mean a-hat effective sampling area | |
| SEa | SE of a-hat | |
| RBa | RB(a-hat) | |
| RSEa | RSE(a-hat) | |
| COVa | coverage of 95% CI for a-hat | |
| pCVn | fraction of var(D-hat) attributable to var(n) |