miom 0.9.0b1

Mixed Integer Optimization for Metabolism

Introduction

https://metexplore.github.io/miom

MIOM (Mixed Integer Optimization for Metabolism) is a python library for creating and solving complex optimization problems using genome-scale metabolic networks, in just a few lines.

MIOM offers a high-level API that leverages the power of modern Mixed Integer Optimization (MIO) solvers to easily define steady-state metabolic optimization problems, from simple Flux Balance Analysis (FBA) simulations, to more complex problems, such as sparse FBA or context-specific reconstruction problems, and solve them the required level of optimality.

MIOM uses the PICOS and the Python-MIP libraries to build and solve the optimization problems using many commercial, academic and free solvers. It is also compatible and complementary to cobrapy.

Here is an example of how to implement FBA and Sparse FBA to maximize flux through the biomass reaction in the Recon3D model with MIOM:

import miom

model = (miom
        .load('@BiGG/Recon3D.miom')
        .steady_state()
        .set_rxn_objective('biomass_reaction')
        .solve(verbosity=1))

print("Optimal flux:", model.get_fluxes('biomass_reaction'))
print("Number of active reactions:", sum(abs(model.get_fluxes()) > 1e-8))

# Minimize the number of reactions preserving the optimal flux
V, X = (model
        .setup(opt_tol=0.05)
        .set_fluxes_for('biomass_reaction')
        .subset_selection(-1)
        .solve(verbosity=1)
        .get_values())

print("Number of active reactions:", sum(abs(V) > 1e-8))

NOTE: This library is functional but still in a very early stage. API is still not stable and might be changed in future versions.

Installation

Minimal install

By default, MIOM comes with support for COIN-OR CBC solver and GLPK using the swiglpk wrapper. To install MIOM with minimal dependencies, run:

pip install miom

Full install

The full install option of miom comes also with the interfaces for Gurobi and Mosek. Also, in order to be able to import metabolic networks in different formats (SBML, Matlab, YAML, etc), you need to install the additional cobra and scipy packages:

pip install miom[all] cobra scipy

CPLEX is also supported, but requires a valid license. To install MIOM with CPLEX support, follow the instructions on the CPLEX page to install your current version of cplex in your python environment.

Quick start

The first step is to import a GEM (a genome-scale model) using the miom.mio.load_gem method. The method accepts a local file or an URL. SBML files and Matlab files are supported through cobra and scipy packages. Please make sure that these packages are correctly installed before trying to import models in these formats (see Full install).

Once these packages are available, you can import a model using:

import miom
network = miom.mio.load_gem("https://github.com/SysBioChalmers/Human-GEM/raw/main/model/Human-GEM.mat")
print("Number of reactions in the network", network.num_reactions)

MIOM includes its own lightweight and portable format (.miom) for loading and storing metabolic networks, which does not require any additional dependency. This models uses numpy compressed structured arrays to store the basic information of the metabolic networks required for performing simulations. This format is even smaller and more portable than the Matlab files. A repository of converted models is available at https://github.com/pablormier/miom-gems.

To make things even easier, the method load_gem can import any model from this repository using the relative path, for example:

human1 = miom.mio.load_gem("@SysBioChalmers/Human-GEM.miom")
recon3d = miom.mio.load_gem("@BiGG/Human-GEM.miom")

Here is an example of how to load a metabolic network and maximize the flux through a target reaction using FBA, and then how to modify the original problem to implement the sparse FBA problem adding only a few lines to the original problem:

import miom

network = miom.mio.load_gem("@mus_musculus_iMM1865.miom")
target_rxn = "BIOMASS_reaction"

# Create the optimization problem with miom and solve
model = (miom
        .load(network)
        .steady_state()
        .set_rxn_objective(target_rxn)
        .solve(verbosity=1))

print("Optimal flux:", model.get_fluxes(target_rxn), "mmol/(h·gDW)")

# Show reactions with non-zero flux
V, X = model.get_values()
print("Number of reactions active reactions:", sum(abs(V) > 1e-8))

Optimal flux: 798.8110517749975 mmol/(h·gDW)
Number of active reactions: 2549

Now, modify the original problem to solve the sparse FBA problem, minimizing the number of reactions with non-zero flux that can lead to the optimal possible flux through the target reaction. This can be easily done by transforming the FBA problem into a subset selection problem, where each reaction has a negative weight and the goal is to remove as many negative weighted reactions as possible. Note that since each reaction has the same weight (-1), all reactions are equally important in the optimization problem:

Note: To better understand the meaning of each step, please read the documentation of the BaseModel class, and the complete example in examples/sparse_fba.py.

V, X = (model
        # Set the MIP Gap tolerance to 5%, using the default solver
        # (COIN-OR CBC included with the Python-MIP lib)
        .setup(opt_tol=0.05, verbosity=1)
        # Set the fluxes to the optimal value found
        .set_fluxes_for('BIOMASS_reaction')
        # Transform to a subset selection problem
        # adding a negative weight to all reactions
        # (to remove them from the final solution)
        .subset_selection(-1)
        # Solve the MIO problem
        .solve()
        # Get continuos vars (fluxes) and binary vars
        .get_values())

# Show reactions with non-zero flux
print("Number of active reactions:", sum(abs(V) > 1e-8))

Number of active reactions: 404

Solving this problem with default COIN-OR CBC solver returns a solution with 404 active reactions (much less than the 2549 reactions obtained with FBA, and less than the 433 reactions returned by the CappedL1 approximation in the sparseFBA implementation in Matlab), with a relative gap between the lower and upper objective bound below 5% (as indicated in the setup method):

Cbc0011I Exiting as integer gap of 122.04538 less than 1e-10 or 5%
Cbc0001I Search completed - best objective -10208, took 0 iterations and 0 nodes (28.34 seconds)
Cbc0035I Maximum depth 0, 0 variables fixed on reduced cost
Total time (CPU seconds):       60.79   (Wallclock seconds):       60.79

The concise API provided by MIOM makes everything explicit: the sparse FBA problem can be implemented as a best subset selection problem of reactions (minimize the number of reactions with non-zero flux) subject to the steady-state constraint and the optimality constraint of the flux for the target reaction (in this case the BIOMASS_reaction). Using this formulation, you can take advantage of modern solvers like CPLEX, GUROBI, MOSEK, COIN-OR CBC (among others) to obtain an optimal or an approximate solution, controlled by the opt_tol parameter.

To use other solvers, you only need to provide the specific solver to the miom method, for example:

model = (miom
        .load('@BiGG/Recon3D.miom', solver=miom.Solvers.GLPK)
        .steady_state()
        .set_rxn_objective('biomass_reaction')
        .solve(verbosity=1))

Advantages

• It's easy to use: MIOM uses the PICOS and the Python-MIP libraries, which means you can use any solver supported by those libraries.
• It's easy to extend: MIOM is written in pure python, so you can easily extend it to solve more complex optimization problems.
• It makes the problem explicit: MIOM uses a declarative way to express the problem, so you can easily read and understand what you are solving and differences between algorithms.
• It's fast: MIOM leverages the power of MIO solvers to solve complex optimization problems. You can control the quality and speed of the solutions for your problem and get better solutions that the approximations (LP) of the original problem available in other constraint-based modeling libraries.
• It's lightweight: The library has a small number of dependencies, so it's easy to install and distribute also in HPC environments.
• It includes a compressed GEM format: MIOM can load and save the minimal information of the metabolic networks required for performing simulations into a compressed file compatible with numpy. The small size of the files allows you to quickly run online experiments so other people can reproduce your results. It also supports SBML and matlab formats if cobratoolbox is installed.
• It's open-source: MIOM is open-source and free to use. You can contribute to the development of MIOM by forking the repository and sending pull requests.

Documentation

The documentation of the library can be found at https://metexplore.github.io/miom/

How to cite

Manuscript in progress

License

GNU General Public License v3.0