simDynocc: Simulate detection/nondetection data under a wide variety of...

In AHMbook: Functions and Data for the Book 'Applied Hierarchical Modeling in Ecology' Vols 1 and 2

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)

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.

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

Author(s)

Marc Kéry & Andy Royle

References

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

Examples

# 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)) )

AHMbook documentation built on Sept. 12, 2024, 6:37 a.m.