# 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. 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: )
    #> - 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.001522 seconds
    #> Chain 1: 1000 transitions using 10 leapfrog steps per transition would take 15.22 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: 270.739 seconds (Warm-up)
    #> Chain 1:                95.724 seconds (Sampling)
    #> Chain 1:                366.463 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

    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 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.75397e-03 1.81591e-03 1.02663e-02
    #>  parameters      median        Q2.5       Q97.5
    #>          kd 1.01050e+00 7.27582e-01 2.56515e+00
    #>          zw 9.38738e+00 5.25934e+00 1.06867e+01
    #>          bw 8.78740e-03 6.09094e-03 1.04962e-02
    #>
    #>
    #>  Maximum Rhat computed (na.rm = TRUE): 1.029804
    #>  Minimum Bulk_ESS: 56
    #>  Minimum Tail_ESS: 44
    #>  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