Learn R Programming

artemis (version 1.1.1)

est_power_lm: Estimate power

Description

Estimate the power for a given eDNA design

Usage

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 )

Arguments

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

Value

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

Details

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.