Index
COBRA-k stands for "Constraint-Based Reconstruction and Analysis (COBRA) with kinetics" [Paper], a generalized variant of the metabolic modeling framework known as COBRA. Both frameworks allow one to analyze constraint-based metabolic models with the help of optimization approaches. While COBRA uses exclusively linear constraints to describe steady state flux distributions in a given metabolic network, COBRA-k expands COBRA by allowing also the integration of non-linear kinetic rate laws (herein we use reversible Michaelis-Menten kinetics). In particular, this enables also a consistent integration of (steady state) fluxes, metabolite concentration and enzyme abundances in COBRA models. While classical COBRA model are usually formulated as linear or mixed-integer linear program (LP / MILP), COBRA-k requires solving mixed-integer non-linear programs (MINLP).
The COBRA-k package is a general COBRA/COBRA-k suite written as a Python module, while also being the reference implementation of COBRA-k. Some of COBRA-k's major features are:
-
"Classical" COBRA methods such as:
- Flux Balance Analysis (FBA) [Review]
- Parsimonious Flux Balance Analysis (pFBA) [Paper]
- Flux Variability Analysis (FVA) [Paper] (written, as all other provided variability analyses, in a multi-core-parallelized way)
These standard methods can also optionally be treated in combination with general enzyme constraints and/or thermodynamic constraints, enabling methods such as:
You may also freely choose your constraints and objectives, allowing you to construct new COBRA methods.
-
COBRA-k methods operating on extended COBRA models with reversible Michaelis-Menten kinetics [Paper]:
- Our developed COBRA-k solver (combining a genetic algorithm with enzyme-constrained FBA + non-linear optimization) to solve also larger COBRA-k problems.
- A MINLP formulation that can be used in combination with global MINLP solvers (works only with small models).
Again, you can freely choose whether you want to enable enzymatic and/or thermodynamic constraints, even on the reaction level.
-
Automatic thermodynamic and/or enzyme-kinetic data retrieval for your model:
-
$k_{cat}$ (turnover numbers) and$K_M$ (Michaelis constants) using the databases SABIO-RK [Website] and BRENDA [Website] as well as taxonomic information from NCBI TAXONOMY [Website]; this retrieval algorithm is similar to the one used by AutoPACMEN [GitHub] -
$Δ_rG'°$ (standard reaction-based Gibb's free energies) using the fantastic eQuilibrator-API [GitLab] -
$W_i$ (molecular weights of enzymes) using Uniprot [Website] - Of course, you can also manually change or set any parameters at your will
-
-
Pretty-printing and exporting results:
- With the help of rich [GitHub], COBRA-k allows one to display colored tables of any COBRA(k) analysis results, as well as models themselves.
- As storage options, results can be saved and loaded as JSON text files, and also exported as XLSX spreadsheets.
- Results can also be directly exported as CNApy [GitHub] scenarios, making it possible to visualize them on interactive metabolic maps.
-
Interoperable loading, editing and saving of metabolic models:
- Metabolic models and their components (reactions, metabolites, enzymes and related parameters) can be freely constructed, changed and/or augmented using COBRA-k.
- Models can be imported and exported in the widely used SBML format [Site] with the help of COBRApy [GitHub]. Thereby, COBRA-k can store and reload any additional kinetic and/or thermodynamic information in SBML annotations. The SBML format is also used by other popular constraint-based packages for various programming languages.
- Additionally, models, model components and results can be quickly saved and loaded in COBRA-k's custom JSON format.
- Also, models with an associated COBRA-k solution can be directly exported as kinetic models in the Antimony and/or SBML format, making it possible to use them with popular kinetic systems biology packages such as Tellurium [GitHub] and COPASI [GitHub].
Programmatically, COBRA-k relies on the optimization framework pyomo [GitHub], making it compatible with any solver supported by it (see here in pyomo's documentation for more). For the conversion of COBRA-k models into kinetic models, Tellurium [GitHub] is used.
To give you a feel of how COBRA-k looks like, here's an enzyme-constrained thermodynamic Flux Balance Analysis (maximization of ATP_Consumption's reactions flux)
of the small toy model
described and visualized here in COBRA-k's documentation:
# Load COBRA-k functions
from cobrak.example_models import toy_model
from cobrak.lps import perform_lp_optimization
from cobrak.printing import print_optimization_result
# Run enzyme-constrained Flux Balance Analysis
lp_result: dict[str, float] = perform_lp_optimization(
cobrak_model=toy_model, # toy_model is an instance of COBRA-k's dataclass 'Model'
objective_target="ATP_Consumption",
objective_sense=+1,
with_enzyme_constraints=True,
with_thermodynamic_constraints=True,
)
# Pretty print enzyme-constrained Flux Balance Analysis result
print_optimization_result(
cobrak_model=toy_model,
optimization_dict=lp_result
)Regarding its programming philosophy, COBRA-k aims to be i) composable (e.g. all main classes are "just" dataclasses - also known as struct) and ii) explicitly typed (with some type checks provided by pydantic) thus trying to help you when coding in your favourite editor or IDE.
COBRA-k is provided as a PyPI package and can be installed through the following command:
pip install cobrakNote: If you encounter any trouble due to a missing SCIP installation (which may happen on some systems), you have to install the free and open-source mixed-integer linear solver SCIP on your system. To do so, follow the SCIP download instructions here or or, if no matching download is provided for your system, the compilation instructions here.
After the installation, which should just take a few minutes, the package can be imported as cobrak.
Also note that only the free and open-source solvers HiGHS (for linear (also mixed-integer) problems) and IPOPT (for linear and non-linear problems) - and on some systems, also automatically the solver SCIP - come pre-installed. For more on how to install other solvers, visit the respective documentation page here.
COBRA-k requires Python≥3.10, making it work on Python-3.10-compatible OS such as Windows, MacOS and Linux. Thereby, COBRA-k is mainly tested on Ubuntu on an x86-64 computer and on a MacBook with an ARM processor.
An introduction to using COBRA-k, including a tutorial with integrated quickstart sections, is provided through its documentation:
https://www.klamt-lab.github.io/COBRA-k/
Also, you may check out COBRA-k's standard examples, provided in the "examples" subfolder of this repository. They also contain all the files to reproduce the results of COBRA-k's publication, as also further explained in the respective chapter in COBRA-k's documentation.
If you encounter any issues with COBRA-k, don't hesitate to open a GitHub issue here:
https://github.com/klamt-lab/COBRA-k/issues
Or write an e-mail, which is provided on the COBRA-k package's main maintainer employer page profile.
You're welcome to contribute to COBRA-k :-), feel free to open pull requests. Keep in mind that you have to be ok with COBRA-k's open-source license (see next paragraph).
- Main folder: The PyPI descriptions and environment settings can be found in the main folder's "pyproject.toml" and "setup.py". The "mkdocs.yml" contains COBRA-k's documentation index and module settings.
- Subfolder "cobrak": Here, you can find all COBRA-k package Python functionalities
- Subfolder "docs": Contains the mkdocs Markdown text for COBRA-k's documentation
- Subfolder "examples": Contains all main COBRA-k examples, as mentioned in COBRA-k's publication; "examples/common_needed_external_resources" contains files that are used by multiple examples, and are created by the .py files in "examples" itself. For a short demo that usually takes only up to a minute, run and look at "examples/toymodel/run_toymodel_calculations.py".
- Subfolder "tests": Contains pytest tests for many COBRA-k functions; also imports the toymodel generation and analyses as test in "tests/test_toymodel.py"
In any code contribution, Python's mypy typing capabilities should be used (see this mypy cheat sheet). Also, ruff [GitHub] format is used for code formatting, together with the ruff linter import sorter. As testing framework for testable functions, pytest is used.
To set up a development environment, you may e.g. use uv [GitHub] as follows:
- Make sure you've installed uv and ruff:
pip install uv
uv pip install ruff
- Checkout the latest COBRA-k development version using git
git clone https://github.com/klamt-lan/COBRA-k.git
- (optional) Run the toy model example
cd COBRA-k
uv run examples/toymodel/run_toymodel_calculations.py
uv will automatically install a correct Python version ≥ 3.10 and COBRA-k dependencies.
- After code changes: Apply ruff
To maintain a consistent style, please apply ruff on you code before you create a pull request as follows (you may run these commands in COBRA-k's main folder):
ruff check --select I --fix
ruff format
ruff check
# All three commands can also be found in this reposiroty's format_code.sh
The first command sorts imports, the second one fixes code formatting. The third command tells you remaining issues that you have to change manually. If you want to deviate from ruff's rules, you can e.g. use a # noqa: $RULE_NAME command at the end of each affected line. This will make ruff ignore the found issue.
- After code changes: Test with pytest
If applicable, you are invited to write new or changed tests in COBRA-k's code. Tests are located in the "tests" subfolder and use pytest [GitHub] which you may install as follows:
uv pip install pytest
You can then run the tests in the "test" subfolder as follows:
pytest tests
Please make sure that your code changes do not unintendently break any tests. Also, you're invited to create tests for uncovered (untested) parts in COBRA-k's code of which there's still too much. To get a coverage report in a nice HTML, e.g. install coverage and pytest-cov as follows:
uv pip install coverage
uv pip install pytest-cov
...and create the nice HTML coverage report as follows (while being in COBRA-k's main folder):
pytest --cov=cobrak --cov-report=html
The resulting report can be found in the newly generated subfolder htmlcov.
To work on COBRA-k's documentation, you need mkdocs [GitHub] and some dependencies. To install them, you may run the following commands using uv:
uv pip install mkdocs
uv pip install mkdocs-material
uv pip install pymdown-extensions
uv pip install mkdocstrings[python]
To now self-run the documentation on a local server, you can use mkdocs itself with the following command in COBRA-k's main folder:
mkdocs serve
The documentation's text can be found in the *.mdMarkdown files in the docssubfolder. Note that the Markdown format uses the Material for mkdocs syntax expansions to the plain Markdown format.
COBRA-k is free and open-source and licensed under the Apache License, Version 2.0
Note that COBRA-k's documentation integrated the open-source JavaScript packages KaTeX [Link to its open-source license], iframe-worker [Link to its open-source license] and mermaid [Link to its open-source license].
Some of COBRA-k's code is also adapted and modified from AutoPACMEN [GitHub] and TCOSA [GitHub]. For both repositories, their main author is the same as the one of COBRA-k and both packages use the same license type as COBRA-k.
If you use COBRA-k in your academic work, please cite its publication:
- Bekiaris & Klamt, COBRA-k: A powerful framework bridging constraint-based and kinetic metabolic modeling. Sci. Adv. 12, eaeb3022 (2026). DOI:10.1126/sciadv.aeb3022