==================================================================
General information on the DEBkiss_tox package
==================================================================
Date: 16 September 2022
This package contains the DEBkiss model in primary parameters, with a dedicated TKTD module added. In general, I would suggest using the DEBtox2019 package for your data analyses and model predictions. The model in this DEBkiss_tox package is for further exploration, beyond the DEBtox2019 simplification.
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 two sets of closely-related model equations, both based on the primary-parameter formulation of DEBkiss. For the main part, these models are derived and described in version 2.0, and more elaborate in version 3.0, of the DEBkiss e-book (https://leanpub.com/debkiss_book). The compound-parameter DEBtox2019 model can be found in the BYOM package of by the same name.
==================================================================
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 'primary_input' has the possibility to calculate initial body size from the egg size (which is also needed as an input). For the 'compound_input' 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).
9) Reverse growth dilution (increase of the concentration upon shrinking) is currently turned off in derivatives.m. Reason is that this process can easily lead to a positive feedback loop and various calculation issues.
==================================================================
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
==================================================================
Two model types that are included in this package.
1) COMPOUND_INPUT. 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 DEBtox2019 model fails (e.g., if you 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.
2) PRIMARY_INPUT. 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. Therefore, 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 3] gives the standard ode45 solver, with very-much tightened tolerances. This is a robust option, though it will become very slow for some settings. If it becomes very slow, I suggest trying glo.stiff = [2 1], which uses a stiff solver with somewhat-tightened tolerances (very strict tolerances don't seem to work well with this solver). This may also be an appropriate choice when using the parameter-space explorer with wide search ranges (as it is bound to try parameter sets that make the system stiff).
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. This option is not too useful for running through FOCUS profiles: it takes much longer and there is no relevant difference in the output.