simDCM {AHMbook}

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,]