# Simulate detection/nondetection data under a wide variety of non-spatial dynamic occupancy models 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!) UTF-8 ```r 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. ## Returns 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 ## References Kéry, M. & Royle, J.A. (2021) **Applied Hierarchical Modeling in Ecology** AHM2 - 4. ## Author(s) Marc Kéry & Andy Royle ## Examples ```r # 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)) ) ```

simDynocc function