DEBtox information
Making sense of ecotoxicity test results

Main menu


DEBtox information

DEBtox information

Software / BYOM modelling platform

BYOM flexible model platform

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)

  • 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 funcions (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 for Matlab version 4.1 (1 Feb. 2018) --> version_log

---> I am working on an on-line manual for BYOM 4. 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 not for the latest version, but still representative)

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). I do not accept liability or responsibility for any damage or costs incurred as a result of these errors. 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.

Warnings for users of versions before 4.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).
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.

Additional 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.

Additional packages for BYOM
Version and date
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.0). version 2.1
  1 Feb. 2018
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.0
28 Apr. 2017
Simplified DEBtox model (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.0
28 Apr. 2017
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
DEBkiss model with TK and TD modules to deal with toxicity. Includes case studies for Capitella and Daphnia. Take a look at the walkthrough. version 2.0
28 Apr. 2017
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.0
28 Apr. 2017

Special support packages (supporting papers or book chapters)
Version and date
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
Support package to reproduce the case studies in the chapter on modelling in the book "Marine Ecotoxicology".
version 2.0
  27 Apr. 2017
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 (standard GUTS analyses, TK analysis with a one- and two-comp. model, and combined GUTS and two-comp. TK analysis).
version 1.0
16 Jun. 2017

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

The DEBtox information site,, since July 2011