Version log GUTS package for BYOM
Version logging starts with 2.0 Beta 1 (earlier version have not been logged).
Version 2.0 Beta 1 (02/03/2017)
- The earlier GUTS1 and GUTS2 package have been merged in 2.0 beta 1. The files in the main folder are the ones to start with (reduced model, constant exposure, analytical solution, only pure SD and IT). The other folders contain the more fully featured 'reduced' and 'full' models.
- This version is made fully compatible with GUTS version 4.0 Beta 2, and the examples make use of several of the new features.
- The naming of the symbols and the model structure now closely follows the new definition as will be used in the GUTS e-book (to be released end of 2017). The model is still the same, and all analyses types that could be performed with the old version are still possible. The examples provided will cover the most common types.
- In the full model, there is an option to set damage repair to fast. This effectively implies that the actual internal concentration is used as dose metric.
- The derivatives.m for the full and reduced model contain the code to include time-varying concentrations. This is demonstrated in the diazinon case studies.
- For the GUTS e-book, we decided that the log-logistic distribution should be the standard for GUTS. This is therefore also the case in this package. In call_deri, you can still find the option for the log-normal.
- The options for the ODE solver have been moved to globals so they can be set in the script.
- For IT and the mixed model (IT and SD combined), a long time vector is needed for the calculations. This was earlier captured in prelim_checks, but is now placed in call_deri for the GUTS package.
- The starting values estimator has been updated and should work well for the simples cases (reduced model, no dynamic damage stage) and constant exposure.
Version 2.0 Beta 2 (2017)
- Several errors in startvals.m that led to errors for some data sets. Also added a short range for hb. Also corrected the call to startvals in all scripts apart from byom_guts_start.
- Corrected the legends for the dieldrin cases: should be ug/L and not uM.
- Forgot to change "clear all" to "clear, clear global" in several of the example scripts.
- Removed the use of the log-normal distribution in call_deri, as we will use the log-logistic as the GUTS default.
Version 2.0 (27 April 2017)
- No additional changes to the beta 2 version.
- Note: when using the likelihood-region method to make confidence intervals for the LC50, percentiles were taken. This should have been min-max, which leads to somewhat wider intervals on the LC50. This is now corrected in BYOM 4.1.
Version 2.1 (01 February 2018)
- Restructured the package into full and reduced, and included a still somewhat experimental part in a separate directory (see next point). Many small changes in comments and layout.
- Added a series of files that include a more extensive analytical solution for the TK+damage dynamics. This can be used with constant exposure, but also for pulsed exposure (as long as the total time vector can be divided into a limited number of episodes with a constant concentration). This latter option makes use of the new function make_te, which creates a global that carries the information on the forcing events (see example files in the 'experimental' directory).
- The full model now also makes use of the analytical solution for constant exposure.
- Increased the long time vector that needs to be calculated for IT and the mixed models from 100 to 200, which should be sufficient for almost all cases. This is now a parameter in call_deri, so when you model very long time periods (e.g., >20 days), this may need to be extended.
- Plot_guts now produces some warnings to let you know that some plots may need careful interpretation due to NaNs in the data, missing animals, or multiple data sets.
- Plot_guts now makes a predicted vs observed plot for the survival probability, and also calculates a significance test for the fit (when plotting expected vs. predicted deaths, and requires the statistics toolbox).
- Modified the calculation of LC50s and multiplication factors to work with the make_te version of an exposure profile (defining multiple episodes with constant concentration within an episode). Changes are made in the general BYOM engine, but only affect the GUTS calculations.
Version 2.2 (07 August 2018)
- The experimental part from the previous version is now made into the main part. In general, it seems like a good idea to keep the hazard integration out of derivatives and simplefun. The main advantage is flexibility and transparency of the code, and easier to make use of analytical solutions for the TK/damage model (even under some time-varying exposure scenarios and when using the full model). Downside is that the analytical solution for SD under constant exposure is now not used.
- For GUTS analyses, a longer time vector is made in call_deri automatically. This is needed for IT to catch the location where the damage level reaches it maximum. For the 'standard' directory, the hazard integration is also done in call_deri, which requires a time vector with more detail. This minimum time vector was set to 200 elements in previous versions but is now 500 in call_deri.m (this does not seem to slow down the analysis much). It is automatically extended when a long time-varying exposure profile needs to be calculated (e.g., a FOCUS profile). For long constant exposure scenarios, or long scenarios with only a few events, it makes sense to increase this value.
- In call_deri for IT, the maximum damage over time is now located in a more efficient manner.
- Simplefun now includes an option to perform fast or slow kinetics for the reduced GUTS models (kd to infinity or zero). This is activated with a global (glo.fastslow set to 'f' or 's'). Note that this is only done for simplefun so when glo.useode=0 (which, for fast and slow kinetics, can now also be used with splined exposure profiles!). Slow kinetics is a bit confusing, as mw should now be interpreted as mw/kd and bw as bw*kd ...
- Note that the definition of time-varying concentrations has changed in the main BYOM engine, which so far mainly affects the GUTS package. Code for extraction of exposure concentrations in derivatives and simplefun is now more compact. For more information, see the BYOM version log.
- The file start_vals (for start value estimation) has been moved to the engine and renamed start_vals_guts. However, it is likely that this function will be removed in future releases as the parameter-space explorer (as under development for the standalone GUTS software) generally has less calculation time, and as added bonus gives confidence intervals on parameters as well as a sample from the joint CI for intervals on model predictions. This function is not yet included in this release as it needs some tweaking (and some work to get it into the generic setting of BYOM so it also works with other models than GUTS-RED models).
- Only the files byom_guts_start and byom_guts_extra (in the folder standard/reduced) have full commenting for every section of the code. In the other files, the comments are limited to a few lines.
Version 2.3 (07 September 2018)
- In BYOM v. 4.2b, a new interpolation method was introduced (type 4, a linear forcing). This is now used with an analytical solution for the reduced and full GUTS models in the directory standard. This leads to faster, and generally more accurate, results than the combination of splining (type 1) and the ODE solver.
- Analytical solutions are now implemented for the full model in the standard directory as well: dealing with static renewal and linear forcing (make_scen types 2, 3 and 4 can now be used). Thanks to Bob Kooi for running the ODEs through Maple for me! The analytical solutions for the full model are not well tested, so it does not hurt to run the ODE solver as well to make sure the result is correct!
- Implementation of a fast way to calculation LPx values (calc_conf_lpx_lim), at the expense of generality: this only gives proper results for the standard GUTS models (full and reduced), such as provided in the standard directory! As soon as you modify the models, it might not give correct results anymore. It is not included in the engine, but in the GUTS directory where it will work properly.
- Also, a faster way to calculate LCx values in calc_conf_lcx_lim. Again, this will only work with the standard model (in this case only the reduced model). It applies the analytical solution for the LCx (IT) or for the survival probability (SD).
- The calculation of the LCx and LPx contained a bias in case background hazard is high and the exposure period is very long. See the BYOM version log for details. This has been fixed.
- Small change in the analytical solution for SD in the sd_special directory: it could be simplified as we only deal with a single exposure concentration at a time. This does not affect the output in any way.
- The way that sampling error was included for the frequentist (likelihood region) approach in calc_conf was only approximate. It is now disabled until I find a correct way to do it. A warning is put on screen. If you like to calculate intervals with sampling errors, use the Bayesian approach (but make sure your posterior is proper!).
- I added files to do the calculations for the ring test. If you run them as is, it will be fast but no CIs will be calculated. Depending on the analysis, this can take quite a bit of time. You can play with the slice sampler for a Bayesian analysis, or the likelihood region method. The settings for these are set rather crudely; the settings that I used for my last run can be read from the PDF downloadable from http://www.debtox.info/book_guts.html (bottom of the web page).
- The goodness of fit tests are removed from plot_guts. They need to be checked for the cases where replicated treatments are used, and they seem to be of limited use in judging a fit anyway.
- Corrected an error in plot_guts in the predicted-vs-observed plot when using replicated data (it was plotting the observations, one replicate versus the other).
- When using replicates, plot_guts now only makes a plot of death vs time in case the initial number of individuals is the same in the different replicates of that treatment. In the previous version, I used the mean number of individuals for the predicted deaths, but this makes the plot impossible to interpret. Overall, I need to look closer at the use of replicates (and how to plot them), which will be on my todo list.