Making sense of ecotoxicity test results
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)
---> 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:
Warnings for users of versions before 4.3:
development of BYOM has been helped by direct and indirect
funding in a range of projects. I want to specifically
thank the following:
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
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
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!
|The simulation package can be
used to produce nice 3d-plots of chaotic attractors, like
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
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.