efmtool — Elementary Flux Mode Tool

The efmtool computes elementary flux modes (EFMs) of metabolic networks. It is implemented in Java and has been integrated into MATLAB (see http://www.mathworks.com).

EFM computation is a special case of extreme ray enumeration of polyhedral cones. You might also want to consider polco, a tool for general polyhedral computations.

News & Current Version

Current version: 4.7.1 (4-Dec-2009)

Licence

Redistribution and use in source and binary forms, with or without
modification, are permitted provided agreeing to the Simplified BSD Style License.

• License
  
• Read about Simplified BSD Style License at http://www.opensource.org
  

Download & Installation

• Download & unzip the efmtool.zip file (an efmtool directory will be created)
• Change current directory to the newly created efmtool directory
  
• Start MATLAB from efmtool directory, with Java Virtual Machine enabled (default)

Documentation & Sources

Invoking EFM computation

• Call the function CalculateFluxModes
  
• Note: different input formats are supported, including SBML (see below)

API / Javadoc & Source files

• Javadoc of the API is available online
• The metabolic-efm-all-src.jar bundle contains the Java source files.
• Sample classes showing how to call the efmtool from Java are available in the ch.javasoft.metabolic.efm.sample package. They can be found in the above source files and are also documented in the javadoc API (click on class names to see sources).

Libraries

• javasoft.ch own development for numeric & matrix computations, a simple Java database, logging etc.
• Apache POI API to access Microsoft format files, for instance to read and write MS Excel files
• dom4j easy to use library for XML, XPath and XSLT
• jaxen XPath library
• JUnit framework to write repeatable tests
• JMatIO Matlab's MAT-file I/O API in pure Java, supports Matlab 5 MAT-flie format reading and writing

References

1. Terzer, M. and Stelling, J., "Large scale computation of elementary flux modes with bit pattern trees", Bioinformatics, July 28, 2008. doi:10.1093/bioinformatics/btn401
2. Terzer, M. and Stelling, J., "Accelerating the Computation of Elementary Modes Using Pattern Trees.", Algorithms in Bioinformatics, WABI 2006, Zurich, pages 333ff, ISBN 3-540-39583-0

FAQ / HowTo

1. How can i increase the heap memory of the MATLAB Java Virtual Machine (JVM), e.g. because a OutOfMemoryError occurs?
   → if matlab is started from within the efmtool directory, the efmtool/java.opts file is used, specifying the virtual machine memory options. To increase the memory, change the file accordingly.
   → see http://www.mathworks.com/support/solutions/data/1-18I2C.html
2. Can the tool be used without MATLAB?
   → Yes, the MATLAB integration is just a thin wrapper around the Java tool.
   → Sample code showing how to use the tool is available here
   → Javadoc of the API is available here
3. Are source files available for the efmtool?
   → Yes, either click on the class/interface name in the javadoc of the API
   → or download metabolic-efm-all-src.jar containing the Java source files corresponding to the classes in metabolic-efm-all.jar file (see efmtool/lib directory).

Samples

By stoichiometry

(example from "System Modeling in Cellular Biology: From Concepts to Nuts and Bolts", section "Stoichiometric and Constraint Based Modeling", MIT Press, ISBN-10:0-262-19548-8 / ISBN-13:978-0-262-19548-5)

stru.stoich=[

1 , 0 , 0 , 0 ,-1 ,-1 ,-1 , 0 , 0 , 0

0 , 1 , 0 , 0 , 1 , 0 , 0 ,-1 ,-1 , 0

0 , 0 , 0 , 0 , 0 , 1 , 0 , 1 , 0 ,-1

0 , 0 , 0 , 0 , 0 , 0 , 1 , 0 , 0 ,-1

0 , 0 , 0 ,-1 , 0 , 0 , 0 , 0 , 0 , 1

0 , 0 ,-1 , 0 , 0 , 0 , 0 , 0 , 1 , 1

];

stru.reversibilities=[0 1 0 0 0 0 0 1 0 0];

mnet = CalculateFluxModes(stru)

This example results the following 8 elementary modes:

efms=[

0 1 2  1  1 2  1 1

1 1 0 -1 -1 0  0 0

1 1 1  0  0 1  1 1

0 1 1  0  0 1  0 0

0 0 0  0  1 1  0 1

0 0 1  1  0 0  1 0

0 1 1  0  0 1  0 0

0 1 0 -1  0 1 -1 0

1 0 0  0  0 0  1 1

0 1 1  0  0 1  0 0

];

Stoichiometry with reaction/metabolite names

Add the reaction and metabolite names to the struct above, e.g.

stru.metaboliteNames = {'A', 'B', 'C', 'D', 'E', 'P'};

stru.reactionNames   = {'R1', 'R2', 'R3', 'R4', 'R5', 'R6', 'R7', 'R8', 'R9', 'R10'};

The names will be reflected in the output structure (e.g. in the reaction formulas).

By reaction formulas

The tool also directly parses reaction formulas:

rformulas = {

'--> A'

'<--> B'

'P -->'

'E -->'

'A --> B'

'A --> C'

'A --> D'

'B <--> C'

'B --> P'

'C + D --> E + P'

};

mnet = CalculateFluxModes(rformulas)

Note that also (Palsson-like) formulas with compartments are supported, e.g.

[c]ala-L <==> ala-D

(3) h[e] + (2) na1[c] --> (3) h[c] + (2) na1[e]

Currently, only the following compartments are supported:

[c] : cytosol    [e] : extracellular    [g] : Golgi appratus    [m] : mitochondrion    [n] : nucleus    [r] : endoplasmic reticulum    [v] : vacoule    [x] : peroxisome

SBML Files

SBML files are directly parsed, a sample call looks like this:

mnet = CalculateFluxModes('c:\sbmlfiles\Yeast_sbml.xml', false, 'external')

Options

Various options are available. For instance

• exact arithmetic is used
• output vectors are normalized to length 1 and
• verbose output level FINE is used

by specifying the following options:

...

opts = CreateFluxModeOpts('arithmetic', 'fractional', 'normalize', 'norm2', 'level', 'FINE');

mnet = CalculateFluxModes(stru, opts)

Note that the options argument opts is always the last input argument. All options are described on the help page, i.e. type

help CreateFluxModeOpts

BUGS & Feature Requests

BUGS

The following bugs are known and should (according to the severity/priority) be fixed in the next or a subsequent efmtool version:

1. Out-core memory option does not work. Standard in-core computation is not affected.
   Version: fixed in version V2.33.00
   Workaround: none
   Prio: 1
2. Duplicate-gene compression is buggy. This compression option is switched off by default, thus standard computations are not affected. Still, for networks with such reactions, the option would be helpful.
   Workaround: don't use this option, remove duplicate gene reactions manually
   Prio: 2
3. If reactions are enforced, using the ''enforce'' option, an exception similar to this one might occur:
   

   RuntimeException: no replacement row found with non-zero pivot to reastablish row-echelon form of kernel matrix for row 1.

   Implementation note: the error occurs since the initial kernel matrix has not full column rank due to the enforced reactions
   Workaround: enforce fewer reactions, and filter the elementary modes manually after the computation
   Prio: 3

4. SignToDouble function fails with an error message like the following: "non-unique double expansion for efm 7, found 0 expansions: zeros(7,0)"
   Workaround: use how option 'r' or 's' instead of the default value 'q'
   Prio: 3
5. If the input matrix is a zero matrix (no rows), an ArrayIndexOutOfBoundsException occurs. This is quite an artificial case, but it might occur if an external preprocessing step takes care of the network compression.
   Workaround: none
   Prio: 3
6. Old efm*.mat files are not deleted. Does not affect normal computations
   Version: fixed in version V2.33.00
   Workaround: none
   Prio: 3

Planned new features

1. A new sign-only option, such that only directions of reaction fluxes are exported (+1/-1/0 for forward/reverse/zero flux). For many applications, these flux patterns are sufficient. The option has the following advantages:
   → post-processing step is faster (no conversion from binary to numeric)
   → the resulting matlab files are smaller, since int8 is used instead of double
   Version: implemented in version V2.33.00
   Prio: 1
2. Integration of the tool into GNU Octave
   Prio: 2
3. A new external-jvm option, such that no MATLAB classpath variables are manipulated. This has the following advantages:
   → virtual machine options can be changed without the need to restart MATLAB (to change java.opts)
   → the virtual machine can be killed without affecting MATLAB
   → the MATLAB classpath initialization process can trigger 'clear java' which implies clear all, and global variables are deleted.
   Prio: 2
   

Input Formats

Typing

help CalculateFluxModes

shows how to call the function for various input formats.

For the most common formats, a sample call is given in the Samples section above.

References

• Terzer, M. "Large scale methods to enumerate extreme rays and elementary modes", PhD Thesis 2009, ETH e-collection, Book at Lulu: B/W, Color
• Terzer, M. and Stelling, J., "Parallel Extreme Ray and Pathway Computation", PPAM 2009 Conference, Wroclaw, Poland (accepted)
• Terzer, M. and Stelling, J., "Large scale computation of elementary flux modes with bit pattern trees", Bioinformatics, July 28, 2008. doi:10.1093/bioinformatics/btn401
• Terzer, M. and Stelling, J., "Accelerating the Computation of Elementary Modes Using Pattern Trees.", Algorithms in Bioinformatics, WABI 2006, Zurich, pages 333ff, ISBN 3-540-39583-0