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 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 BYOM.zip for Matlab version 4.2c (7 Sept. 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 for version 4.2)

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

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.

Notes for BYOM update to v. 4.2 (7 Aug. 2018):
- I still need to go through some of the packages to check if they are fully compatible with BYOM v.4.2. Even though I do not expect problems, occasional error messages may occur. If they do, please let me know.

Additional 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 2.3
  7 Sept. 2018
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.0
28 Apr. 2017
DEBkiss.zip
DEBtox
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
DEBtox.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
DEBkiss_tox
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
DEBkiss_tox.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.1
  9 Aug. 2018
doseresp.zip

Special support packages (supporting papers or book chapters)
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).




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