Overview
toxval is an R package for estimating ecotoxicological toxicity
metrics from fitted concentration-response models. It extracts effect
concentrations (ECx) with ecx() and No-Significant-Effect
Concentrations (NSEC) with nsec().
toxval currently has methods for Bayesian models fitted with
brms or
bayesnec and frequentist
models fitted with drc. The
package is designed so that more model classes can be easily added,
letting users estimate toxicity metrics from whichever modelling
framework they work in.
For every model class, the fitted curve is evaluated over a grid of
concentrations once per realisation of the fit (once per posterior draw
for a Bayesian fit, and once per parametric bootstrap replicate for a
frequentist one), the metric is found for each realisation, and the
realisations are summarised by an estimate and compatibility limits. The
result is a toxval tibble with one row per curve and direction.
For the theoretical basis of the NSEC, see Fisher & Fox
(2023). For model-averaged N(S)EC
estimation across smooth and threshold model classes, see Fisher et al.
(2024).
Installation
The current development version can be installed from GitHub with
if (!requireNamespace("remotes")) {
install.packages("remotes")
}
remotes::install_github("open-aims/toxval")
Usage
ecx() and nsec() take a fitted model and return a toxval tibble,
whichever framework the model was fitted with. The examples estimate the
EC10, EC50 and NSEC of ryegrass root length from the ryegrass data in
drc, first from a three-parameter log-logistic curve fitted with
drc:
library(toxval)
library(drc)
fit_drc <- drm(rootl ~ conc, data = ryegrass, fct = LL.3())
ecx(fit_drc, proportion = c(0.1, 0.5), seed = 42)
#> # A tibble: 4 × 10
#> # Model: drc
#> # Settings: resolution 500 | 1000 bootstrap realisations
#> metric direction estimate conf.low conf.high proportion type control reference
#> <chr> <chr> <dbl> <dbl> <dbl> <dbl> <chr> <dbl> <dbl>
#> 1 ecx decreasing 1.33 0.946 1.70 0.1 absolute 7.85 7.06
#> 2 ecx increasing NA NA NA 0.1 absolute 7.85 8.63
#> 3 ecx decreasing 3.27 2.89 3.66 0.5 absolute 7.85 3.92
#> 4 ecx increasing NA NA NA 0.5 absolute 7.85 11.8
#> # ℹ 1 more variable: asymptote <dbl>
nsec(fit_drc, seed = 42)
#> # A tibble: 2 × 14
#> # Model: drc
#> # Settings: resolution 500 | 1000 bootstrap realisations
#> metric direction estimate conf.low conf.high sig_val type anchor control reference
#> <chr> <chr> <dbl> <dbl> <dbl> <dbl> <chr> <chr> <dbl> <dbl>
#> 1 nsec decreasing 1.06 0.504 1.40 0.01 absolute model 7.85 7.36
#> 2 nsec increasing NA NA NA 0.01 absolute model 7.85 8.31
#> # ℹ 4 more variables: asymptote <dbl>, ecnsec <dbl>, ecnsec.low <dbl>, ecnsec.high <dbl>
Both directions are estimated every time. Root length falls with
concentration, so the increasing rows have no crossing and are NA. The
header records the model class and the settings the estimates were
computed with. The realisations of a drc fit are parametric bootstrap
replicates, so seed makes the results reproducible.
The same curve fitted with brms gives estimates in the same form,
summarised over the posterior draws:
fit_brms <- brms::brm(
brms::bf(rootl ~ top / (1 + (conc / ec50)^b), top + ec50 + b ~ 1, nl = TRUE),
data = ryegrass,
prior = brms::set_prior("normal(0, 10)", nlpar = c("top", "ec50", "b"), lb = 0),
seed = 42,
refresh = 0
)
This is the beginning of the README. Read the rest at the original. Read the full README ↗
