Generate a simulated dataset

Simulate cetacean responses to Navy sonar exposure, as in behavioural response studies (BRSs).

simulate_data(
  biphasic = FALSE,
  n.species = 2,
  n.whales = 20,
  min.trials = 1,
  max.trials = 3,
  covariates = NULL,
  mu = NULL,
  phi = NULL,
  sigma = NULL,
  nu = NULL,
  tau = NULL,
  psi = 0.5,
  omega = 1,
  alpha = NULL,
  Npriors = c(0, 30),
  dose.range = c(60, 215),
  Lc = c(65, 75),
  Rc = c(190, 195),
  obs.sd = 2.5,
  verbose = TRUE,
  seed = NULL
)

Arguments

biphasic	Logical. If TRUE, will simulate data from a biphasic dose-response functional form.
n.species	Number of species.
n.whales	Number of individuals. Can be specified as a vector of length n.species, allowing for uneven samples sizes across species, or as an integer multiple of n.species for equal sample sizes across species.
min.trials	Minimum number of exposures per individual. Each animal is exposed x times, with x taken as a random draw from a discrete Uniform distribution bounded by min.trials and max.trials.
max.trials	Maximum number of exposures per individual.
covariates	Contextual covariates and their associated coefficients. Must be supplied as a named list, in which the baseline levels of factor covariates are given a coefficient of zero.
mu	Mean response threshold(s) for each species.
phi	Between-whale variance in response thresholds.
sigma	Within-whale between-exposure variance in response thresholds.
nu	Mean response thresholds from the context-dependent and dose-dependent mixtures in a biphasic model. Must be a list of length n.species, where each element is a vector of length two.
tau	Scale parameters associated with nu. Must be a vector of length two.
psi	Probability of exhibiting a context-dependent response, expressed on a probit scale.
omega	Variance in psi.
alpha	Upper bound on the context-dependent response threshold, which corresponds to the lower bound of the dose-dependent threshold. Must be a vector of length n.species.
Npriors	Vector of length two, giving the mean and SD of the Normal priors placed on covariates.
dose.range	Bounds for the dose-response function. Must be a vector of length 2. Defaults to: (1) a lower bound of 60 dB re 1μPa, taken as a conservative lower limit of detectability given hearing sensitivity and the lowest average sea noise conditions; and (2) an upper bound of 215 dB re 1μPa at/above which all animals are expected to respond. This upper bound is consistent with the maximum source levels employed in behavioural response studies (BRSs) to date.
Lc	Left-censoring interval. Values of the minimum realised dose for each exposure are generated as random draws from a Uniform distribution within the bounds defined by `Lc.
Rc	Right-censoring interval. Values of the maximum realised dose for each exposure are generated as random draws from a Uniform distribution within the bounds defined by `Rc.
obs.sd	Measurement uncertainty (expressed as a standard deviation in received levels), in dB re 1μPa.
verbose	Logical. Whether to print or suppress warning messages.
seed	Random seed (for reproducible results).

Value

A list object of class brsdata, with the following elements:

dat	Output dataset, after processing.
species	Species data, including species names, groups, sample sizes etc.
whales	Individual data, including animal IDs.
trials	Exposure data, including exposure IDs.
covariates	Covariate data, including dummy coding, sonar groupings, factor levels etc.
obs	Observations, including left- and right-censoring cutoffs.
param	General parameters.

See also

read_data summary.brsdata

Author

Phil J. Bouchet

Examples

if (FALSE) {
library(espresso)

# Simulate data for two species 
# (no censoring, monophasic functional form)
mydat <- simulate_data(biphasic = FALSE,
                       n.species = 2,
                       n.whales = 16,
                       max.trials = 3,
                       covariates = list(exposed = c(0, 5), range = 0.5),
                       mu = c(125, 142),
                       phi = 20,
                       sigma = 20,
                       Lc = c(60, 65),
                       Rc = c(214, 215),
                       seed = 58697)
                       
# Simulate data for three species 
# (right- and left-censoring, biphasic functional form)
mydat <- simulate_data(biphasic = TRUE,
                       n.species = 3,
                       n.whales = c(10, 5, 8),
                       max.trials = 3,
                       alpha = c(125, 140, 139),
                       nu = list(c(98, 149), c(110, 165), c(105,152)),
                       tau = c(20, 20),
                       psi = 0.5,
                       omega = 1,
                       Lc = c(60, 70),
                       Rc = c(165, 195),
                       seed = 58697)
                       
}