msocc_sim: Simulate data from a multi-scale occupancy model.

In StrattonCh/msocc: Package for Fitting and Analyzing Computationally Efficient Multi-scale Occupancy Models

Description

This function simulates data from the multi-scale occupancy model described by Dorazio and Erickson (2017). Note that this documentation assumes there are M sites, J_i samples within each site, and K_{ij} replicates from each sample.

Usage

msocc_sim(
  M = 10,
  J = 5,
  K = 5,
  psi = 0.8,
  theta = 0.75,
  p = 0.9,
  seed = NULL,
  site.df = NULL,
  site.mod = NULL,
  beta = NULL,
  sample.df = NULL,
  sample.mod = NULL,
  alpha = NULL,
  rep.df = NULL,
  rep.mod = NULL,
  delta = NULL
)

Arguments

M	integer; number of sites to simulate
J	may be either an integer or vector of length M representing the number of samples taken from each site. In the former case, J is set to rep(J, M).
K	may be either an integer or vector of length sum(J) representing the number of replicates taken from each sample. In the former case, K is set to rep(K, sum(J)).
psi	may be either a single numeric value in (0,1) representing the constant probability of presence at every site or a vector of length M representing the probability of presence at each site.
theta	may be either a single numeric value in (0,1) representing the constant probability of occurence in every sample or a vector of length sum(J) representing the probability of occurence in each sample.
p	may be either a single numeric value in (0,1) representing the constant probability of detection in every replicate or a vector of length sum(K) representing the probability of detection in each replicate.
seed	optional seed for reproducibility
site.df	optional data.frame used to create the model matrix implied by site.mod if psi is a function of covariates. This data.frame must have M rows and include a column named 'site'. If specified, site.mod and beta must also be specified.
site.mod	optional model statement to produce psi when it is a function of covariates. If specified, site.df and beta must also be specified.
beta	optional vector of parameters use to calculate psi when it is modeled with covariates. It must have length equal to the number of columns in the model matrix implied by site.mod.
sample.df	optional data.frame used to create the model matrix implied by sample.mod if theta is a function of covariates. This data.frame must have sum(J) rows and include columns named 'site' and 'sample'. If specified, sample.mod and alpha must also be specified.
sample.mod	optional model statement to produce theta when it is a function of covariates. If specified, sample.df and alpha must also be specified.
alpha	optional vector of parameters use to calculate theta when it is modeled with covariates. It must have length equal to the number of columns in the model matrix implied by sample.mod.
rep.df	optional data.frame used to create the model matrix implied by rep.mod if p is a function of covariates. This data.frame must have either sum(J) rows (if the covariates used to model p are aggregated at the sample level) or sum(K) rows (if the covariates used to model p are at the individual replicate level). In the former case, it must include columns named 'site' and 'sample'; in the latter case, it must include columns named 'site', 'sample', and 'rep'. If specified, rep.mod and delta must also be specified.
rep.mod	optional model statement to produce p when it is a function of covariates. If specified, rep.df and delta must also be specified.
delta	optional vector of parameters use to calculate p when it is modeled with covariates. It must have length equal to the number of columns in the model matrix implied by rep.mod.

Details

This function supports both balanced an unbalanced designs as well as constant probabilities or those modeled by covariates. For unbalanced designs, J should be specified as a vector of length M representing the samples taken from each site. Similarly, K should be specified as a vector of length sum(J) representing the number of replicates taken from each sample. For balanced designs, each of M, J, and K should be specified as integers. Any combination of balance or imbalance is accepted at all three levels.
For constant probability at any level, specify psi, theta, or p appropriately. Alternatively, the data frame, model and appropriate parameter vector must be supplied to model a probability by covariates. See the examples for more detail.

Value

an object of class list containing the following elements:

• resp a data.frame with sum(J) rows containing columns 'site', 'sample', prc1, ...
  

• site a data.frame with M rows containing a column named 'site' and any site level covariates (if applicable)
  

• sample a data.frame with sum(J) rows containing columns 'site' and 'sample' and any sample level covariates (if applicable)
  

• rep a data.frame with sum(K) rows containing columns 'site', 'sample', and 'rep' and any rep level covariates (if applicable)
  

• params a list containing the following elements:
  

  • psi site level presence probabilities

  • theta sample level occurence probabilities

  • p replicate level detection probabilities

  • z vector of latent variables of length M denoting presence at the site

  • a vector of latent variables of length sum(J) denoting occurence in the sample

  • z.vec vector of latent variables of length sum(J) denoting site level presence stretch across samples

• beta matrix of regression coefficients used to generate psi if

• alpha matrix of regression coefficients used to generate theta if

• delta matrix of regression coefficients used to generate p if

Examples

# constant psi, theta, p
sim <- msocc_sim(M = 10, J = 5, K = 5)
mod <- msocc_mod(wide_data = sim$resp,
                 site = list(model = ~1, cov_tbl = sim$site),
                 sample = list(model = ~1, cov_tbl = sim$sample),
                 rep = list(model = ~1, cov_tbl = sim$rep),
                 progress = F)
posterior_summary(mod)
cred_plot(mod, truth = sim$params$psi)
cred_plot(mod, level = 'sample', truth = sim$params$theta)
cred_plot(mod, level = "rep", truth = sim$params$p)

# psi function of covariates, constant theta and p
sim <- msocc_sim(M = 50, J = 5, K = 5,
                 site.df = data.frame(site = 1:50, x = rnorm(50)),
                 site.mod = ~x,
                 beta = c(1,1))
mod <- msocc_mod(wide_data = sim$resp,
                 site = list(model = ~x, cov_tbl = sim$site),
                 sample = list(model = ~1, cov_tbl = sim$sample),
                 rep = list(model = ~1, cov_tbl = sim$rep),
                 progress = F)
posterior_summary(mod)
cred_plot(mod, truth = sim$params$psi)
cred_plot(mod, level = 'sample',truth = sim$params$theta, n = 10)
cred_plot(mod, level = "rep", truth = sim$params$p, n = 10)

# psi constant, theta function of covariates, p constant
sim <- msocc_sim(M = 10, J = 20, K = 5,
                 sample.df = data.frame(site = rep(1:10, each = 20),
                                        sample = rep(1:20, 10),
                                        x = rnorm(200)),
                 sample.mod = ~x,
                 alpha = c(1,1))
mod <- msocc_mod(wide_data = sim$resp,
                 site = list(model = ~1, cov_tbl = sim$site),
                 sample = list(model = ~x, cov_tbl = sim$sample),
                 rep = list(model = ~1, cov_tbl = sim$rep),
                 progress = F)
posterior_summary(mod)
cred_plot(mod, level = 'site', truth = sim$params$psi)
cred_plot(mod, level = 'sample', truth = sim$params$theta, n = 20)
cred_plot(mod, level = 'rep', truth = sim$params$p)

# psi constant, theta constant, p function of covariates at sample level
rep.df <- data.frame(
  site = rep(1:10, each = 5),
  sample = rep(1:5, 10),
  x = rnorm(50)
)
sim <- msocc_sim(M = 10, J = 5, K = 10,
                 rep.df = rep.df,
                 rep.mod = ~x,
                 delta = c(1,1))
mod <- msocc_mod(wide_data = sim$resp,
                 site = list(model = ~1, cov_tbl = sim$site),
                 sample = list(model = ~1, cov_tbl = sim$sample),
                 rep = list(model = ~x, cov_tbl = sim$rep), beta_bin = T, progress = F)
posterior_summary(mod)
cred_plot(mod, level = 'site', truth = sim$params$psi)
cred_plot(mod, level = 'sample', truth = sim$params$theta)
cred_plot(mod, level = 'rep', n = 25, truth = unique(sim$params$p))

# constant psi, theta, and p - unbalanced at sample level
sim <- msocc_sim(M = 10, J = sample(c(4:5), 10, replace = T), K = 5)
mod <- msocc_mod(wide_data = sim$resp,
                 site = list(model = ~1, cov_tbl = sim$site),
                 sample = list(model = ~1, cov_tbl = sim$sample),
                 rep = list(model = ~1, cov_tbl = sim$rep),
                 progress = F)
posterior_summary(mod)
cred_plot(mod, truth = sim$params$psi)
cred_plot(mod, level = 'sample', truth = sim$params$theta)
cred_plot(mod, level = "rep", truth = sim$params$p)

# constant psi, theta, and p - unbalanced at sample and rep level
num.sites <- 10
num.samples <- sample(c(4:5), num.sites, replace = T)
num.reps <- sample(c(5:8), sum(num.samples), replace = T)

sim <- msocc_sim(M = num.sites, J = num.samples, K = num.reps)
mod <- msocc_mod(wide_data = sim$resp,
                 site = list(model = ~1, cov_tbl = sim$site),
                 sample = list(model = ~1, cov_tbl = sim$sample),
                 rep = list(model = ~1, cov_tbl = sim$rep),
                 progress = F)
posterior_summary(mod)
cred_plot(mod, truth = sim$params$psi)
cred_plot(mod, level = 'sample', truth = sim$params$theta)
cred_plot(mod, level = "rep", truth = sim$params$p)

StrattonCh/msocc documentation built on Dec. 22, 2020, 2:51 a.m.