METATOOL 5.1 for GNU octave and MATLAB

Purpose

This version of Metatool consists mainly of script files which are compatible with octave and Matlab and can optionally use a shared libary that is specific for the operating system and math program. In principle the script files provide all necessary functionality, but usage of the shared library makes elementary mode calculation far more efficient. The purpose of this distribution is to make the operations performed by Metatool more easily understandable and to allow the users to quickly adapt and extend the scripts according to their needs. Caveat: Due to currently sparse documentation and too few commentaries in the scripts this may not be so easy after all.

Features

Installation

Extract the script files (script-files.tar.gz) and optionally the appropriate shared library (elmo.*) into one directory. Note that all shared libraries were compiled for the 32-bit variant of the respective OS.


GNU octave 3.0 or higher
MATLAB 7 or higher
Linux x86 elmo.oct.gz elmo.mexglx.gz
Windows n/a elmo.dll.zip
Intel Mac
n/a
elmo.mexmaci.gz

The Linux library requires libstdc++.so.6 and libc.so.6 as well as some other standard libraries (type e.g. 'ldd elmo.oct' for the octave installation to check if all dependencies are resolved).

Metatool for CellNetAnalyzer

The most recent Metatool modules are now distributed together with the CellNetAnalyzer.

Usage

Using standard Metatool input files

The standard Metatool input format is described here. Start your math program and cd into the directory where you have placed the files (or tell the program to include the directory in its search path). Then execute:

ex= parse('example.dat');

This will read the input file and store its content into several fields of the data structure 'ex' (the field names are: 'st', 'irrev_react', 'ext', 'ext_met', 'int_met', 'react_name'; cf. table below). If you get an error when executing this command, look in the known problems section below. The 'parse' command alone is useful when you want to manipulate the input data before the calculations. You can now call

ex= metatool(ex);

to perform the calculations or if you want both steps in one go you can directly call

ex= metatool('example.dat');

This will perform most of the operations that the stand-alone Metatool does and stores the results in the variable 'ex'. If you run metatool with a second argument as in

ex= metatool('example.dat', 'example.out');

then it will produce an ouput file similar to the one of the stand-alone version. There are two drawbacks with this kind of output: First, it is not possible to load this output later again. Second, for large systems the process of writing this file is very time-consuming. Therefore it is often better to use the built-in functions of the math program to save and load your data.
The variable 'ex' (or whatever you choose to call it) is a structure that contains several fields, the most important of which are:

st stoichiometric matrix (rows correspond to internal metabolites, columns to reactions)
irrev_react row vector which contains 0 for a reversible and 1 for an irreversible reaction
kn kernel (nullspace) of the stoichiometric matrix
sub subset matrix (rows correspond to the subsets, columns to the reactions in st)
rd reduced system
irrev_rd reversibility of the subsets in the reduced system
rd_ems elementary modes of the reduced system (rows correspond to the subsets, columns are elementary modes)
irrev_ems row vector which contains 0 for a reversible and 1 for an irreversible elementary mode
ext same structure as st, but rows correspond to external metabolites
int_met names of the internal metabolites
ext_met names of the external metabolites
react_name names of the reactions

The fields in bold print are those wich are created by reading an input file or converting a SBML model. The other fields contain the results of calculations.
When you call metatool with a second argument so that an output file is produced, there will also be a field calles 'ems' in the return variable. This field contains the elementary modes of the full system. When you run metatool without producing an output file, the elementary modes for the full system are not produced. The reason for this is to save memory since the the number of elementary modes in large/complex networks can explode. If you want to expand the elementary modes to the original system do this:

ex.ems= ex.sub' * ex.rd_ems;

Of course, this will produce one large matrix. But you can also choose which modes to expand by using the standard indexing mechanisms (cf. math program documentation), e.g.

ems_part= ex.sub' * ex.rd_ems(:, 1:10);

will only expand the first ten elementary modes. To examine the numerical quality of the result you can look at something likes this:

max(max(abs(ex.rd * ex.rd_ems)))

Ideally, the result should be zero or a very small number. If all your stoichiometric coefficients were integers and the result is not 0, something went wrong.

Using a stoichiometric matrix directly

In case you don't have your network as a metatool input file but want to calculate the elementary modes for a stoichiometric matrix directly, this is also possible. You simply have to set up a variable with the two fields 'st' and 'irrev_react' in the same way as described in the table above. Here is an example how to calculate the elementary modes of a network with two metabolites and four reactions:

net.st= [1 1 -1 0; 0 0 1 -1];
net.irrev_react= [1 0 1 1];
net= metatool(net);

After calculation, net.rd_ems contains the elementary modes of the reduced system. Since no reaction and metabolite names were given, no metatool output file can be produced.

Using a SBML model

If you want to use a model that is available in SBML format you first need to convert the SBML file into a data structure that is accessible within your math program. This can be done with the SBML toolbox which provides a command (TranslateSBML) that reads a SBML file and returns a struct variable. However, installation of this toolbox may require some effort. The first step in loading a SBML model is then to call:

mySBMLmodel= TranslateSBML('mySBMLfile.xml');

The result can then be convertet into a struct variable that can be used by Metatool with:

myMetatoolModel= sbmlModel2metatool(mySBMLmodel);

During the execution of this command you will be asked for every compartment in the model whether or not the metabolites that it contains should be considered as external. Finally, you can calculate the elementary modes with:

myMetatoolModel= metatool(myMetatoolModel);

After calculation, net.rd_ems contains the elementary modes of the reduced system. Because reaction and metabolite names were copied from the SBML model, a metatool output file can additionally be produced.

Documentation (click here)

Known problems

Currently none.

Selected publications

A. von Kamp and S. Schuster: Metatool 5.0: fast and flexible elementary modes analysis. Bioinformatics 22 (15), 2006, 1930-1931. Full text article at bioinformatics.oupjournals.org

S. Klamt, J. Gagneur and A. von Kamp: Algorithmic approaches for computing elementary modes in large biochemical reaction networks. IEE Proceedings Systems Biology 2005, 152 (4), 249-255.

T. Pfeiffer, I. Sánchez-Valdenebro, J. C. Nuño, F. Montero and S. Schuster: METATOOL: For Studying Metabolic Networks. Bioinformatics 15, 1999, 251-257 (describes important concepts, but not the current implementation).

S. Schuster, D. Fell and T. Dandekar: A General Definition of Metabolic Pathways Useful for Systematic Organization and Analysis of Complex Metabolic Networks. Nature Biotechnology 18 (3), 2000, 326-332. PubMed (general introduction to elementary modes analysis; the algorithm described in this paper is not used for the current implementation).

R. Urbanczik, C. Wagner:An improved algorithm for stoichiometric network analysis: theory and applications. Bioinformatics  21, 2005, 1203-1210 (basis for the null space algorithm used in the current implementation).

Feedback

If you have any questions or comments and especially when you encounter errors please tell
email address

Last updated: 28.5.2008