fbc_curation: FROG analysis in Python¶
The project fbc_curation implements the FROG analysis for reproducibility of constraint-based models in Python with code
available from https://github.com/matthiaskoenig/fbc_curation.
The documentation is available on https://fbc-curation.readthedocs.io.
If you have any questions or issues please open an issue.
Contents:
Introduction¶
The project fbc_curation implements the FROG analysis for reproducibility of constraint-based models in Python.
FROG can be run
- programmatically in python
- using the
runfrogcommand line tool available in this package - via the website https://runfrog.de
- via the REST API https://runfrog.de/docs
The FROG analysis creates standardized reference files for a given constraint-based computational model. The FROG files can be used in the model curation process for validating the model behavior, e.g., when submitting the model to BioModels. The latest version supports
fbc_curation provides two implementations of FROG using
- cobrapy based on COBRApy (Constraint-Based Reconstruction and Analysis in Python)
- cameo cameo based on Cameo (Computer Aided Metabolic Engineering and Optimization)
For more information see the following resources
- Documentation: https://fbc-curation.readthedocs.io
- Website: https://runfrog.de
- REST API: https://runfrog.de/docs
- FROG format: FROG version 1
- FROG JSON schema: frog-schema-version-1.json.
- Code: https://github.com/matthiaskoenig/fbc_curation
- FROG BioModels submission: https://www.ebi.ac.uk/biomodels/curation/fbc.
If you have any questions or issues please open an issue.
Installation¶
fbc_curation is available from pypi and
can be installed via:
pip install fbc-curation
The latest develop version can be installed via:
pip install git+https://github.com/matthiaskoenig/fbc-curation.git@develop
Run FROG¶
Command line tool¶
After installation FROG analysis can be performed using the runfrog command line tool
$ runfrog
──────────────────────────────────────────────────────────────────────────────────
🐸 FBC CURATION FROG ANALYSIS 🐸
Version 0.2.3 (https://github.com/matthiaskoenig/fbc_curation)
Citation https://doi.org/10.5281/zenodo.3708271
──────────────────────────────────────────────────────────────────────────────────
Usage: runfrog [options]
Options:
-h, --help show this help message and exit
-i INPUT_PATH, --input=INPUT_PATH
(required) path to COMBINE archive (OMEX) with SBML
model or an SBML model
-o OUTPUT_PATH, --output=OUTPUT_PATH
(required) omex output path to write FROG
──────────────────────────────────────────────────────────────────────────────────
Website¶
FROG can be easily executed via the website https://runfrog.de
REST API¶
FROG can be execute via the REST API https://runfrog.de/docs
Python¶
To run FROG programmatically via python use the run_frog function
from fbc_curation.worker import run_frog
run_frog(model_path, omex_path)
Here a complete example with comparison of the FROG results
"""FROG example using `fbc_curation`."""
from pathlib import Path
from fbc_curation.compare import FrogComparison
from fbc_curation.worker import run_frog
def create_frog(model_path: Path, omex_path: Path) -> None:
"""Create FROG report and writes OMEX for given model."""
# create FROG and write to COMBINE archive
run_frog(
source_path=model_path,
omex_path=omex_path,
)
# compare FROG results in created COMBINE archive
model_reports = FrogComparison.read_reports_from_omex(omex_path=omex_path)
for _, reports in model_reports.items():
FrogComparison.compare_reports(reports=reports)
if __name__ == "__main__":
base_path = Path(".")
create_frog(
model_path=base_path / "e_coli_core.xml",
omex_path=base_path / "e_coli_core_FROG.omex",
)
The typically output of a FROG analysis is depicted below
runfrog -i e_coli_core.xml -o e_coli_core.omex
───────────────────────────────────────────────────────────────────────────────────────
🐸 FBC CURATION FROG ANALYSIS 🐸
Version 0.2.3 (https://github.com/matthiaskoenig/fbc_curation)
Citation https://doi.org/10.5281/zenodo.3708271
───────────────────────────────────────────────────────────────────────────────────────
INFO Loading 'e_coli_core.xml' worker.py:70
WARNING Omex path 'e_coli_core.xml' is not a zip archive. omex.py:500
───────────────────────────────── FROG CuratorCobrapy ─────────────────────────────────
INFO * metadata curator.py:107
INFO * objectives curator.py:110
INFO * fva curator.py:113
INFO * reactiondeletions curator.py:116
INFO * genedeletions curator.py:119
INFO FROG created in '0.977' [s] worker.py:178
────────────────────────────────── FROG CuratorCameo ──────────────────────────────────
INFO * metadata curator.py:107
INFO * objectives curator.py:110
INFO * fva curator.py:113
INFO * reactiondeletions curator.py:116
INFO * genedeletions curator.py:119
INFO FROG created in '1.219' [s] worker.py:178
───────────────────────────────────── Write OMEX ──────────────────────────────────────
WARNING Existing omex is overwritten: 'e_coli_core.omex' omex.py:680
INFO Reports in omex: compare.py:60
{'./e_coli_core.xml': ['cobrapy', 'cobrapy_tsv', 'cameo',
'cameo_tsv']}
────────────────────────────── Comparison of FROGReports ──────────────────────────────
--- objective ---
cobrapy cobrapy_tsv cameo cameo_tsv
cobrapy 1 1 1 1
cobrapy_tsv 1 1 1 1
cameo 1 1 1 1
cameo_tsv 1 1 1 1
--- fva ---
cobrapy cobrapy_tsv cameo cameo_tsv
cobrapy 1 1 1 1
cobrapy_tsv 1 1 1 1
cameo 1 1 1 1
cameo_tsv 1 1 1 1
--- reaction_deletion ---
cobrapy cobrapy_tsv cameo cameo_tsv
cobrapy 1 1 1 1
cobrapy_tsv 1 1 1 1
cameo 1 1 1 1
cameo_tsv 1 1 1 1
--- gene_deletion ---
cobrapy cobrapy_tsv cameo cameo_tsv
cobrapy 1 1 1 1
cobrapy_tsv 1 1 1 1
cameo 1 1 1 1
cameo_tsv 1 1 1 1
───────────────────────────────────────────────────────────────────────────────────────
Equal: True
───────────────────────────────────────────────────────────────────────────────────────
License¶
- Source Code: LGPLv3
- Documentation: CC BY-SA 4.0
The fbc_curation source is released under both the GPL and LGPL licenses version 2 or
later. You may choose which license you choose to use the software under.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License or the GNU Lesser General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Funding¶
Matthias König is supported by the Federal Ministry of Education and Research (BMBF, Germany) within the research network Systems Medicine of the Liver (LiSyM, grant number 031L0054) and by the German Research Foundation (DFG) within the Research Unit Programme FOR 5151 “QuaLiPerF (Quantifying Liver Perfusion-Function Relationship in Complex Resection - A Systems Medicine Approach)” by grant number 436883643 and by grant number 465194077 (Priority Programme SPP 2311, Subproject SimLivA).
JSON Schema¶
The JSON schema for FROG version 1 is available from frog-schema-version-1.json
{
"title": "FrogReport",
"description": "Definition of the FROG standard.",
"type": "object",
"properties": {
"metadata": {
"$ref": "#/definitions/FrogMetaData"
},
"objectives": {
"$ref": "#/definitions/FrogObjectives"
},
"fva": {
"$ref": "#/definitions/FrogFVA"
},
"reaction_deletions": {
"$ref": "#/definitions/FrogReactionDeletions"
},
"gene_deletions": {
"$ref": "#/definitions/FrogGeneDeletions"
}
},
"required": [
"metadata",
"objectives",
"fva",
"reaction_deletions",
"gene_deletions"
],
"definitions": {
"Tool": {
"title": "Tool",
"description": "Tool description.",
"type": "object",
"properties": {
"name": {
"title": "Name",
"description": "Name of tool/software/library.",
"type": "string"
},
"version": {
"title": "Version",
"description": "Version of tool/software/library.",
"type": "string"
},
"url": {
"title": "Url",
"description": "URL of tool/software/library.",
"type": "string"
}
},
"required": [
"name"
]
},
"Creator": {
"title": "Creator",
"description": "Creator/curator in ModelHistory and other COMBINE formats.\n\nExtended by optional orcid.",
"type": "object",
"properties": {
"familyName": {
"title": "Familyname",
"type": "string"
},
"givenName": {
"title": "Givenname",
"type": "string"
},
"email": {
"title": "Email",
"type": "string"
},
"organization": {
"title": "Organization",
"type": "string"
},
"site": {
"title": "Site",
"type": "string"
},
"orcid": {
"title": "Orcid",
"type": "string"
}
},
"required": [
"familyName",
"givenName"
]
},
"FrogMetaData": {
"title": "FrogMetaData",
"description": "FROG metadata.",
"type": "object",
"properties": {
"model.location": {
"title": "Model.Location",
"description": "Location of the model in the COMBINE archive for which the FROG analysis was performed.",
"type": "string"
},
"model.md5": {
"title": "Model.Md5",
"description": "MD5 hash of model",
"type": "string"
},
"frog_id": {
"title": "Frog Id",
"description": "Id for the FROG analysis. All frog_ids within an archive must be unique.",
"type": "string"
},
"frog.software": {
"title": "Frog.Software",
"description": "Software used to run FROG (e.g. 'fbc_curation'",
"allOf": [
{
"$ref": "#/definitions/Tool"
}
]
},
"frog.curators": {
"title": "Frog.Curators",
"description": "Curators which executed the FROG analysis.",
"type": "array",
"items": {
"$ref": "#/definitions/Creator"
}
},
"software": {
"title": "Software",
"description": "Software used to run FBC (e.g. 'cameo', 'COBRA', 'cobrapy'",
"allOf": [
{
"$ref": "#/definitions/Tool"
}
]
},
"solver": {
"title": "Solver",
"description": "Solver used to solve LP problem (e.g. 'CPLEX', 'GUROBI', 'GLPK').",
"allOf": [
{
"$ref": "#/definitions/Tool"
}
]
},
"environment": {
"title": "Environment",
"description": "Execution environment such as Linux.",
"type": "string"
}
},
"required": [
"model.location",
"frog_id",
"frog.software",
"frog.curators",
"software",
"solver"
]
},
"StatusCode": {
"title": "StatusCode",
"description": "Status code for simulation results.",
"enum": [
"optimal",
"infeasible"
],
"type": "string"
},
"FrogObjective": {
"title": "FrogObjective",
"description": "Frog Objective.",
"type": "object",
"properties": {
"model": {
"title": "Model",
"type": "string"
},
"objective": {
"title": "Objective",
"type": "string"
},
"status": {
"$ref": "#/definitions/StatusCode"
},
"value": {
"title": "Value",
"type": "number"
}
},
"required": [
"model",
"objective",
"status",
"value"
]
},
"FrogObjectives": {
"title": "FrogObjectives",
"description": "Definition of FROG Objectives.",
"type": "object",
"properties": {
"objectives": {
"title": "Objectives",
"type": "array",
"items": {
"$ref": "#/definitions/FrogObjective"
}
}
},
"required": [
"objectives"
]
},
"FrogFVASingle": {
"title": "FrogFVASingle",
"description": "Frog FVA.",
"type": "object",
"properties": {
"model": {
"title": "Model",
"type": "string"
},
"objective": {
"title": "Objective",
"type": "string"
},
"reaction": {
"title": "Reaction",
"type": "string"
},
"flux": {
"title": "Flux",
"type": "number"
},
"status": {
"$ref": "#/definitions/StatusCode"
},
"minimum": {
"title": "Minimum",
"type": "number"
},
"maximum": {
"title": "Maximum",
"type": "number"
},
"fraction_optimum": {
"title": "Fraction Optimum",
"type": "number"
}
},
"required": [
"model",
"objective",
"reaction",
"status",
"fraction_optimum"
]
},
"FrogFVA": {
"title": "FrogFVA",
"description": "Definition of FROG FVA.",
"type": "object",
"properties": {
"fva": {
"title": "Fva",
"type": "array",
"items": {
"$ref": "#/definitions/FrogFVASingle"
}
}
},
"required": [
"fva"
]
},
"FrogReactionDeletion": {
"title": "FrogReactionDeletion",
"description": "Frog reaction deletion.",
"type": "object",
"properties": {
"model": {
"title": "Model",
"type": "string"
},
"objective": {
"title": "Objective",
"type": "string"
},
"reaction": {
"title": "Reaction",
"type": "string"
},
"status": {
"$ref": "#/definitions/StatusCode"
},
"value": {
"title": "Value",
"type": "number"
}
},
"required": [
"model",
"objective",
"reaction",
"status"
]
},
"FrogReactionDeletions": {
"title": "FrogReactionDeletions",
"description": "Definition of FROG Reaction deletions.",
"type": "object",
"properties": {
"deletions": {
"title": "Deletions",
"type": "array",
"items": {
"$ref": "#/definitions/FrogReactionDeletion"
}
}
},
"required": [
"deletions"
]
},
"FrogGeneDeletion": {
"title": "FrogGeneDeletion",
"description": "Frog gene deletion.",
"type": "object",
"properties": {
"model": {
"title": "Model",
"type": "string"
},
"objective": {
"title": "Objective",
"type": "string"
},
"gene": {
"title": "Gene",
"type": "string"
},
"status": {
"$ref": "#/definitions/StatusCode"
},
"value": {
"title": "Value",
"type": "number"
}
},
"required": [
"model",
"objective",
"gene",
"status"
]
},
"FrogGeneDeletions": {
"title": "FrogGeneDeletions",
"description": "Definition of FROG Gene deletions.",
"type": "object",
"properties": {
"deletions": {
"title": "Deletions",
"type": "array",
"items": {
"$ref": "#/definitions/FrogGeneDeletion"
}
}
},
"required": [
"deletions"
]
}
}
}
FROG files¶
In the following the four created reference files and the metadata file are described and examples provided for the e_coli_core.xml model. All output files are tab separated files (TSV) with the first three columns being model, objective, and status. The column model encodes the SBML model id. The column objective encodes the SBML objective id, which is the objective which was optimized in the respective simulation. The column status encodes the status of the simulation. The status can be either optimal (optimization worked) or infeasible (no solution found or problem in simulation).
Metadata file¶
A required metadata file metadata.json encodes information about the curation run and the used software and library. The information is documented at the JSON schema frog-schema-version-1.json <https://raw.githubusercontent.com/matthiaskoenig/fbc_curation/develop/src/fbc_curation/resources/schema/frog-schema-version-1.json>__
The following fields are required:
software.name(required): software used to create the reference files,software.version(required): software versionmodel.location(required): SBML model filenamesolver.name(required): solver used for optimization,solver.version(required): solver version
A concrete example of the metadata is shown below
{
"model_location": "./e_coli_core.xml",
"model_md5": "4574760460afe9e1b3388dc15f354706",
"frog_id": "cobrapy_tsv",
"frog_software": {
"name": "fbc_curation",
"version": "0.2.2",
"url": "https://doi.org/10.5281/zenodo.3708271"
},
"curators": [],
"software": {
"name": "cobrapy",
"version": "0.26.0",
"url": "https://github.com/opencobra/cobrapy"
},
"solver": {
"name": "glpk",
"version": "5.0",
"url": null
},
"environment": "posix, Linux, 5.15.0-53-generic"
}
01 Objective value¶
The objective value file 01_objective.tsv contains the four columns with the headers model, objective, status, and value. The model column stores the SBML model filename.
The value is the optimal value of the respective objective function when the model is optimized. If the status is infeasible, no value is provided, i.e., the value is empty.
model objective status value
./e_coli_core.xml obj optimal 0.8739215069684295
For an example file see e_coli_core/01_objective.tsv. For more information on how to simulate the FBA see https://cobrapy.readthedocs.io/en/latest/simulating.html.
02 Flux variability analysis (FVA)¶
The FVA file 02_fva.tsv contains six columns with the headers model, objective, reaction, flux, status, minimum and maximum. The model column stores the SBML model filename. The reaction column stores the SBML reaction id. The minimum and maximum columns contain the minimum and maximum values of the FVA. The rows are sorted based on the SBML reaction identifier. The status contains the status of the optimization (optimal or infeasible). If the status is infeasible the value is empty.
Flux variability is calculated with fraction_optimum = 1.0, i.e. the objective of the model is set to its maximum in secondary optimization (percent of optimum is 100%). The flux column stores the reference flux through the objective reaction which is objective_value * fraction_optimum. In case of fraction_optimum = 1.0 this is identical to the value in `01_objective.tsv
model objective reaction flux status minimum maximum fraction_optimum
./e_coli_core.xml obj R_ACALD 0.8739215069684295 optimal 1.1348525979450152e-14 0.0 1.0
./e_coli_core.xml obj R_ACALDt 0.8739215069684295 optimal 3.662182303830574e-15 0.0 1.0
./e_coli_core.xml obj R_ACKr 0.8739215069684295 optimal 0.0 0.0 1.0
./e_coli_core.xml obj R_ACONTa 0.8739215069684295 optimal 6.007249575350388 6.007249575350355 1.0
./e_coli_core.xml obj R_ACONTb 0.8739215069684295 optimal 6.007249575350388 6.007249575350264 1.0
./e_coli_core.xml obj R_ACt2r 0.8739215069684295 optimal 1.772023695401875e-14 0.0 1.0
./e_coli_core.xml obj R_ADK1 0.8739215069684295 optimal 0.0 -3.4583850794047745e-14 1.0
./e_coli_core.xml obj R_AKGDH 0.8739215069684295 optimal 5.064375661482467 5.0643756614820665 1.0
./e_coli_core.xml obj R_AKGt2r 0.8739215069684295 optimal 0.0 0.0 1.0
./e_coli_core.xml obj R_ALCD2x 0.8739215069684295 optimal 9.884200046617872e-15 0.0 1.0
./e_coli_core.xml obj R_ATPM 0.8739215069684295 optimal 8.39 8.389999999999924 1.0
./e_coli_core.xml obj R_ATPS4r 0.8739215069684295 optimal 45.51400977451763 45.514009774517376 1.0
./e_coli_core.xml obj R_BIOMASS_Ecoli_core_w_GAM 0.8739215069684295 optimal 0.873921506968431 0.8739215069684305 1.0
./e_coli_core.xml obj R_CO2t 0.8739215069684295 optimal -22.80983331020497 -22.80983331020505 1.0
...
See for instance: e_coli_core/02_fva.tsv. For more information: https://cobrapy.readthedocs.io/en/latest/simulating.html#Running-FVA
03 Gene deletions¶
The gene deletion file 03_gene_deletion.tsv contains five columns with the headers model, objective, gene, status and value. The model column stores the SBML model filename.
The gene column contains the SBML gene identifiers. The status and value columns contain the status of the optimization (optimal or infeasible) and optimal value under the given gene deletion. If the status is infeasible the value is empty. The rows are sorted based on gene identifier.
model objective gene status value
./e_coli_core.xml obj G_b0008 optimal 0.873921506968431
./e_coli_core.xml obj G_b0114 optimal 0.7966959254309566
./e_coli_core.xml obj G_b0115 optimal 0.7966959254309566
./e_coli_core.xml obj G_b0116 optimal 0.7823510529477393
./e_coli_core.xml obj G_b0118 optimal 0.8739215069684314
./e_coli_core.xml obj G_b0351 optimal 0.8739215069684306
./e_coli_core.xml obj G_b0356 optimal 0.873921506968431
...
./e_coli_core.xml obj G_b2415 infeasible NaN
./e_coli_core.xml obj G_b2416 infeasible NaN
...
See for instance: e_coli_core/03_gene_deletion.tsv. For more information: https://cobrapy.readthedocs.io/en/latest/deletions.html
04 Reaction deletions¶
The reaction deletion file 04_reaction_deletion.tsv contains five columns with the headers model, objective, reaction, status and value. The model column stores the SBML model filename.
The reaction column contains the SBML reaction identifiers. The status and value columns contain the status of the optimization (optimal or infeasible) and optimal value under the given reaction deletion. If the status is infeasible the value is empty. The rows are sorted based on reaction identifier.
model objective reaction status value
./e_coli_core.xml obj R_ACALD optimal 0.873921506968431
./e_coli_core.xml obj R_ACALDt optimal 0.873921506968431
./e_coli_core.xml obj R_ACKr optimal 0.8739215069684305
./e_coli_core.xml obj R_ACONTa optimal -3.2790312837402413e-15
./e_coli_core.xml obj R_ACONTb optimal -4.655434573658402e-15
./e_coli_core.xml obj R_ACt2r optimal 0.8739215069684313
./e_coli_core.xml obj R_ADK1 optimal 0.873921506968431
./e_coli_core.xml obj R_AKGDH optimal 0.8583074080226888
...
See for instance: e_coli_core/04_reaction_deletion.tsv. For more information: https://cobrapy.readthedocs.io/en/latest/deletions.html.