artemis (version 1.1.1)

eDNA_lm: Fit eDNA Model

Description

Fit eDNA model

Usage

eDNA_lm(
  formula,
  data,
  std_curve_alpha,
  std_curve_beta,
  upper_Cq = 40,
  prior_intercept = normal(location = -15, scale = 10),
  priors = normal(),
  ...
)
eDNA_lmer(
  formula,
  data,
  std_curve_alpha,
  std_curve_beta,
  upper_Cq = 40,
  prior_intercept = normal(location = -15, scale = 10),
  priors = normal(),
  prior_random_variance = exponential(),
  ...
)
eDNA_zinf_lm(
  formula,
  data,
  std_curve_alpha,
  std_curve_beta,
  upper_Cq = 40,
  probability_zero = 0.08,
  prior_intercept = normal(location = -15, scale = 10),
  priors = normal(),
  ...
)
eDNA_zinf_lmer(
  formula,
  data,
  std_curve_alpha,
  std_curve_beta,
  upper_Cq = 40,
  probability_zero = 0.08,
  prior_intercept = normal(location = -15, scale = 10),
  priors = normal(),
  prior_random_variance = exponential(),
  ...
)

Arguments

formula

a formula, specifying the relationship between the predictors and the latent variable eDNA concentration.

data

data.frame, with the response and predictors

std_curve_alpha

the alpha (intercept) value for the formula for converting between log(eDNA concentration) and CQ value

std_curve_beta

the beta (slope) value for the formula for converting between log(eDNA concentration) and CQ value

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.

prior_intercept

named list such as created by rstanarm::normal. The list must contain elements named "location" and "scale", which are the location and scale for a normal prior over the intercept. Ignored when the intercept is omitted in the model formula.

priors

named list such as created by rstanarm::normal. The list must contain elements named "location" and "scale", which are the location and scale for a normal prior over the betas, and "autoscale". If a single value is provided, this value will be repeated for each beta. If autoscale = TRUE, the scale of the priors is scaled by the sd of the predictors similar to rstanarm handles them.

...

additional arguments passed to sampling

prior_random_variance

the prior on variance of the random effects. Defaults to exponential distribution with rate 1.

probability_zero

numeric, between 0 and 1. The probability of a non-detection from a source other than low concentration of eDNA, e.g. a filter failure. Defaults to 8 was the estimated p(zero) from a daily sampling experiment.

Value

S4 object, with the following slots:

ln_conc

matrix, the posterior samples for the latent variable, eDNA concentration

Cq_star

matrix, the posterior prediction for the observed response

betas

array, the posterior estimates for the betas for the linear model

sigma_ln_eDNA

array, the posterior estimates for the measurement error of ln_eDNA

formula

formula, the original formula used in the model

x

data.frame, the model matrix used in the model

std_curve_alpha

numeric, the std. curve intercept value used

std_curve_beta

numeric, the std. curve slope value used

upper_Cq

numeric, the upper limit for observed CQ used

stanfit

stanfit, the original results from rstan::sampling

Diagnosing warning and error messages

The models have been written in Stan with key focus on robustness and speed. However, it is possible that users might encounter issues. Typically, these issues will be highlighted by warning messages coming from rstan::sampling. Often times, these warnings can be resolved by increasing the number of iterations that the HMC algorithm runs by specifying iters to be a larger value. This should be the first action attempted, as increasing the iters increases both the warm-up and sampling iterations. If users continue to have issues, additional control arguments can be passed to rstan::sampling via the ... argument.

Details

These functions fit a Bayesian latent variable model to data collected from a eDNA sampling experiment. These data have a few particular characteristics that justify using a specialized model. More details on these characteristics and the model structure, please refer to the "Getting Started" vignette for the artemis package.

There are four different modeling functions in the artemis package, eDNA_lm, eDNA_lmer, eDNA_zinf_lm, eDNA_zinf_lmer. eDNA_lm is for fitting a fixed effects model, while eDNA_lmer is for fitting a mixed or random effects model. The *_zinf versions implement a zero-inflated version of their respective lm function. All models are fit using the rstan::sampling function, which uses a Hamiltonian Monte Carlo algorithm to estimate parameters for the model. Users are encouraged to refer to the documentation for Stan and RStan at https://mc-stan.org/users/documentation/ for details about how models are fit.

Examples

# NOT RUN {
## Fixed effect model
ans = eDNA_lm(Cq ~ Distance_m, eDNA_data,
              std_curve_alpha = 21.2, std_curve_beta = -1.5)

# }
# NOT RUN {
## Mixed-effect model
## This takes a while to run
ans2 = eDNA_lmer(Cq ~ Distance_m + (1|FilterID), eDNA_data,
                 std_curve_alpha = 21.2, std_curve_beta = -1.5)

# }
# NOT RUN {
# }