Purpose

This version of Metatool consists partly of script
files which are compatible with octave and Matlab and partly of
shared libraries that are specific for the operating system and math
program. In principle the script files provide all necessary
functionality, but usage of the shared libraries 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

the shared libraries provide a very fast algorithm for the
calculation of elementary modes (look at this
poster for further information; more information about the networks
used for this poster and some input files are here)

if all the stoichiometric coefficients are integers, the
elementary modes and most other results will automatically be computed
on an integer basis; otherwise, calculations will use floating point
numbers

Installation

Extract the common files (common-files.tar.gz)
and platform/program
specific files (see table below) into one directory. Do not mix the
specific files for the different math programs in one directory.

If you want to use the Metatool
option for calculation of elementary
modes in FluxAnalyzer, you need to download the appropriate
MATLAB-specific files for your operating system. Then extract the
elmo.* shared library from the archive and copy it into the main
installation directory of FluxAnalyzer. In addition, you have to put
the kernel.m function from the common files into this directory.

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:

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

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:

Known problems

Determination of math
program fails

Because octave and Matlab are not 100% compatible, there are some
parts
in the scripts where it is necessary to determine which math program is
used. This is done by setting the global variable 'MATH_PROGRAM' to '0'
for octave and '1' for Matlab. However, there are slight differences in
the various octave and Matlab versions concerning the declaration and
definition of global variables. As a result, the determination of the
math program can fail leading to different consecutive errors. If you
encounter an error when running Metatool, set the global variable
'MATH_PROGRAM' manually and retry. In order to do this, you first have
to declare:

global MATH_PROGRAM

and then assign this variable '0' if you are using octave and '1' if
you are using Matlab.

Parsing of Metatool
input file fails

The Metatool input files are in ASCII format and it is essential
that
the linefeed encoding used by them corresponds to conventions of the
operating system you are working on. To convert between UNIX and DOS
formats use the unix2dos and dos2unix utilities. In addition, the last line in
the input file must end with a linefeed.

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