simDCM: Simulate detection/nondetection data under a general dynamic...

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

Simulate detection/nondetection data under a general dynamic community (site-occupancy) model

Description

Function to simulate detection/nondetection data under a general dynamic community (= dynamic, multi-species site-occupancy) model, including:

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

* species heterogeneity around the community means is specified by the SD of a normal distribution and expressed on the logit scale

* one covariate is allowed per parameter (site covariate for psi1, site-year covariate for phi and gamma and site-year-rep covariate for p). Each covariate is allowed to differ among species again according to a logit-normal model of heterogeneity.

* additional detection heterogeneity at the site- or the occasion level, with the possibility of a temporal trend in this heterogeneity over years. E.g., an annual trend in detection heterogeneity at the site or the occasion level is specified by the value 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-level heterogeneity in detection from 0 in the first year to 1 in the last year, with interpolation for the years in between.

* additional detection heterogeneity that among occasions according to a quadratic effect of occasion number (to model the typical 'phenological curve' of an insect species for instance).

These last two types of detection heterogeneity are not (yet) allowed to be species-specific.

Usage

simDCM(nspecies = 50, nsites = 100, nsurveys = 3, nyears = 10,
  mean.psi1 = 0.4, sig.lpsi1 = 1, mu.beta.lpsi1 = 0, sig.beta.lpsi1 = 0,
  range.mean.phi = c(0.8, 0.8), sig.lphi = 1, mu.beta.lphi = 0,
  sig.beta.lphi = 0, range.mean.gamma = c(0.2, 0.2), sig.lgamma = 1,
  mu.beta.lgamma = 0, sig.beta.lgamma = 0, range.mean.p = c(0.5, 0.5),
  sig.lp = 1, mu.beta.lp = 0, sig.beta.lp = 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), show.plot = TRUE, verbose = TRUE)

Arguments

nspecies	number of species (typically called N in AHM book)
nsites	number of sites (M).
nsurveys	number of replicate surveys within a year (J).
nyears	number of years (T).
mean.psi1	average (across all species in the community) of the intercept of occupancy probability in first year.
sig.lpsi1	sd of the normal distribution from which species-specific occupancy intercepts are drawn (centered on logit(mean.psi1)), on logit scale.
mu.beta.lpsi1	community mean of the coefficients of the covariate in probabilities of initial occupancy: the probability-scale mean of the normal distribution from which the species-specific coefficients are drawn.
sig.beta.lpsi1	sd of the normal distribution from which species-specific slopes are drawn (centered on mu.beta.lpsi1).
range.mean.phi	bounds of uniform distribution from which the average (across species) annual intercept of persistence is drawn.
sig.lphi	sd of the normal distribution from which species-specific persistence intercepts are drawn (centered on logit(mean.phi), which are year-specific), on logit scale.
mu.beta.lphi	community mean of the coefficients of the covariate in probabilities of persistence: the probability-scale mean of the normal distribution from which the species-specific coefficients are drawn.
sig.beta.lphi	sd of the normal distribution from which species-specific persistence slopes are drawn (centered on mu.beta.lphi).
range.mean.gamma	bounds of uniform distribution from which the average (across species) annual intercept of colonization is drawn.
sig.lgamma	sd of the normal distribution from which species-specific colonization intercepts are drawn (centered on logit(mean.gamma), which are year-specific), on logit scale.
mu.beta.lgamma	community mean of the coefficients of the covariate in probabilities of colonization: the probability-scale mean of the normal distribution from which the species-specific coefficients are drawn.
sig.beta.lgamma	sd of the normal distribution from which species-specific colonization slopes are drawn (centered on mu.beta.lgamma).
range.mean.p	bounds of uniform distribution from which the average (across species) annual intercept of p is drawn.
sig.lp	sd of the normal distribution from which species-specific detection intercepts are drawn (centered on logit(mean.p), which are year-specific), on logit scale.
mu.beta.lp	community mean of the coefficients of the covariate in probabilities of detection: the probability-scale mean of the normal distribution from which the species-specific coefficients are drawn.
sig.beta.lp	sd of the normal distribution from which species-specific detection slopes are drawn (centered on mu.beta.lp).
range.beta1.survey	the range of the annual variation in the linear effect of survey (i.e., of surveys 1-12 if nsurveys = 12) on the product of availability and detection.
range.beta2.survey	the range of the annual variation in the quadratic effect of survey (i.e., of surveys 1-12 if nsurveys = 12) on the product of availability and detection.
trend.sd.site	sd of normal distribution to model logit-normal noise in p at the site level in the first and the last year of the simulation, with values for intermediate years interpolated linearly.
trend.sd.survey	sd of normal distribution to model logit-normal noise in p at the occasion level, in the first and the last year, with values for intermediate years interpolated linearly.
show.plot	if TRUE, plots are produced. Set this to FALSE when running simulations.
verbose	if TRUE, output will be written to the console.

Value

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

Xpsi1	Site covariate for psi1, a nsites x 1 matrix
Xphi	Yearly-site covariate for phi, a nsites x nyears matrix
Xgamma	Yearly-site covariate for gamma, a nsites x nyears matrix
Xp	Observation covariate for p, a nsites x nsurveys x nyears array
beta0.lpsi	initial (logit-scale) occupancy intercept for each species in the community, a vector of length nspecies
beta1.lpsi	initial (log-scale) occupancy slope on Xpsi1 for each species in the community, a vector of length nspecies
psi	occupancy probability per site, year and species, a nsites x nyears x nspecies array
mean.phi	mean persistence (across species) intercept for each interval, a vector of length (nyears - 1)
mean.gamma	mean colonization (across species) intercept for each interval, a vector of length (nyears - 1)
eps.lphi	additive species effects in logit(phi) intercept, a vector of length nspecies
eps.lgamma	additive species effects in logit(gamma) intercept, a vector of length nspecies
beta0.lphi	logit-scale persistence intercepts for each species in community, a nspecies x (nyears - 1) matrix
beta0.lgamma	logit scale colonization intercepts for each species in the community, a nspecies x (nyears - 1) matrix
beta1.lphi	slope of logit(phi) on Xphi for each species in the community, a vector of length nspecies
beta1.lgamma	slope of logit(gamma) on Xgamma for each species in the community, a vector of length nspecies
phi	probability of persistence for each site, yearly interval and species, a nsites x (nyears-1) x nspecies array
gamma	probability of colonization for each site, yearly interval and species, a nsites x (nyears-1) x nspecies array
mean.p	mean detection (across species) intercept for each year, a vector of length nyears
eps.lp	additive species effects in logit(p) intercept, a vector of length nspecies
beta0.lp	species- and site-specific intercepts in the linear predictor for p, a nspecies x nyears matrix
beta1.lp	species specific slopes of logit(p) on Xp, a vector of length nspecies
beta1	linear effect of the occasion number on detection probability, a vector of length nyears
beta2	quadratic effect of the occasion number on detection probability, a vector of length nyears
sd.site	standard deviation of the zero-mean normal distribution from which additional, site-level detection heterogeneity is simulated, a vector of length nyears
sd.survey	standard deviation of the zero-mean normal distribution from which additional, occasion-level detection heterogeneity is simulated,, a vector of length nyears
eps1	additive site random effects tht generate unstructured site-level detection heterogeneity, a vector of length nsites
eps2	additive occasion random effects tht generate unstructured site-level detection heterogeneity, a vector of length nsurveys
n.occ	Number of occupied sites, a nyears x nspecies matrix
psi.fs	Finite-sample occupancy proportion, a nyears x nspecies matrix
mean.psi	Average psi over sites, a nyears x nspecies matrix
z.obs	Observed value of z matrix, a nsites x nyears x nspecies array
n.occ.obs	Observed number of occupied sites, a nyears x nspecies matrix
psi.obs	Observed occupancy (finite sample), a nyears x nspecies matrix
nyears.pres	Number of years when species present, a vector of length nspecies
nspecies.pres	Number of species ever present, scalar
nyears.det	Number of years when species detected, a vector of length nspecies
nspecies.det	Number of species ever detected, scalar
z	True value of z matrix (ie, presence/absence), a nsites x nyears x nspecies array
p	Probability of detection, a nsites x nsurveys x nyears x nspecies array
y	Observed detection history, a nsites x nsurveys x nyears x nspecies array of 0/1

Author(s)

Marc Kéry & Andy Royle

References

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

Examples

# Simulate a data set with the default arguments and look at the structure of the output:
tmp <- simDCM()
str(tmp)


# Default arguments, without plots
str(data <- simDCM(show.plot = FALSE))
# More examples:
str(data <- simDCM(nspecies = 200)) # More species (looks great)
str(data <- simDCM(nspecies = 1))   # A single species (ha, works !)
str(data <- simDCM(nsites = 267))   # More sites
str(data <- simDCM(nsites = 1))     # A single site
str(data <- simDCM(nsurveys = 10))  # More visits
str(data <- simDCM(nyears = 25))    # More years
str(data <- simDCM(nyears = 2))     # Just two years
try(data <- simDCM(nyears = 1))     # A single year ... error

# No species heterogeneity in parameters of initial occupancy
str(data <- simDCM(sig.lpsi1 = 0, sig.beta.lpsi1 = 0))
# No species heterogeneity in parameters of persistence
str(data <- simDCM(sig.lphi = 0, sig.beta.lphi = 0))
# No species heterogeneity in parameters of colonisation
str(data <- simDCM(sig.lgamma = 0, sig.beta.lgamma = 0))
# No species heterogeneity in parameters of detection
str(data <- simDCM(sig.lp = 0, sig.beta.lp = 0))
# No annual variation in rates
str(data <- simDCM(range.mean.phi = c(0.8, 0.8), range.mean.gamma = c(0.3, 0.3),
  range.mean.p = c(0.6, 0.6)))

# Function arguments that lead to much structure (no zero arguments)
str(data <- simDCM(nspecies = 200, nsites = 267, nsurveys = 3, nyears = 25,
  mean.psi1 = 0.4, sig.lpsi1 = 3, mu.beta.lpsi1 = 1, sig.beta.lpsi1 = 3,
  range.mean.phi = c(0.5, 1), sig.lphi = 3, mu.beta.lphi = 1,
  sig.beta.lphi = 3, range.mean.gamma = c(0, 0.5),
  sig.lgamma = 3, mu.beta.lgamma = -1, sig.beta.lgamma = 3,
  range.mean.p = c(0.1, 0.9), sig.lp = 3, mu.beta.lp = 1, sig.beta.lp = 3,
  range.beta1.survey = c(-2, -0.5), range.beta2.survey = c(0, 2),
  trend.sd.site = c(0, 0), trend.sd.survey = c(0, 0), show.plot = TRUE))

# Not every occurring species will be detected
set.seed(1)
str(data <- simDCM(nspecies = 200, nsites = 20, nsurveys = 2, nyears = 10,
  mean.psi1 = 0.1, sig.lpsi1 = 5,
  range.mean.phi = c(0.3, 0.3), sig.lphi = 5,
  range.mean.gamma = c(0.1, 0.1), sig.lgamma = 5,
  range.mean.p = c(0.1, 0.1), sig.lp = 5) )

# Pull out data from species 5
ysp5 <- data$y[,,,5]

# Pull out data from year 1
yyr1 <- data$y[,,1,]

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