Tutorial
BeeGUTS
The goal of BeeGUTS is to analyse the survival toxicity tests performed for bee species. It can be used to fit a Toxicokinetic-Toxicodynamic (TKTD) model adapted for bee standard studies (acute oral, acute contact, and chronic oral studies). The TKTD model used is the General Unified Threshold model of Survival (GUTS).
Installation
You can install the released version of BeeGUTS from CRAN with:
And the development version from GitHub with:
Example
This is a basic example which shows you how to solve a common problem. Beware that for space constrains with CRAN, the fit has been limited to a single chain, but more chains can be used.
library(BeeGUTS)
#> BeeGUTS (Version 1.3.0, packaged on the: 2024-10-23 14:07:22 UTC)
#> - For execution on a local, multicore CPU with excess RAM we recommend calling
#> options(mc.cores = parallel::detectCores()-1)
#> - In addition to the functions provided by 'BeeGUTS', we recommend using the packages:
#> - 'bayesplot' for posterior analysis, model checking, and MCMC diagnostics.
#> - 'loo' for leave-one-out cross-validation (LOO) using Pareto smoothed
#> importance sampling (PSIS), comparison of predictive errors between models, and
#> widely applicable information criterion (WAIC).
file_location <- system.file("extdata", "betacyfluthrin_chronic_ug.txt", package = "BeeGUTS") # Load the path to one of the example file
lsData <- dataGUTS(file_location = file_location, test_type = 'Chronic_Oral', cstConcCal = FALSE) # Read the example file
plot(lsData) # Plot the data
#> [[1]]
fit <- fitBeeGUTS(lsData, modelType = "SD", nIter = 2000, nChains = 1) # Fit a SD model. This can take some time...
#>
#> SAMPLING FOR MODEL 'GUTS_SD' NOW (CHAIN 1).
#> Chain 1:
#> Chain 1: Gradient evaluation took 0.000941 seconds
#> Chain 1: 1000 transitions using 10 leapfrog steps per transition would take 9.41 seconds.
#> Chain 1: Adjust your expectations accordingly!
#> Chain 1:
#> Chain 1:
#> Chain 1: Iteration: 1 / 2000 [ 0%] (Warmup)
#> Chain 1: Iteration: 200 / 2000 [ 10%] (Warmup)
#> Chain 1: Iteration: 400 / 2000 [ 20%] (Warmup)
#> Chain 1: Iteration: 600 / 2000 [ 30%] (Warmup)
#> Chain 1: Iteration: 800 / 2000 [ 40%] (Warmup)
#> Chain 1: Iteration: 1000 / 2000 [ 50%] (Warmup)
#> Chain 1: Iteration: 1001 / 2000 [ 50%] (Sampling)
#> Chain 1: Iteration: 1200 / 2000 [ 60%] (Sampling)
#> Chain 1: Iteration: 1400 / 2000 [ 70%] (Sampling)
#> Chain 1: Iteration: 1600 / 2000 [ 80%] (Sampling)
#> Chain 1: Iteration: 1800 / 2000 [ 90%] (Sampling)
#> Chain 1: Iteration: 2000 / 2000 [100%] (Sampling)
#> Chain 1:
#> Chain 1: Elapsed Time: 45.668 seconds (Warm-up)
#> Chain 1: 45.733 seconds (Sampling)
#> Chain 1: 91.401 seconds (Total)
#> Chain 1:
#> Warning: Bulk Effective Samples Size (ESS) is too low, indicating posterior means and medians may be unreliable.
#> Running the chains for more iterations may help. See
#> https://mc-stan.org/misc/warnings.html#bulk-ess
#> Warning: Tail Effective Samples Size (ESS) is too low, indicating posterior variances and tail quantiles may be unreliable.
#> Running the chains for more iterations may help. See
#> https://mc-stan.org/misc/warnings.html#tail-ess
traceplot(fit) # Produce a diagnostic plot of the fit
summary(fit) # Gives a summary of the results
#> Computing summary can take some time. Please be patient...Summary:
#>
#> Bayesian Inference performed with Stan.
#> Model type: SD
#> Bee species: Honey_Bee
#>
#> MCMC sampling setup (select with '$setupMCMC')
#> Iterations: 2000
#> Warmup iterations: 1000
#> Thinning interval: 1
#> Number of chains: 1
#>
#> Priors of the parameters (quantiles) (select with '$Qpriors'):
#>
#> parameters median Q2.5 Q97.5
#> hb 8.32763e-03 1.09309e-04 6.34432e-01
#> kd 2.62826e-03 1.17073e-06 5.90041e+00
#> zw 8.24621e-03 1.19783e-06 5.67693e+01
#> bw 1.84061e-03 1.69711e-06 1.99625e+00
#>
#> Posteriors of the parameters (quantiles) (select with '$Qposteriors'):
#>
#> parameters median Q2.5 Q97.5
#> hb[1] 6.7631e-03 1.99199e-03 9.90951e-03
#> parameters median Q2.5 Q97.5
#> kd 1.02510e+00 7.42151e-01 2.61091e+00
#> zw 9.36139e+00 5.10762e+00 1.06863e+01
#> bw 8.75098e-03 5.95674e-03 1.06148e-02
#>
#>
#> Maximum Rhat computed (na.rm = TRUE): 1.042453
#> Minimum Bulk_ESS: 73
#> Minimum Tail_ESS: 76
#> Bulk_ESS and Tail_ESS are crude measures of effecting sampling size for
#> bulk and tail quantities respectively. An ESS > 100 per chain can be
#> considered as a good indicator. Rhat is an indicator of chains convergence.
#> A Rhat <= 1.05 is a good indicator of convergence. For detail results,
#> one can call 'rstan::monitor(YOUR_beeSurvFit_OBJECT$stanFit)
#>
#> EFSA Criteria (PPC, NRMSE, and SPPE) can be accessed via 'x$EFSA'
validation <- validate(fit, lsData) # produce a validation of the fit (here it uses the same dataset as calibration as an example, so not relevant…)
#> Note that computing can be quite long (several minutes).
#> Tips: To reduce that time you can reduce Number of MCMC chains (default mcmc_size is set to 1000).
plot(validation) # plot the validation results
dataPredict <- data.frame(time = c(1:5, 1:15), conc = c(rep(5, 5), rep(15, 15)), replicate = c(rep("rep1", 5), rep("rep3", 15))) # Prepare data for forwards prediction
prediction <- predict(fit, dataPredict) # Perform forwards prediction. At the moment, no concentration recalculation is performed in the forwards prediction. The concentrations are taken as in a chronic test
plot(prediction) # Plot of the prediction results
Documentation
For the complete documentation, refer to the github page