simDynocc: Simulate detection/nondetection data under a wide variety of non-spatial dynamic occupancy models

Description

Function to simulate detection/nondetection data under a general dynamic site-occupancy model, including:

* Annual variation in the probabilities of patch persistence, colonization and detection is specified by the bounds of a uniform distribution.

* One covariate is allowed to affect each parameter: a site covariate for psi1, site-by-year covariates for phi and gamma, and an observational covariate for p. Covariates are generated internally from uniform(-2, 2) distributions.

* Additional heterogeneity among sites in persistence and colonization or both.

* Additional detection heterogeneity at the site-, the survey, or the site-by-survey level, with the possibility of a temporal trend in this heterogeneity over the years. E.g., an annual trend in detection heterogeneity at the site or the survey level is specified by the first and second value, which correspond to the heterogeneity in the first and the last year. Hence, trend.sd.site = c(0, 1) will result in a linear trend in the magnitude of site heterogeneity in detection from 0 in the first year to 1 in the last year.

* Additional detection heterogeneity that varies over the survey (= occasion) according to a quadratic effect of occasion number (to model the typical phenology of an insect species for instance).

* Simulation of data under a BACI (before-after-control-impact) design, where some event happens in a given year and reduces phi or gamma by a stated percentage (only reductions, no increases allowed!)

Usage

simDynocc(nsites = 250, nyears = 10, nsurveys = 3, year.of.impact = NA,
  mean.psi1 = 0.4, beta.Xpsi1 = 0,
  range.phi = c(0.5, 1), sd.lphi.site = 0, impact.phi = 0, beta.Xphi = 0,
  range.gamma = c(0, 0.5), sd.lgamma.site = 0, impact.gamma = 0, beta.Xgamma = 0,
  sd.lphi.lgamma.site = 0,
  range.p = c(0.1, 0.9), beta.Xp = 0,
  range.beta1.survey = c(0, 0), range.beta2.survey = c(0, 0),
  trend.sd.site = c(0, 0), trend.sd.survey = c(0, 0),
  trend.sd.site.survey = c(0, 0), show.plots = TRUE)

Value

A list with the values of the arguments input and the following additional elements:

impact: a 0/1 vector of length (nyears-1) indicating if an impact applies to the interval
BACI.effect.phi: reduction in persistence due to impact, a vector of length nyears - 1
BACI.effect.gamma: reduction in colonization due to impact, a vector of length nyears - 1
beta1: linear effect of occasion on the product of availability and detection, a vector of length nyears
beta2: quadratic effect of occasion on the product of availability and detection, a vector of length nyears
mean.phi: mean persistence for each interval before application of any BACI effect, a vector of length nyears - 1
mean.gamma: mean colonization for each interval before application of any BACI effect, a vector of length nyears - 1
mean.p: mean detection probability for each year, a vector of length nyears
psi: annual occupancy for each site, a nsites x nyears matrix
mean.psi: average occupancy over sites, a vector of length nyears
n.occ: number of occupied sites, a vector of length nyears
psi.fs: finite-sample occupancy proportion, a vector of length nyears
psi.app: apparent occupancy over sites, a vector of length nyears
z: true occurrence state, a nsites x nyears matrix of 0/1
phi: persistence, a nsites x nyears-1 matrix
gamma: colonization, a nsites x nyears-1 matrix
p: detection probability, a nsites x nsurveys x nyears array
y: the observed detection history, a nsites x nsurveys x nyears array
Xpsi1: covariate affecting initial occupancy, a vector of length nsites
Xphi: covariate affecting persistence, a nsites x nyears matrix
Xgamma: covariate affecting colonization, a nsites x nyears matrix
Xp: covariate affecting probability of detection, a nsites x nsurveys x nyears array
eps.lphi.site: site random effects on persistence, a vector of length nsites
eps.lgamma.site: site random effects on colonization, a vector of length nsites
eps.lphi.lgamma.site: site random effects on persistence and colonization, a vector of length nsites
eps1: site random effects on detection, a vector of length nsites
eps2: the survey random effects on detection, a vector of length nsurveys
eps3: the site/survey/year random effects on detection, a nsites x nsurveys x nyears array

Arguments

nsites: Number of sites.
nyears: Number of years (or 'seasons').
nsurveys: Number of replicate surveys (= occasions) within a year.
year.of.impact: Year in which an impact happens that can affect phi and gamma (for BACI design), NA if no impact occurs; for the BACI design, nyears must be greater than 2, and year of impact cannot be the first or last year.
mean.psi1: average occupancy probability in first year.
beta.Xpsi1: coefficient of environmental covariate in probability of initial occupancy.
range.phi: bounds of uniform distribution from which annual probability of persistence is randomly drawn.
sd.lphi.site: SD of random site effect on persistence on the logit scale drawn from a normal distribution with mean zero.
impact.phi: negative effect in percent on annual phi (e.g., impact.phi = 20 means a 20% reduction in phi); ignored if year.of.impact = NA.
beta.Xphi: coefficients of environmental covariate in probability of persistence.
range.gamma: bounds of uniform distribution from which annual probability of colonization is randomly drawn.
sd.lgamma.site: SD of random site effect on colonization on the logit scale drawn from a normal distribution with mean zero.
impact.gamma: negative effect in percent on annual gamma (e.g., impact.gamma = 20 means a 20% reduction in gamma); ignored if year.of.impact = NA.
beta.Xgamma: coefficient of environmental covariate in probability of colonization.
sd.lphi.lgamma.site: SD of random site effect on persistence AND colonization on the logit scale drawn from a normal distribution with mean zero.
range.p: bounds of uniform distribution from which annual probability of detection is randomly drawn.
beta.Xp: coefficients of environmental covariate in probability of detection.
range.beta1.survey: bounds of the uniform distribution from which the annual variation in the linear effect of the survey occasion (i.e., of survey 1-12 with nsurveys = 12) on detection (= product of availability and perceptibility) is randomly drawn.
range.beta2.survey: the same for the quadratic effect of survey occasion.
trend.sd.site: initial and final values of sd of normal distribution to model logit-normal noise in p at the site level; a linear trend is assumed over time; if the two values are the same, a constant value is assumed.
trend.sd.survey: initial and final values of sd of normal distribution to model logit-normal noise in p only at the 'survey' level; if they are different, a linear trend is assumed over time.
trend.sd.site.survey: initial and final values of sd of normal distribution to model logit-normal noise in p at the site/year/survey = ‘survey’ level; if they are different, a linear trend is assumed over time.
show.plots: If TRUE, plots of results are displayed; set to FALSE if running simulations.

Author

Marc Kéry & Andy Royle

References

Kéry, M. & Royle, J.A. (2021) Applied Hierarchical Modeling in Ecology AHM2 - 4.

Examples

Run this code

# Generate data with the default arguments and look at the structure
tmp <- simDynocc()
str(tmp)

# no annual variation in the parameters
str(data <- simDynocc(nsites = 250, nsurveys = 3, nyears = 10, mean.psi1 = 0.6,
    range.phi = c(0.7, 0.7), range.gamma = c(0.3, 0.3), range.p = c(0.5, 0.5)))
# a fully time-dependent model (with p constant within each primary period)
str(data <- simDynocc(mean.psi1 = 0.6, range.phi = c(0.5, 0.8),
   range.gamma = c(0.1, 0.5), range.p = c(0.1, 0.9)) )
# a time-constant model with four different covariates affecting the four parameters
str(data <- simDynocc(mean.psi1 = 0.6, beta.Xpsi1 = 1,
  range.phi = c(0.6, 0.6), beta.Xphi = 2, range.gamma = c(0.3, 0.3),
  beta.Xgamma = 2, range.p = c(0.2, 0.2), beta.Xp = -2) )
# seasonal variation in detection probability
str(data <- simDynocc(nsurveys = 12, mean.psi1 = 0.6,
  range.phi = c(0.6, 0.6), range.gamma = c(0.3, 0.3),
  range.p = c(0.5, 0.5), range.beta1.survey = c(-0.3, 0.4),
  range.beta2.survey = c(0, -0.7)) )
# now both yearly variation and effects of all covariates (including survey)
str( data <- simDynocc(mean.psi1 = 0.6, beta.Xpsi1 = 1,
   range.phi = c(0.6, 1), beta.Xphi = 2, range.gamma = c(0, 0.2),
   beta.Xgamma = 2, range.p = c(0.1, 0.9), beta.Xp = -2,
   range.beta1.survey = c(-0.4, 0.5), range.beta2.survey = c(0, -0.8)) )

# To add detection heterogeneity at the site level, you can do this:
str(data <- simDynocc(trend.sd.site = c(3, 3)) ) # No time trend
str(data <- simDynocc(trend.sd.site = c(1, 3)) ) # With time trend

# To add detection heterogeneity at the level of the survey, you can do this:
str(data <- simDynocc(trend.sd.survey = c(3, 3)) ) # No time trend
str(data <- simDynocc(trend.sd.survey = c(1, 3)) ) # With time trend

# To add detection heterogeneity at the level of the individual visit, you can do this:
str(data <- simDynocc(trend.sd.site.survey = c(3, 3)) ) # No trend
str(data <- simDynocc(trend.sd.site.survey = c(1, 3)) ) # With trend

# To simulate data under a BACI design, where an impact happens in year 10
str(data <- simDynocc(nsites = 250, nsurveys = 3, nyears = 20, year.of.impact = 10,
   impact.phi = 80, impact.gamma = 50) )

# And data where there is no detection error (i.e., with p = 1):
str( data <- simDynocc(range.p = c(1, 1)) )

Run the code above in your browser using DataLab