software package DEBtool

by Bas Kooijman, 28 June 2010

Purpose

DEBtool is a software package written in Matlab 7.3.0 (DEBtool_M) and Octave 3.2.4 (DEBtool_O) and that can be used to illustrate some implications of the Dynamic Energy Budget theory and to apply this theory in the analysis of eco-physiological data. The manual and the code follow the DEB notation. It has script-files for almost all figures of the DEB book, with many references to the formulae in the book, and explaining remarks. Add_my_pet (AmP) is an example of application of DEBtool.
Although DEBtool continues to expand, many implications of DEB theory will remain beyond the capacities of this package.

DEBtool is used in the DEB tele-courses and is freely available via GitHub, see DEB laboratory (Octave and Matlab versions)

This release focuses on

relationships between variables, as modified by parameter values
extracting parameter values from data and testing model predictions

Installation & start

Matlab is commercial and has a large users group. Matlab is very expensive, wants to check license numbers frequently on the web. The student version is much less expensive and will do for most purposes. Matlab versions are available for Unix, Windows and McIntosh. See also Mathtools for additional information. Some of DEBtool's functions can be computationally intensive; reduce Matlab's priority by priority('l'). This routine is included in DEBtool.

The Matlab package is accessable via GitHub

Octave can be down-loaded freely; it runs under Linux, Unix and Windows 95/98/2000/NT/XP/Vista/10, see `Windows installer' on the linked page.. Although it is possible to run Octave 3.2.4 directly in the Octave Window, can best be run under

Emacs 23.1, freely downloadable from http://ftp.gnu.org/gnu/emacs/windows/ (emacs-23.1-bin-i386.zip) . Install it by adding the emacs-23.1 folder under Program Files under Windows and run the addxpm.exe file in the bin directory of emacs-23.1 to add an emacs-icon in the start menu. Start Octave under Emacs by Alt-x run-octave, after making sure that Emacs and Octave are added to the path of Windows. The path under Windows can edited by right-clicking on "Computer" under "the start-menu", and select "properties", and then "advanced systems settings". You will then see an increadibly long path in an increadibly small window that can be edited.
Octave GUI in Qt 4.6 - QOcTerm, freely downloadble from http://sourceforge.net/, using an interface that is similar to that of Matlab. To find it, type "QOC Term", in the search-window of the sourceforge-entry-page. You just copy the directory with the executable under "C:/Program Files", for instance, make a coupling to your desktop, activate by double clicking and walk in the Term-tab to the place where you want to work; cd(return) brings you on top of your user-directory.

Octave uses Gnuplot for graphics. If the Gnuplot window freezes after sending a plot command, type in the Octave window: pkg rebuild -noauto oct2mat, press return and restart octave.

The Octave package is accessable via GitHub, but is no longer maintained

Maintenance & updates

New versions of any function are only indicated by the creation date and/or modification dates in the file headers. The changes are visible in GitHub.

Local manual

The manual for DEBtool is included in the package in subdirectory DEBtool/manual and is written in HTML. To read it, run a browser on file index.html.

Use and recommendations

Basic-level use

Octave and Matlab have a very similar syntax, but small differences do exist. The first steps in Octave are explained in separate notes . A useful short introduction to Matlab is: Knight, A. 2000 Basics of Matlab and Beyond, Chapman & Hall/CRC, 202 pp. A full manual of Octave is: Eaton, J. W., Batemen, D. and Hauberg, S. 2008 GNU Octave Manual, Version 3, Network Theory Limited, 555 pp. An electronic manual is on the web.

Don't work in DEBtool, but set a path to it

It is best to work in the subdirectory that has your own data and routines, and make a path to DEBtool. If you have this just besides DEBtool you set the path to DEBtool and all its subdirectories by addpath(genpath('../DEBtool_O/')) in Octave or in the menu-bar in Matlab. Use pwd under Octave or Matlab for getting the current prosition in to directory-tree, and ls for the list of files in the current directory. Use cd for changing directories, where .. means the parent-directory. Example if you are in a sister-directory of DEBtool: cd ../DEBtool/animal/ will bring you to toolbox animal.

The routines in each subdirectory can call other routines from that subdirectory, or from the library DEBtool/lib, which has three subdirectories.

Rename functions if you modify them

Since DEBtool is updated every now and then, existing routines can be changed. If you modified a function, and want to install a new version of DEBtool, it can save a lot of work if your modified functions have other names and have been stored outside DEBtool.

Erase variables

Do not forget to type clear all after switching toolboxes. No error messages are given if you do it otherwise, but the effect is not what you want it to be. So if you are in alga and type cd ../plant, continue with clear all; plant, for instance.

The plot ranges of DEBtools' plotting routines are set without notice, when you use the routines for the first time. Clear them by either use clear, or the 'default' option in the *_option routines. See under the manual under library.

Recalculate optimisation results from different start values

Always remember that optimization results contain local extremes at best, and that a local extreme might differ from the global extreme. Try different starting values, and check the results by making plots. See instructions under DEBtool/lib/nrregr.

Nomenclature

mydata_*.m The practical application of many DEBtool functions is illustrated with mydata-files, i.e. script files with the name mydata_filename.m. This information is supplementary to that in this manual. You can change these files according to your own needs.
sh*.m Routines that produce and show plots are called shfilename.m files.
d*.m Routines that specify differential equations are called d*.m; they are frequently subroutines of *.
pars_*.m Parameter values that are use in de demo's are specified in pars.m files; the notation follows the DEB-book, and explanations are given in the file. A demo is a script-file with a name equal to its toolbox (i.e. directory).

Logo

The logo, designed by Hugo van den Berg, represents a three-dimensional object, such that the projections in three directions give the symbols A, M and G. These symbols stand for the three basic energy fluxes Assimilation, Maintenance and Growth, which together organize all mass fluxes. Later in the development of the DEB theory, maintenance was replaced by dissipation to include development and other dissipating fluxes.

Acknowledgements

This work is the product of intensive collaboration between DEB-enthousiasts, e.g. the AQUAdeb group and especially the people in the Department of Theoretical Biology of the Vrije Universiteit, Amsterdam.

Go to the DEB information page or the DEB laboratory