Version log DEBtox2019 package (previously DEBkiss_tox) for BYOM Version logging starts with 2.0 (earlier version have not been logged). Version 2.0 (28 April 2017) - Modified package so it runs with BYOM 4.0. Version 3.0 (24 May 2019) - Brought the code in line with the version 2.0 of the DEBkiss book. This means that damage is the central property of interest (rather than scaled internal concentrations), and a change in toxicity parameters/symbols. - Made a single directory that is able to run both case studies (complete_model). - Added code to automatically fit basic parameters to the control data (fixing the tox parameters), or the tox parameters to the full data set (fixing the control parameters). In general, it is a good idea to *not* fit all parameters to the full data set. - Added simplified models: a full model where the input parameters are easy-to-understand compound parameters, and a simplified model with the model equations themselves expressed in compound parameters (as in the original DEBtox models). More details in the text file about_the_DEBkisstox_package.txt. - Added license information. Version 3.1 (2 September 2019) - Reformulated the model to match a manuscript for an update of DEBtox (Jager, in prep.). This brings the formulation more in line with GUTS, and adds a starvation module in the model formulated in compound parameters. Furthermore, it adds a flexible damage equation and flexible pMoA selection. More details in the text file about_the_DEBtox2019_package.txt. - The ODE solvers in Matlab have a tendency to increase step size to very large values. That works well for nice continuous model runs, but not for sudden changes (e.g., a starvation event or a pulse exposure to a toxicant). The code for decreasing step size was already in call_deri but commented out. It is now uncommented, just to be on the safe side (the issue with too large of a step size can lead to erroneous behaviour that is difficult to spot). Version 4.0 (29 May 2020) - Turned reverse growth dilution (concentration by shrinking) OFF in derivatives. This process can lead to runaway positive feedback which leads to failure of the ODE solvers. It can always be turned on again in derivatives. By commenting out the lines indicated to deal with this process. - I made a number of changes to make the calculations more efficient, especially for time-varying exposure. The ODE solver now runs through the time vector piecewise: each interval between two events (as specified in the exposure scenario) is run separately, and the solver is restarted for the next interval. This avoids having the ODE solver run over time points where the exposure is discontinuous. Further, structure glo is now passed on to derivatives as an input rather than a global, and the faster function read_scen is used instead of make_scen. - Modified the new plotting routine plot_tktd (part of the engine folder) for use with sub-lethal effects. This makes more readable plots (especially when also plotting CIs). Format is similar to that used for openGUTS, with separate panels for each treatment. - The files in the simple_compound directory also have an option (commented out) to use the parameter-space explorer with calc_parspace. Search ranges for the toxicity parameters are automatically generated by startgrid_debtox. This is still experimental, and in any case very slow! In the next few years, expect to see more progress in this package. - The engine function calc_ecx is now capable of calculating ECx for sub-lethal endpoints. In fact, it goes through all endpoints to see which ones are affected. Version 4.1 (27 September 2020) - An error was repaired in general BYOM for the break-time functioning with ODEs, which slowed it down. Furthermore, type 4 can now be used with double time points (just like in openGUTS). Both fixes also require you to update to BYOM v. 5.2! - When running through time-varying exposure without breaking the time vector, size of the time step of the ODE solver is limited. This avoids the solver missing switches in exposure completely (which might happen with pulsed exposure). However, breaking the time vector is better in most cases. - Set the ODE solver by default to [0 3], which uses ode45 with very-much tightened tolerances. In some cases, sloppy tolerances will show an apparent optimum that only exists due to numerical problems in the solver. Care is needed with the selection of the most-appropriate solver for each problem! Version 4.2 (28 September 2020) - Spotted an error in the calculations for preventing shrinking on physical length on starvation. When running through the calculations with a rough time vector (as often in calibration), the maximum length before shrinking is poorly estimated. Simulations (with a generous time vector of 100 points or more) were not affected. In call_deri, a long time vector is now forced when glo.len == 2. - Changed the equations for preventing shrinking: the same algorithm as used in openGUTS for finding maximum damage over time for IT. This should increase speed a bit. Version 4.3, not released via the web (2 July 2021) (part of the BYOM package 6.0 Beta 1) - Corrected an error in the 'special' package that gave an error in automatic_runs when using multiple data sets per state. - In 'special' package, allowed multiple data sets per state, where some parameters can differ between sets (e.g., f and L0). - In 'special' package, there can be multiple data sets, so scaling uptake/elimination rates with Lm/L is dangerous. Instead, a reference Lm is used as glo.Lm_ref. - Corrected an error in call_deri that prevented use of Tlag in combination with time-varying exposure and breaking of the time vector. - Modified scripts to work with the new BYOM version 6.0. This includes a different function call for call_deri (including ). - Included the possibility to shift the reproduction model output to simulate a brood-pouch delay. This is useful for species like Daphnia where neonate release is counted (rather than egg production). - Moved code from the byom_debtox scripts_... to a helper function automatic_runs_basic. This makes the code easier to read. The helper function makes sure that X0mat and par are adapted based on what needs to be fitted (only basic parameters or only tox parameters). - The scripts in the simple_compound folder automatically fit the controls first (simplex), and keep the basic parameters fixed to fit the tox parameters (with the parameter-space explorer). These sections can be used for the other model versions as well. - Added the option to use repro hazards next to repro costs as MoA. - Small change for surface:volume scaling of uptake/elimination rates. Instead of the max-to-1 operator, an explicit if used to set the factors xu and xe to 1 when their matrix entry in glo.feedb is zero. This is safer as I don't know how people will want to modify the model. - Included the possibility to use metabolic acceleration (V1-morphy) rather than hyperbolic saturation of feeding. - Included the option to use hazard to embryo as well as costs for reproduction. - Extended the 'special package' with more automated options, and use of the Matlab GUI element for selecting files to select and use previously-saved MAT files. Version 4.4, not released via the web (19 August 2021) (as part of the BYOM package 6.0 Beta 4) - In 'special' package, allowed profiling of the likelihood function for the basic parameters. Just add opt_prof at the end of the call to automatic_runs_debtox2019. - In 'special' package, demonstrated the use of batch-wise calculating through exposure profiles with effect windows. - In 'special' package, added files to perform IT analysis for survival, instead of SD. - Engine function startgrid_debtox was extended to allow using IT versions and additional parameters for eggs in a brood pouch (both are preliminary versions for testing, and not part of the publicly available package). - The option for 'pruning the exposure profile' is included for effect windows and EPx calculations. Version 4.5 (27 November 2021) - This is the first web-released version that works with BYOM v.6.0. - Modified call_deri to initialise the matrices that collect the output (tout and Xout). This implies that they don't grow while looping through the exposure intervals. Theoretically, initialising should increase speed, but I cannot see that yet. However, it is more 'proper' coding, so I have included it. - Updated the 'special' packages to work with the new file to automatically read data files, and adapt their identifiers when using multiple sets. Furthermore, they now make use of the fact that all functions that create a sample also save glo, par and X0mat in the MAT file. This makes validation and calculating EPx much easier, with less chance of errors, and makes several of these files generic. However, this new functionality does not work with MAT files generated with older versions of BYOM (Before 6.0 beta 7). - Finally included an ERA_special package with all of the bells and whistles to support routine use in risk assessment. Version 4.5a (30 November 2021) - The profiling had an option setting in opt_prof that was modified. That did not produce an error; it just did not do what it was supposed to do. So the option 're_fit=1' was replaced be 'brkprof=2'. Version 4.5b (14 January 2022) - The EPx calculation for certain profiles turned out to be very slow. This related to the hazard rate become extremely high in the 'rough exploration' of the MF range, in cases where there is no effect on one of the endpoints. This is solved by maximising the hazard rate to 111 d-1, which implies 99% mortality in 1 hour. Version 4.6 (16 September 2022) - Moved the models in primary parameters to a dedicated package: DEBkiss_tox. Since the DEBtox2019 model has been published (in compound-parameter formulation), and since it is regularly used for risk assessment, it is best to not confuse users with additional (less used) model formulations in the same package. - Added Weibull background mortality parameter a to the model. When fixed to 1 it will have no effect. Values greater than one produce a nice background mortality rate that increases over time. - The hazard rate in derivatives is maximised to 111 d-1, which implies 99% mortality in 1 hour. This avoids the system becoming stiff under extreme parameter settings/forcings. This value assumes that all times are entered in days! - Tiny change in call_deri. When using an exposure scenario (with make_scen) and NOT breaking up the time vector (glo.break_time=0), call_deri sets smaller step size for the ODE solver. This makes sure that no concentration switches are missed. I now make an exception for very simple scenarios (Tev of length 2), as it is not needed and makes the solver rather slow. - Changed behaviour of the acceleration (using par.Lj). Just as in standard DEB, acceleration cannot continue after puberty, so Lj <= Lp is enforced. If Lj > Lp, call_deri will just return an empty matrix (which transfer interprets as an infinitely bad fit). - Added a script to recreate the case study for Folsomia candida in the DEBkiss e-book version 3.0. Version 4.7 (13 December 2022) - In the ERA_special package, changed the byom_batch_epx script. In the previous version, it ran multiple exposure profiles with calc_effect_window_batch. Now, that functionality is moved to the script byom_batch_effect. The byom_batch_epx now uses the new function calc_epx_window_batch. This calculates explicit EPx for each exposure profile. If CIs are requested, they are only generated on the lowest EPx (for each endpoint) for each profile. This is way more calculation efficient than calculating CIs across the entire profile. - In the ERA_special package, calls to the new DeEP conversion function convert_deep are included at two places where they could be useful. This conversion tool will convert a BYOM MAT file into an input file for the DeEP tool. Note that this function will NOT produce a file for the case studies included here, with the settings in these files. The Daphnia example uses a brood-pouhc delay and the Folsomia example uses acceleration. Both processes are not included in DeEP v.1.0 (but may be added in a future update). ========================================================== Errors spotted and things that will be changed in future releases: - In derivatives, for the damage dynamics, for the surface:volume feedbacks, switches were applied on Xi(1) and Xi(2) when these are zero. These values are, however, reals and not booleans anymore. However, it worked because these values are truly zero when the switch value in glo.feedb is zero. In terms of code readability, this is not a good idea, and I replaced the switches on Xi by switching on glo.feedb. This is also in line with the SI for the stdDEB-TKTD paper. - Added to call_deri the option to output hazard rates as Xout2. This is done when survival data are provided as time-to-death data in the main script. This still needs testing! Note that time-to-death data cannot be combined with additional calibration data in DATAx. - ...