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. If you're new to Matlab, check out tutorial from Udemy, or the tutorial that the MathWorks offers. In the future, I hope to test/modify BYOM to run in GNU Octave (which is freeware).

I originally created this platform for teaching purposes: I want students to build and fit their own models, but I want 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 more and more, as it is a perfect platform for non-standard modelling (which is not so easy with DEBtoxM). BYOM is also used in the TKTD summer course in Denmark.

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).
  • And much, much, more!
At this moment, BYOM is written only for Matlab. It is probably not too hard to modify it for Octave as well ... The new version 4 is a major update, and has changed the calls of the post-calculation functions (to allow to work with options structures), increasing robustness of profiling, and adding many nifty features (o.a., pre-defined figure window size to accommodate multiplots, and saving figures as PDF). This version seems very stable so far, but errors or unexpected behaviour may still occur owing to the large number of changes made throughout. If you run into an error, please let me know!

---> Download BYOM.zip for Matlab version 5.2 (24 September 2020) --> version_log

---> I am working on an on-line manual for BYOM. You can look at the in-progress version that already covers the BYOM basics. Whenever I have time I will add sections to it, so in the end it will 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 4.2)

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 WARNING.
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 ;-).

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 will be 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.

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 (2 June 2020):
- I still need to go through some of the special support packages (second table below) to make sure that they are fully compatible with BYOM v.5.0. Till that time, occasional error messages may occur. The packages in the first table should all work as of today.

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.1
  26 Sept. 2020
GUTS.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.2
28 Sept. 2020
DEBkiss.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. Note: this package is NOT up-to-date with the new release of the DEBtox e-book (version 2.0), which places 'damage' in a central position. The DEBtox2019 package below is fully updated, and my proposal for a 'standard' DEBtox model.
version 2.2
27 Sept. 2020
DEBtox_classic.zip
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.0
  28 Apr. 2017
SIMbyom.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 includes the three different model versions as treated in Chapter 5. This version brings DEBtox in line with the developments in GUTS. This package replaces the package DEBkiss_tox. The package includes case studies for Folsomia, Capitella and Daphnia. Take a look at the walkthroughMore information on this package.
version 4.2
  28 Sept. 2020
DEBtox2019.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.2
  22 May 2019
doseresp.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. version 2.0
28 Apr. 2017
DEBkiss-paper.zip
support-marecotox
Support package to reproduce the case studies in the chapter on modelling in the book "Marine Ecotoxicology".
version 2.1
  9 Aug. 2017
support-marecotox.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.1
  8 Aug. 2018
acute_calanus
_package.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