est_power_lmer: Estimate power
In artemis: Analysis and Simulation of Environmental DNA Experiments

Description Usage Arguments Details Value Author(s)

Estimate the power for a given eDNA design

est_power_lm(
  formula,
  variable_list,
  betas,
  sigma_Cq,
  std_curve_alpha,
  std_curve_beta,
  type = c("exclude_zero", "accuracy"),
  accuracy_level = 0.2,
  conf_level = 0.95,
  n_sim = 200L,
  probs = conf_to_probs(conf_level),
  upper_Cq = 40,
  X = expand.grid(variable_list),
  verbose = FALSE
)

est_power_lmer(
  formula,
  variable_list,
  betas,
  sigma_Cq,
  sigma_rand,
  std_curve_alpha,
  std_curve_beta,
  type = c("exclude_zero", "accuracy"),
  accuracy_level = 0.2,
  conf_level = 0.95,
  n_sim = 200L,
  probs = conf_to_probs(conf_level),
  upper_Cq = 40,
  X = expand.grid(variable_list),
  verbose = FALSE
)

`formula`	a model formula, e.g. `y ~ x1 + x2`. For `sim_eDNA_lmer`, random intercepts can also be provided, e.g. `( 1 \| rep )` .
`variable_list`	a named list, with the levels that each variable can take. Please note that the variables listed in the formula, including the response variable, must be present in the variable_list or in the X design matrix. Extra variables, i.e. variables which do not occur in the formula, are ignored.
`betas`	numeric vector, the beta for each variable in the design matrix
`sigma_Cq`	numeric, the measurement error on CQ.
`std_curve_alpha`	the alpha value for the formula for converting between log(eDNA concentration) and CQ value
`std_curve_beta`	the beta value for the formula for converting between log(eDNA concentration) and CQ value
`type`	either "exclude_zero" or "accuracy". Exclude_zero give the classic power estimate, i.e. whether 0 is in the confidence interval for the estimate ("significant"). Accuracy measures whether the estimated betas are within some percentage of the "true" betas used to simulate the data.
`accuracy_level`	numeric, between 0 and 1. The percent of the true betas for the accuracy estimate.
`conf_level`	numeric, between 0 and 1, representing the percent of the confidence interval to calculate. If `probs` is not provided, then the interval is assumed to be symetric.
`n_sim`	integer, the number of simulations to conduct in order to estimate the power.
`probs`	probabilities for the calculation of the confidence intervals. By default, a symetric set of lower and upper probabilities is constructed by `conf_to_probs`)
`upper_Cq`	numeric, the upper limit on CQ detection. Any value of log(concentration) which would result in a value greater than this limit is instead recorded as the limit.
`X`	optional, a design matrix. By default, this is created from the variable_list using `expand.grid()`, which creates a balanced design matrix. However, the user can provide their own `X` as well, in which case the variable_list is ignored. This allows users to provide an unbalanced design matrix.
`verbose`	logical, when TRUE output from `rstan::sampling` is written to the console.
`sigma_rand`	numeric vector, the stdev for the random effects. There must be one sigma per random effect specified

These functions estimate the power for a given eDNA design and specific effect sizes. The functions allow the user to specify to either use the classic definition of power (i.e., whether an estimate includes 0 in the confidence/credible interval), or accuracy, defined as the estimates being within a certain percentage of the "true" betas. Both can be useful in different circumstances, but eDNA survey studies produce data where accuracy can be a more useful metric. Since the response variable, Cq values, are truncated at an upper limit, it is often possible to detect a "significant effect" which results in Cq values above this upper limit, but the effects are estimated with a high amount of uncertainty. When are primarily interested in the precision of the estimate, the classic definition of power is not helpful. For these reasons, these functions allow the user to specify "accuracy" as the metric of interest.

a named vector, with one estimate of the power for each parameter estimate.

Matt Espe

artemis documentation built on Sept. 9, 2021, 1:07 a.m.