==================================================================
General information on the DEBtox2019 package
==================================================================
Date: 29 May 2020
GENERAL WARNING: This package has not extensively been tested yet, and has been modified quite a bit (and BYOM itself as well). I hope that in the near future, more (and more interesting) data sets will become available. Therefore, this version of the package should be seen as experimental, and you may run into error messages with some more exotic analysis or data sets. Take special care when working with time-varying exposure, NaNs in your data, replicated data, etc.
ANOTHER GENERAL WARNING: Analysing data sets with DEBtox is tough! Really, trust me! You need quite a bit of expertise in DEB, TKTD, optimisation routines, ODE solvers, and the workings of my code to get to the best possible result. This code is therefore nothing like openGUTS where you push a button and all is done automatically. It is very easy to make a plausible-looking analysis that yields complete nonsense.
This package contains three sets of closely-related model equations, all based on DEBkiss. For the main part, these models are derived and described in version 2.0 of the DEBkiss e-book (https://leanpub.com/debkiss_book). Version 3.0 of this package was consistent (in terms of models and symbols) with version 2.0 of the e-book. However, in the meantime, I have published a manuscript with an update of 'DEBtox' and have settled on a slightly different formulation. This version of the package follows that publication (though it should not be too hard to understand with the information in version 2.0 of the e-book). The paper can be found from https://doi.org/10.1016/j.ecolmodel.2019.108904.
==================================================================
General points to note
==================================================================
For those familiar with classic DEBtox models, there are a few general things to note:
1) The models are phrased as 'reduced models', using scaled damage as the central property driving toxicity, and a rate constant designated as a 'dominant rate constant'. In this way, the model formulation differs from the classical DEBtox models (e.g., Jager & Zimmer), but is in line with the developments of GUTS (see the GUTS e-book: https://leanpub.com/guts_book). The 'Making sense' e-book has, in version 2.0, also been updated to reflect a central role for damage.
2) As damage is central, there is no scaled internal concentration anymore. In the reduced models, damage may reflect internal concentrations, or some form of damage, or a combination of both. Damage is not necessarily diluted by growth or affected by the animal's surface to volume ratio. Therefore, a flexible damage configuration is used, with on/off switches for the various feedbacks.
3) For the pMoA, a similar set of switches is used as for the damage configuration. This allows trying out combinations of affected processes.
4) The tolerance concentration has been replaced by an effect strength (which is equivalent to 1/cT). This is done to bring the model for sub-lethal effects more in line with that for lethal effects (the killing rate is also an effect strength).
5) The TK/damage module allows incorporation of losses with reproduction. This requires an additional parameter (KRV). KRV=1 is a useful starting point, which implies that eggs receive the same chemical concentration as the mother had at the time of egg production.
6) Model type 'complete_primary' has the possibility to calculate initial body size from the egg size (which is also needed as an input). For the 'complete_compound' model, this would also be possible but would require some additional code in call_deri.m.
7) The model formulations in this package standardly contain a few extras: the possibility to include a size-dependent food limitation (as e.g., used for nematodes), and the option for a lag time (used for the Capitella case study).
8) The models include a consistent starvation module, though this will require some testing in practice. Note that toxicant stress on assimilation and/or maintenance may induce starvation (especially under time-varying exposure).
==================================================================
Facilitated model calibration
==================================================================
Fitting a DEBtox model to data from toxicity tests is more complex than fitting a GUTS model. One problem is that there are more parameters to fit: usually around 10, which makes it tough to optimise. The strategy that I propose is to first fit the parameters that govern the control response, and then fix these while fitting the entire data set. To facilitate this strategy, I included some code in the "Calculations and plotting" section. If you set the first element of to 0, the code will automatically select the controls (for which the treatment identifier is 0) for fitting, and only fits a selection of the parameters (those for the control behaviour). If you set the first element to 1, the code will automatically select all treatments for fitting, and only fits a selection of the parameters (those for the toxicant response).
I you want to fit all parameters together, comment out this section of the code. However, more likely than not, you will end up with nonsense.
==================================================================
Model types
==================================================================
Three model types that are included in this package.
1) SIMPLE_COMPOUND. This is the DEBkiss model translated into compound parameters. This leads to a very compact (though slightly abstract) set of model equations (as in the original DEBtox of Kooijman & Bedaux). This version is easiest to use, and would be recommended for most data sets. Body size must be entered as a length measure (which may be the cubic root of body weight or volume).
2) COMPLETE_COMPOUND. This is the full DEBkiss model, specified in compound parameters (e.g., maximum body length and von Bertalanffy growth-rate constant). The user thus interacts with easy-to-understand parameters, that are internally translated into the primary ones. After that translation, the model calculations are exactly the same as for the full model in primary parameters. This version is recommended if the previous model fails (e.g., the need to try out other pMoAs, add maturity, or add endpoints like respiration). For this version, conversion factors (e.g., shape correction) need to be established for the species of interest, as well as the dry weight of a single egg.
3) COMPLETE_PRIMARY. This is the full DEBkiss model, specified in primary parameters (e.g., maximum surface-specific assimilation rate and specific maintenance rate). This version is generally not recommended.
==================================================================
Main open questions
==================================================================
1) The feedbacks from the life-history traits to the TK/damage module require further investigation. At this moment, this package contains full flexibility to try out different configurations, as it is unclear a priori which one is most relevant (for which situations). The classical DEBtox models simply used growth dilution and scaling with the surface:volume ratio for all cases (ignoring losses with reproduction). However, since damage dynamics may be dominant, this is not a good idea in general. This aspect requires dedicated testing.
2) Few studies have dealt in detail with starvation effects in DEB models, and none have looked at toxicant effects on starvation. Since starvation may be induced by (time-varying) exposure to toxicants, this is not a trivial matter. In this version of the model, animals will shrink at some point, which leads to the reverse of growth dilution: 'shrinking concentration'. This is a positive feedback mechanism that will rapidly lead to runaway model behaviour. It needs to be investigated whether 'shrinking concentration' actually happens. Note: in version 4.0, the reverse growth dilution has been turned off as it rapidly leads to numerical problems.
3) Starvation could also increase the probability to die. This is not considered at the moment, due to a lack of suitable information on this issue.
==================================================================
ODE solver technicalities
==================================================================
Working with ODE solvers is rather tricky. I have not yet found a single solver that works for all problems I throw at it. Therefore, the scripts have a setting for choosing the solver and the level of precision. Setting glo.stiff = [0 1] gives the standard ode45 solver, with slightly tightened tolerances. This one is pretty fast, and a good one to start it. However, there will be plenty of cases where this solver will not be precise enough. It is good to check its output against much tighter tolerances as in glo.stiff = [0 3]. If the model curves show unexpected behaviour (extra up-and-down waves or spikes) try a different solver.
With version 4.0, an option glo.break_time has been included. Setting this to 1 implies that breaks up the time vector, and runs the ODE solver piecewise. It breaks the time vector at the places where exposure events are defined. Therefore, this setting is useful for time-varying exposure with discontinuities (type 2-4). It is also useful when you set a lag time (), e.g., to cover an initial period when the animal is not feeding/developing.