DEBtox information
Making sense of ecotoxicity test results

Main menu
Submenu

DEBtox information

DEBtox information

Software / BYOM modelling platform

BYOM flexible model platform

Bring/Build Your Own Model (BYOM) is a flexible set of Matlab scripts and functions to help you build, simulate and fit your own models. Not just DEB models or TKTD models; any model that you want (well, as long as it can be expressed in terms of ordinary differential equations, or as explicit function). Using these files requires a working knowledge of Matlab, as there is no nice GUI. If you're new to Matlab, check out the free tutorials that the MathWorks offers, or some of the on-line course of Udemy (not free).

I originally created this platform for teaching purposes: I wanted students to build and fit their own models, but I wanted them to focus on the modelling and not on the programming (BYOM takes most of the difficulties away from the user). However, I find myself using it almost exclusively now, as it is a perfect platform (for me) for both standard and especially non-standard (one of a kind) modelling. BYOM is also used in the TKTD summercourse in Denmark.

Please note that user-friendliness is limited, which is generally the consequence of high flexibility. You need to be able to work with Matlab at a fairly basic level, and get used to the BYOM format, to be able to work with it effectively. The TKTD summercourse is a good place to get started with it.

Below, an example fit with BYOM (simultaneous fit on two state variables, with replicated data for different concentrations and different observation times)



Features:
  • Full flexibility in number of parameters; each parameter is specified by a name (in a Matlab structure). Each parameter has a min-max range that you can set.
  • Select which parameters you want to fit, and which you want to fix, in optimisation.
  • Flexibility in the model, as long as it is set up as ODEs (although I also included the option to work with explicit functions).
  • Include events functions to catch discontinuities (switches) in the model.
  • Simultaneous fitting of multiple data sets, based on multinomial or normal likelihood functions (with optional power transformations). Starting with version 2.0: the option to have multiple data sets per state.
  • Calculate asymptotic standard errors, or confidence intervals using profile likelihoods.
  • Bayesian analysis using the Matlab slice sampler (you need the statistics toolbox for that!). Also CIs on model curves and error ellipses for any two parameters.
  • Starting from version 3.0, the script files can be easily 'published' to html or pdf in Matlab (see the walkthrough).
  • Starting from version 5.0, the parameter-space explorer (see : DOI: 10.1002/ieam.4333) as used in openGUTS is now available for general application in BYOM.
  • Starting from version 6.0, support for Matlab's parallel processing toolbox that will speed up various analyses considerably (e.g., parameter space explorer with DEBtox analyses).
  • Starting from version 6.0, moving time window LPx/EPx analyses.
  • And much, much, more!
NOTE ON RELEASE 6.0. Version 6.0 is a major update, and has changed the calls of call_deri.m and derivatives.m, as well as those of several post-calculation functions. Therefore, older scripts will not work anymore. However, it should not be too hard to modify your old scripts to work with version 6 (a guide is included in the ZIP file). Make sure you use the new version of pathdefine.m as the structure of the engine folder has changed. The packages have also received updates to work with this new version. 

---> Download BYOM_v65.zip for Matlab (version 6.5, 22 March 2023) --> version_log

---> I have been working on an on-line manual for BYOM. You can look at the in-progress version that already covers the BYOM basics (updated 15 Nov. 2021). Whenever I have time I will update it and add sections to it, so in the end it will hopefully cover all of the nooks and crannies of BYOM. You may also download the PDF manual BYOM 3.x (3 April 2015). This manual will eventually be completely replaced by the on-line manual.

---> Walk through the BYOM code to see what it does! (this is for version 6.0 BETA 6)

LICENSE INFORMATION. The BYOM implementation and the associated packages are distributed under an MIT-style permissive license. The license can be downloaded here, and is included in the BYOM zip file as well. From v. 5.0, the parameter-space explorer from openGUTS was modified to be used in BYOM as well. These functions are in a sub-function of the engine folder named <parspace> and are distributed under the terms of the GNU General Public License (just like the openGUTS files from which they were derived).

DISCLAIMER AND WARNINGS. The files are prepared with care, but not extensively tested (and I adapt them all the time), so I cannot give any guarantees as to their correctness. In fact, I am pretty sure that they will contain errors given the current complexity of BYOM. Many parts only get thoroughly checked when I use them for a project (sorry, I am not getting paid for maintaining BYOM). Furthermore, as BYOM relies on numerical procedures, there is always the possibility of poor performance in extreme cases. As explained in the license file, I do not accept liability or responsibility for any damage or costs incurred as a result of using these files. If you spot an error or want to comment on these files, please contact me. Note that I will only look into problems with the current version of BYOM. If there is an update, I will post an announcement on the home page. If you are working with BYOM, and would like to be notified immediately in case of errors, new versions, etc., email me and I will include you in a mailing list. I may also use this mailing list for other important developments such as new (versions) of the e-books, and new papers. This saves you the hassle of checking this website every week ;-).

Matlab R2023a throws errors in BYOM v.6.5 and earlier.
The newest version of Matlab does not allow the cell-array format for name-value pairs anymore, at least not in the way it was used in the openGUTS Matlab version for formatting text in figures. I will prepare an update (April/May 2023) that solves this issue. Matlab versions up to 2022b do not have this problem. (thanks to Amund for spotting this).

Warnings for users of version 4.5-6.2:
  • I found an error in calc_parspace, in the 'extra sampling' code block. This section is run when the profiling step indicates a poor coverage of the sample: it should resample in the problem areas. Due to the error, it just duplicated the sample sets that were selected as starting points, so this step is useless. This error thus only influences the results for data sets where the initial sampling rounds lead to poor results (extra steps are run, but no improvement to the sample is obtained). This error is NOT present in openGUTS, even though the same algorithm is used there (the error was made in the translation to BYOM). This error has been corrected in version 6.3!
Warnings for users of version 5.0-5.2
  • Error in the engine files calc_epx and calc_ecx when used in conjunction with the slice sampler (in Bayesian analyses). The confidence intervals take min-max of the output rather than percentiles (they will thus be too wide). This has been repaired in the next update.
Warnings for users of versions before 5.0:
  • Older byom files/packages may not work error free anymore, so also update your packages to the new version. If you want to run older byom files, compare them to the new example files (or copy the data and parameters to a new example script).

Warnings for users of versions before 4.3:

  • Better update to the latest version! Some specific warnings for the old versions can be found at the bottom of this page.

ACKNOWLEDGMENTS. The development of BYOM has been helped by direct and indirect funding in a range of projects. I want to specifically thank the following:
- The European Union funded the project Marie-Curie ITN CREAM, which allowed further development of GUTS, DEBkiss and DEBtox. This formed the starting point for the development of the GUTS, DEBkiss and DEBtox-classic packages.
- The Research Council of Norway has funded a range of projects over the years, which have indirectly contributed to the development of BYOM.
- Cefic-LRI for funding the GUTS and openGUTS projects. This formed a major contribution to the development of the GUTS package. Furthermore, in the openGUTS project, the algorithm for the parameter-space explorer was developed, which was later translated to BYOM.
- Syngenta for funding code development related to simplified DEBtox analysis for supporting risk assessment. This included the translation of the parameter-space explorer from openGUTS to BYOM, methods for running through exposure profiles (calculating EPx and effect windows, including error propagation), openGUTS-type plotting routines, and robust numerical methods for using pulsed forcings. This formed a major contribution to the development of the DEBtox2019 package.
- The National Environmental Research Council (UK) funded the development of methods for GUTS mixture analyses. These methods are included into the engine folder, and demonstrated in the package GUTS-mix.
- Copenhagen University facilitated the DynModTox Summer Schools, which have been a major incentive to improve BYOM functionality and ease-of-use.
- Bayer for funding the implementation of standard DEB (following the add-my-pet format) into BYOM, and inclusion of the DEBtox2019 TKTD module into standard DEB. This is now the package stdDEB-TKTD.

OLD VERSIONS. The BYOM versions as well as the packages are archived, by me, off-line. That is done since the official release of version 1.0 in 2012. Therefore, if you need an older version of the software, for example to re-run an old analysis, please contact me and I can send you the files.

Dedicated BYOM packages

Below, I will collect packages that have been made to perform certain calculations with BYOM. Make sure you have BYOM installed and working properly. Download and unzip the file and place the directory in the BYOM directory (at the same level as the engine). For most of the packages, version logging starts with version 2.0. These packages are distributed under the same license as BYOM itself (this will be included explicitly in the files of these packages when they are updated, after 23 April 2019).

Notes for BYOM update to v.5.0 and v.6.0 (2 December 2021):
- All versions of the packages are compatible with BYOM v.6.0 and later only. Most of the walkthroughs are also updated by now. 

Packages for BYOM
Name
 Description
 Version and date
 Download
GUTS
 This package contains both simple and more elaborate GUTS implementations. Easy to adapt, and can accommodate time-varying concentrations. Includes a script to produce synthetic data sets. Take a look at the walkthrough (for v. 2.3).
 version 3.2
  29 Nov. 2021
 GUTS_v32.zip
DEBkiss
 A general version of the DEBkiss model, so more useful as starting point for your own analyses. Take a look at the walkthrough (version 2.3a). version 2.3a
  30 Nov. 2021
 DEBkiss_v23a.zip
DEBtox classic
 Classic simplified DEBtox model. This is the version as published by Jager & Zimmer (2012). Same model as in DEBtoxM flavour "Basic DEBtox", but with more flexibility. Includes case studies for Capitella and Daphnia that also demonstrate the calculation of the intrinsic rate of population increase. Take a look at the walkthrough (version 2.3a). Note: this package is NOT up-to-date with the new release of the DEBtox e-book (version 2.0) and the revisited DEBtox2019 (Jager, 2020), which place 'damage' in a central position. The DEBtox2019 package below is fully updated, and my advice for a 'standard' simplified DEB-TKTD model.
 version 2.3a
  30 Nov. 2021
 DEBtox_classic_v23a
SIMbyom
 A simulation tool for BYOM models. Can plot state vs. time, but also state vs. state (2d and 3d), or derivative vs. state. Several example systems are provided: two chaotic systems, log-logistic growth, and the Rosenzweig-MacArthur population model. Take a look at the walkthrough (version 2.1). version 2.1
  17 Nov. 2021
 SIMbyom_v21.zip
DEBtox2019
 Updated simplified DEBtox model, based on DEBkiss. A paper presenting and explaining this version is published (Jager, 2020). This version is largely equivalent to the one described in the DEBkiss e-book version 2 (and completely equivalent to upcoming version 3), and includes the simplified model versions as treated in Chapter 6. This version brings DEBtox in line with the developments in GUTS. The package includes case studies for Folsomia, Capitella and Daphnia. Take a look at the walkthrough (for version 4.5a). With version 4.6, the models using primary parameters are moved to the new package DEBkiss_tox. More information on this package. See also the associated DeEP tool to make predictions from a DEBtox2019 calibration to long-term exposure profiles. Version 4.7 of the package (ERA-special folder) shows how BYOM calibration results can be converted to DeEP input files.
 version 4.7
  13 Dec. 2022
 DEBtox2019_v47.zip
doseresp
 Use BYOM to fit a simple log-logistic dose-response curve to quantal (e.g., survival) or graded (e.g., reproduction) data. For quantal data, the binomial distribution is used. Now you can use BYOM tools like profiling and Bayes to your classic dose-response analyses (but see warning over here). Take a look at the walkthrough (version 1.3).
 version 1.3
  17 Nov. 2021
 doseresp_v13.zip
GUTS_mix
 Extension of the reduced GUTS models SD and IT for dealing with binary mixtures. The model extension is presented and discussed in Bart et al (2021). More information on this package. This package requires BYOM v.6.0 beta 8 or newer!
6 Dec. 2021
 GUTS_mix_v10.zip
stdDEB-TKTD
 Implementation of standard DEB with the TKTD module from DEBtox2019. This package requires use of AmP parameters for the species. In general, I would recommend using DEBtox2019, though, because of its simplicity. This package requires BYOM v.6.0 beta 8 or newer! This package needs a bit more testing, especially for pulsed exposure, and it is a rather complex piece of code. The paper presenting this model version is Jager et al (2023).
 version 1.1
8 March 2023
 stdDEB_tktd_v11.zip
DEBkiss_tox
 Updated simplified DEBtox model, based on DEBkiss.This package was split out of the DEBtox2019 package, and contains the models in primary parameters (with either primary parameters or compound parameters as input). In general, I advise to use the DEBtox2019 package. This formulation is for further experimentation with additional pMoAs or additional endpoints. More information on this package. version 1.0
16 Sept. 2022
 DEBkiss_tox_v10.zip

Special support packages (supporting papers or book chapters). Note that these packages are meant to reproduce published results. For your own analyses, I advise to use the packages from the table above, which are updated regularly!
Name
 Description
 Version and date
 Download
DEBkiss-paper This package contains the files to reproduce the figures for the pond snail in the DEBkiss paper (Jager et al., 2013). It is a basic implementation of DEBkiss, for continuous reproduction only, with optional maturity maintenance. Several things are specific for this example, so use the DEBkiss package above for your own analyses. Take a look at the walkthrough (older version).
 version 2.1
29 Nov. 2021
DEBkiss-paper_v21.zip
support-marecotox
 Support package to reproduce the case studies in the chapter on modelling in the book "Marine Ecotoxicology".
 version 2.2
  1 Dec. 2021
 support-marecotox_v22.zip
Acute Calanus package
 This package contains the files needed to reproduce the results of the paper "Dynamic links between lipid storage, toxicokinetics and mortality in a marine copepod exposed to dimethylnaphthalene." Environ Sci Technol http://dx.doi.org/10.1021/acs.est.7b02212 (standard GUTS analyses, TK analysis with a one- and two-comp. model, and combined GUTS and two-comp. TK analysis).
 version 1.2
  2 Dec. 2021
 acute_calanus
_package_v12.zip

The simulation package can be used to produce nice 3d-plots of chaotic attractors, like the Lorenz system (yellow dots are the equilibria, and the four colours indicate four starting points that are close together, but not the same). Take a look at the walk through the code (but seeing this thing in action is way cooler: download an AVI).

Warnings for users of really old BYOM versions (before v. 4.3)


Notes for users of profiling and slice sampling:
- I realised that the profiling algorithm is not always robust enough. It looks locally around each new point it is trying, and may easily miss better optima elsewhere. Sometimes this can be seen as sudden jumps in the profile, when the algorithm suddenly spots a better optimum, and switches from one track to another. The 4.0 version uses the option to provide multiple optimisations with randomly perturbed starting values.
- Further, I realised that the slice sampler of Matlab is not always providing a representative sample of the posterior. Especially when the different parameters differ a lot in value and/or range. The 4.0 version includes more information about the sample trace, including a calculation of the auto-correlation in the sample. I took the code from this page of the Radboud University Nijmegen, which also contains some useful information on the slice sampling and interpreting the trace. Problems will also occur when the posterior is not 'proper' (when it cannot be integrated). This requires careful consideration of prior distributions!

Notes for users of the  likelihood-region for CIs on model predictions:
- The likelihood-region method (function calc_likregion) can be used to construct the joint 95% confidence region for the parameters. This calculation is fine. However, the samples from this 95% region can also be used to calculate CIs on model predictions (model curves, or on an ECx, etc.). For more than 1 free model parameter, this leads to a CI on the model prediction with a coverage of more than 95% (they exaggerate the uncertainty). It turns out that I should not propagate the joint 95% region, but only the sets within the chi2 criterion with df=1. This is fixed in BYOM version 4.2. Do not use older mat files with this version, though.

Warnings for users of the GUTS package:
- Warning for LPx calculations: the calculation of the multiplication factors (LPx) for long exposure profiles (e.g., FOCUS profiles) seems to be biassed when the data set contains considerable background mortality (probably at hb > 0.01 d-1). This seems to lead to lower (more conservative) LPx values. This is now corrected in BYOM v. 4.2b.
- Warning for time-varying exposure scenarios: this contained an error when defining more than one type of scenario in the same analysis (all scenarios are set  to the type of the last-defined one). This is now corrected in BYOM v. 4.2b.
- Found an error in calc_conf with the new set_zero option. This option is used to plot survival over time at the LPx in the GUTS package v. 2.2. It goes wrong when background hazard is fitted on log scale (or the alllog option for the slice sampler is used). In that case, the upper and lower CI curves will be close together and show very high mortality (the curve for the best-fit parameters is allright). This is now corrected BYOM v. 4.2c.



The DEBtox information site, www.debtox.info, since July 2011