# 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:

    install.packages("BeeGUTS")

And the development version from GitHub with:

    # install.packages("devtools")
    devtools::install_github("bgoussen/BeeGUTS")

## Example

This is a basic example which shows you how to solve a common problem:

    library(BeeGUTS)
    #> BeeGUTS (Version 1.1.3, packaged on the: )
    #> - 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') # 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.003877 seconds
    #> Chain 1: 1000 transitions using 10 leapfrog steps per transition would take 38.77 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: 46.334 seconds (Warm-up)
    #> Chain 1:                42.017 seconds (Sampling)
    #> Chain 1:                88.351 seconds (Total)
    #> Chain 1:
    #> 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

    plot(fit) # Plot the fit results
    #> [[1]]

    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 1.30384e-03 1.15441e-06 1.47261e+00
    #>          bw 7.36245e-02 6.78843e-05 7.98500e+01
    #>
    #> Posteriors of the parameters (quantiles) (select with '$Qposteriors'):
    #>
    #>  parameters      median        Q2.5       Q97.5
    #>       hb[1] 6.91682e-03 3.71481e-03 1.00421e-02
    #>  parameters      median        Q2.5       Q97.5
    #>          kd 1.00459e+00 7.35096e-01 1.76633e+00
    #>          zw 2.37407e-01 1.48619e-01 2.68072e-01
    #>          bw 3.57555e-01 2.68854e-01 4.21737e-01
    #>
    #>
    #>  Maximum Rhat computed (na.rm = TRUE): 1.018584
    #>  Minimum Bulk_ESS: 216
    #>  Minimum Tail_ESS: 54
    #>  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