Our goal in promoting this tool is to achieve two major shifts in the metabolic model building community:
The memote tool therefore performs four subfunctions:
And in order to make this process as easy as possible the generated repository can easily be integrated with continuous integration testing providers such as Travis CI, which means that anytime you push a model change to GitHub, the test suite will be run automatically and a report will be available for you to look at via GitHub pages for your repository.
For comments and questions get in touch via
Are you excited about this project? Consider contributing by adding novel tests, reporting or fixing bugs, and generally help us make this a better software for everyone.
We highly recommend creating a Python virtualenv for your model testing purposes.
To install memote, run this command in your terminal:
$ pip install memote
This is the preferred method to install memote, as it will always install the most recent stable release.
If you don’t have pip installed, this Python installation guide can guide you through the process.
The sources for memote can be downloaded from the Github repo.
You can either clone the public repository:
$ git clone https://github.com/opencobra/memote.git
Or download the tarball or zip archive:
$ curl -OL https://github.com/opencobra/memote/archive/master.zip
Once you have a copy of the source files, you can install it with:
$ pip install .
After installation, memote can be employed in two different ways: As a benchmarking tool for ad hoc model assessment and as an automated testing suite to aid with the reconstruction of metabolic models. When using memote to benchmark a model, the tests are run once and a report is generated which describes the status-quo. As an automated testing suite, memote facilitates tracking incremental model changes in a version controlled repository and can enable continuous testing and reporting if desired.
Here, we explain step-by-step the necessary commands to pursue either workflow. Users that have already followed this tutorial once may want to refer to the cheat-sheet flowchart to refresh their memory.
To benchmark the performance of a single model, run this command in your terminal:
$ memote report snapshot path/to/model.xml
This will generate the performance report as index.html.
The output filename can be changed by adding the following option.
To illustrate here it is changed to report.html.
$ memote report snapshot --filename "report.html" path/to/model.xml
While the html report is still a work in progress, we recommend relying on the
verbose output of the command line tool above. Users can tweak the console
output by passing additional arguments directly to pytest through the
--pytest-args or simply -a option. This can be done by
writing the pytest arguments as one continuous string.
For a more detailed traceback try:
$ memote report snapshot -a "--tb long" --filename "report.html" path/to/model.xml
For a full list of possible arguments please refer to the pytest documentation.
This functionality is coming soon.
Comparing two models against each other and quickly identify the differences.
When starting a memote repository, users need to provide an SBMLv3-FBC formatted file. Automatic draft reconstruction tools such as Pathway Tools, Model SEED, The RAVEN Toolbox and others are able to output files in this format. Model repositories such as BiGG or BioModels further serve as a great resource for models in the correct format.
With this in mind, starting a local, version-controlled model repository is as simple as running the following command:
$ memote new
After this, the user will be prompted with a few questions regarding details of the project. If the project is to be kept strictly locally, the user does not need to supply GitHub (or GitLab - not implemented yet) credentials. However, these are a requirement if the project is to use the full benefits of distributed version control such as cloud-based development, remote collaboration and community feedback. It is important to note that furthermore a public repository is needed to set up automatic testing through continuous integration, one of the key features of memote.
Once all the questions following memote new have been answered, a public
repository has been created under either the user’s GitHub or GitLab account.
To enable continuous integration via Travis CI the following command is
executed:
This functionality is coming soon. A manual workaround is outlined in the cookiecutter-memote readme.
$ memote online
Now, after each edit to the model in the repository, the user can generate an update to the continuous model report shown at the project’s gh-pages branch by saving the changes with the following command:
This functionality is coming soon, for now please utilize the steps outlined for advanced users.
$ memote save
For advanced users: memote save is the equivalent of executing git add .,
git commit and git push in sequence.
Users that have decided to not to use GitHub (or GitLab Not implemented yet) or those that have decided to set the model repository to private, will need to execute:
$ memote run
to run the testing suite on their commit history followed by:
$ memote report history
to generate the same type of report that would be shown automatically with
continuous integration. After this it is crucial to save the generated test
results by running memote save again.
We recommend the public workflow not only to promote open, collaborative science but also to benefit from the full functionality of memote.
This cheat-sheet flowchart servers as a visual guide on how to get up and running with memote! It is essentially the pictographic form of the section Getting Started.
Memote can be configured to include custom test modules from any other directory in addition to the tests that are included in the package.
All custom test modules and the tests defined inside of them have to adhere to the same standard design for the results to be generated and displayed correctly. Optionally, a user may specify a configuration file which can be used to change how individual tests are displayed in the snapshot report.
At its core, a memote test module is a collection of specific python code in a
text file with the file ending .py. Since, memote uses pytest for discovery
and execution of model tests, the conditions for memote test modules and
pytest test modules are identical.
The module name has to match either test_*.py or *_test.py:
your_custom_directory/
test_module1.py
module2_test.py
...
The minimal content of a custom test module should look like this:
import pytest
from memote.utils import annotate, wrapper, truncate
import path.to.your_support_module as your_support_module
@annotate(
title="Some human-readable descriptive title for the report",
type="Single keyword describing how the data ought to be displayed."
)
def test_your_custom_case(read_only_model):
"""
Docstring that briefly outlines the test function.
A more elaborate explanation of why this test is important, how it works,
and the assumptions/ theory behind it. This can be more than one line.
"""
ann = test_your_custom_case.annotation
ann["data"] = list(your_support_module.specific_model_quality(read_only_model))
ann["metric"] = len(ann["data"]) / len(read_only_model.reactions)
ann["message"] = wrapper.fill(
"""A concise message that displays and explains the test results.
For instance, if data is a list of items the amount: {} and
percentage ({:.2%}) values can be recorded here, as well as an
excerpt of the list itself: {}""".format(
len(ann["data"]), ann['metric'], truncate(ann['data'])
))
)
assert len(ann["data"]) == 0, ann["message"]
This is a minimal test module template containing a test function called
test_your_custom_case. There can be additional lines of code, but you
should keep in mind that any logic is best put into a separate support
module, which is imported above as your_support_module. The functions of
this support module are called by the test function. This will simplify
debugging, error handling and allows for dedicated unit testing on the code
in the support module.
The following components are requirements of test_your_custom_case:
annotate() decorator, which
collects:data that the test is run on. Can be of the following type: list,
set, tuple, string, float, integer and boolean. It
can be of type dictionary, but this is only supported for parametrized
tests (see example below).type of data. This is not the actual python type
of data! Choose it according to how you’d like the results to be
displayed in the reports. For example: In the case above data
is a list, for instance it could be list of unbalanced reactions. If you choose
type="length", the report will display its length. With type="array"
it will display the individual items of the list. If data is a
single string then type="string" is best. In case, you’d rather display
the metric as opposed to the contents of data use
type="number". type="object" is only supported for parametrized
tests (see example below).title that will be displayed in the report
as opposed to the test function name test_your_custom_case which will
only serve as the test’s ID internally.metric can be any fraction relating to the quality that is tested. In
memote’s core tests the metrics of each scored tests are used to calculate
the overall score.message is a brief summary of the results displayed only on the
command line. There are no restrictions on what it should include. We’ve
generally tried to keep this short and concise to avoid spamming the command
line.read_only_model is the required parameter to access the loaded
metabolic model.Pytest allows us to run one test function with multiple sets of arguments by
simply using the pytest.mark.paremtrize decorator. This is quite useful
when the same underlying assertion logic can be applied to several parameters.
In the following example taken from memote.suite.tests.test_annotation we test
that there are no metabolites that lack annotations from any of the databases
listed in annotation.METABOLITE_ANNOTATIONS. Without parametrization we
would have had to copy the entire test function below to specifically check
the metabolite annotations for each database.
@pytest.mark.parametrize("db", list(annotation.METABOLITE_ANNOTATIONS))
@annotate(title="Missing Metabolite Annotations Per Database",
type="object", message=dict(), data=dict(), metric=dict())
def test_metabolite_annotation_overview(read_only_model, db):
"""
Expect all metabolites to have annotations from common databases.
The required databases are outlined in `annotation.py`.
"""
ann = test_metabolite_annotation_overview.annotation
ann["data"][db] = get_ids(annotation.generate_component_annotation_overview(
read_only_model.metabolites, db))
ann["metric"][db] = len(ann["data"][db]) / len(read_only_model.metabolites)
ann["message"][db] = wrapper.fill(
"""The following {} metabolites ({:.2%}) lack annotation for {}:
{}""".format(len(ann["data"][db]), ann["metric"][db], db,
truncate(ann["data"][db])))
assert len(ann["data"][db]) == 0, ann["message"][db]
Finally, there are two ways of configuring memote to find custom tests. The
first involves the --custom option of the memote CLI and requires the user
to provide a corresponding config file with the custom test modules, while the second
involves passing arguments directly to pytest through the use of the
--pytest-args option, which can be abbreviated to -a. This option only
requires the user to set up the custom test module. No config file is needed
here.
When invoking the memote run or memote report snapshot commands in
the terminal, it is possible to add the --custom option. This option takes
two parameters in a fixed order:
$ memote report snapshot --custom path/to/dir/ path/to/config.yml --filename "report.html" path/to/model.xml
In case you want to avoid setting up a configuration file, it is possible to pass any number of absolute paths to custom test directories directly to pytest, as long as they are placed behind any other parameters that you might want to pass in. For instance here we want to get a list of the ten slowest running tests while including two custom test module directories:
$ memote run -a "--durations=10 path/to/dir1/ path/to/dir2/" --filename "report.html" path/to/model.xml
Perform basic tests on an instance of cobra.Model.
test_basic.test_compartments_presence(read_only_model)[source]¶Expect that more than two compartments are defined in the model.
While simplified metabolic models may be perfectly viable, generally across the tree of life organisms contain at least one distinct compartment: the cytosol or cytoplasm. In the case of prokaryotes there is usually a periplasm, and eurkaryotes are more complex. In addition to the internal compartment, a metabolic model also reflects the extracellular environment i.e. the medium/ metabolic context in which the modelled cells grow. Hence, in total, at least two compartments can be expected from a metabolic model.
test_basic.test_find_pure_metabolic_reactions(read_only_model)[source]¶Expect at least one pure metabolic reaction to be defined in the model.
If a reaction is neither a transport reaction, a biomass reaction nor a boundary reaction, it is counted as a purely metabolic reaction. This test requires the presence of metabolite formula to be able to identify transport reactions. This test is passed when the model contains at least one purely metabolic reaction i.e. a conversion of one metabolite into another.
test_basic.test_find_transport_reactions(read_only_model)[source]¶Expect >= 1 transport reactions are present in the read_only_model.
test_basic.test_find_unique_metabolites(read_only_model)[source]¶Expect there to be less metabolites when removing compartment tag.
Metabolites may be transported into different compartments, which means that in a compartimentalized model the number of metabolites may be much higher than in a model with no compartments. This test counts only one occurrence of each metabolite and returns this as the number of unique metabolites. The test expects that the model is compartimentalized, and thus, that the number of unique metabolites is generally lower than the total number of metabolites.
test_basic.test_gene_protein_reaction_rule_presence(read_only_model)[source]¶Expect all non-exchange reactions to have a GPR rule.
Gene-Protein-Reaction rules express which gene has what function. The presence of this annotation is important to justify the existence of reactions in the model, and is required to conduct in silico gene deletion studies. However, reactions without GPR may also be valid: Spontaneous reactions, or known reactions with yet undiscovered genes likely lack GPR.
test_basic.test_genes_presence(read_only_model)[source]¶Expect that more than one gene is defined in the model.
A metabolic model can still be a useful tool without any genes, however there are certain methods which rely on the presence of genes and, more importantly, the corresponding gene-protein-reaction rules. This test requires that there is at least one gene defined.
test_basic.test_metabolic_coverage(read_only_model)[source]¶Expect a model to have a metabolic coverage >= 1.
The degree of metabolic coverage indicates the modeling detail of a given reconstruction calculated by dividing the total amount of reactions by the amount of genes. Models with a ‘high level of modeling detail have ratios >1, and models with a low level of detail have ratios <1. This difference arises as models with basic or intermediate levels of detail are assumed to include many reactions in which several gene products and their enzymatic transformations are ‘lumped’.
test_basic.test_metabolites_charge_presence(read_only_model)[source]¶Expect all metabolites to have charge information.
To be able to ensure that reactions are charge-balanced, all model metabolites ought to be provided with a charge.
test_basic.test_metabolites_formula_presence(read_only_model)[source]¶Expect all metabolites to have a formula.
To be able to ensure that reactions are mass-balanced, all model metabolites ought to be provided with a chemical formula.
test_basic.test_metabolites_presence(read_only_model)[source]¶Expect that more than one metabolite is defined in the model.
To be useful a metabolic model should consist at least of a few metabolites that are converted by reactions. This test simply checks if there are more than one metabolites defined.
test_basic.test_model_id_presence(read_only_model)[source]¶Expect that the model has an identifier.
The MIRIAM guidelines require a model to be named. While it is not required, the ID will be displayed on the memote reports, which helps to distinguish the output clearly.
test_basic.test_ngam_presence(read_only_model)[source]¶Expect a single non growth-associated maintenance reaction.
The Non-Growth Associated Maintenance reaction (NGAM) is an ATP-hydrolysis reaction added to metabolic models to represent energy expenses that the cell invests in continuous processes independent of the growth rate.
test_basic.test_protein_complex_presence(read_only_model)[source]¶Expect that more than one enzyme complex is present in the model.
Based on the gene-protein-reaction (GPR) rules, it is possible to infer whether a reaction is catalyzed by a single gene product, isozymes or by a heteromeric protein complex. This test checks that at least one such protein complex is defined in the GPR of the model. For S. cerevisiae it could be shown that “essential proteins tend to [cluster] together in essential complexes” (https://doi.org/10.1074%2Fmcp.M800490-MCP200).
This might also be a relevant metric for other organisms.
test_basic.test_reactions_presence(read_only_model)[source]¶Expect that more than one reaction is defined in the model.
To be useful a metabolic model should consist at least of a few reactions. This test simply checks if there are more than one.
test_basic.test_transport_reaction_gpr_presence(read_only_model)[source]¶Expect a small fraction of transport reactions not to have a GPR rule.
As it is hard to identify the exact transport processes within a cell, transport reactions are often added purely for modeling purposes. Highlighting where assumptions have been made vs where there is proof may help direct the efforts to improve transport and transport energetics of the tested metabolic model. However, transport reactions without GPR may also be valid: Diffusion, or known reactions with yet undiscovered genes likely lack GPR.
test_basic.test_transport_reaction_presence(read_only_model)[source]¶Expect more than one transport reaction to be defined in the model.
Cellular metabolism in any organism usually involves the transport of metabolites across a lipid bi-layer. Hence, this test checks that there is at least one reaction, which transports metabolites from one compartment to another.
A transport reaction is defined as follows: 1. It contains metabolites from at least two compartments and 2. at least one metabolite undergoes no chemical conversion, i.e., the formula stays the same on both sides of the equation.
This test will not be able to identify transport via the PTS System.
Stoichiometric consistency tests for an instance of cobra.Model.
test_consistency.test_blocked_reactions(read_only_model)[source]¶Expect all reactions to be able to carry flux in complete medium.
Universally blocked reactions are reactions that during Flux Variability Analysis cannot carry any flux while all model boundaries are open. Generally blocked reactions are caused by network gaps, which can be attributed to scope or knowledge gaps.
test_consistency.test_detect_energy_generating_cycles(read_only_model, met)[source]¶Expect that no energy metabolite can be produced out of nothing.
When a model is not sufficiently constrained to account for the thermodynamics of reactions, flux cycles may form which provide reduced metabolites to the model without requiring nutrient uptake. These cycles are referred to as erroneous energy-generating cycles. Their effect on the predicted growth rate in FBA may account for an increase of up to 25%, which makes studies involving the growth rates predicted from such models unreliable.
This test uses an implementation of the algorithm presented by: Fritzemeier, C. J., Hartleb, D., Szappanos, B., Papp, B., & Lercher, M. J. (2017). Erroneous energy-generating cycles in published genome scale metabolic networks: Identification and removal. PLoS Computational Biology, 13(4), 1–14. http://doi.org/10.1371/journal.pcbi.1005494
test_consistency.test_find_deadends(read_only_model)[source]¶Expect no dead-ends to be present.
Dead-ends are metabolites that can only be produced but not consumed by reactions in the model. They may indicate the presence of network gaps.
test_consistency.test_find_disconnected(read_only_model)[source]¶Expect no disconnected metabolites to be present.
Disconnected metabolites are not part of any reaction in the model. They are most likely left-over from the reconstruction process, but may also point to network gaps.
test_consistency.test_find_metabolites_consumed_with_closed_bounds(read_only_model)[source]¶Expect no metabolites to be consumed without product removal.
Just like metabolites should not be produced from nothing, mass should not simply be removed from the model. This test disables all the boundary reactions and checks if each metabolite can be consumed individually using flux balance analysis. To pass this test no metabolite outside of specific boundary reactions should be consumed without product leaving the system.
test_consistency.test_find_metabolites_produced_with_closed_bounds(read_only_model)[source]¶Expect no metabolites to be produced without substrate consumption.
It should not be possible for the model to produce metabolites without consuming substrate from the medium. This test disables all the boundary reactions and checks if each metabolite can be produced individually using flux balance analysis. To pass this test no metabolite outside of specific boundary reactions should be produced without the consumption of substrate.
test_consistency.test_find_orphans(read_only_model)[source]¶Expect no orphans to be present.
Orphans are metabolites that are only consumed but not produced by reactions in the model. They may indicate the presence of network gaps.
test_consistency.test_find_reactions_unbounded_flux_default_condition(read_only_model)[source]¶Expect the fraction of unbounded reactions to be low.
A large fraction of model reactions able to carry unlimited flux under default conditions indicates problems with reaction directionality, missing cofactors, incorrectly defined transport reactions and more.
test_consistency.test_find_stoichiometrically_balanced_cycles(read_only_model)[source]¶Expect no stoichiometrically balanced loops to be present.
Stoichiometrically Balanced Cycles are artifacts of insufficiently constrained networks resulting in reactions that can carry flux when all the boundaries have been closed.
test_consistency.test_reaction_charge_balance(read_only_model)[source]¶Expect all reactions to be charge balanced.
In steady state, for each metabolite the sum of influx equals the sum of outflux. Hence the net charges of both sides of any model reaction have to be equal.
test_consistency.test_reaction_mass_balance(read_only_model)[source]¶Expect all reactions to be mass balanced.
In steady state, for each metabolite the sum of influx equals the sum of outflux. Hence the net masses of both sides of any model reaction have to be equal.
test_consistency.test_stoichiometric_consistency(read_only_model)[source]¶Expect that the stoichiometry is consistent.
Stoichiometric inconsistency violates universal constraints: 1. Molecular masses are always positive, and 2. On each side of a reaction the mass is conserved. A single incorrectly defined reaction can lead to stoichiometric inconsistency in the model, and consequently to unconserved metabolites. Similar to insufficient constraints, this may give rise to cycles which either produce mass from nothing or consume mass from the model.
This test uses an implementation of the algorithm presented by Gevorgyan, A., M. G Poolman, and D. A Fell. “Detection of Stoichiometric Inconsistencies in Biomolecular Models.” Bioinformatics 24, no. 19 (2008): 2245. doi: 10.1093/bioinformatics/btn425
Annotation tests performed on an instance of cobra.Model.
test_annotation.test_metabolite_annotation_overview(read_only_model, db)[source]¶Expect all metabolites to have annotations from common databases.
Specific database cross-references are paramount to mapping information. To provide references to as many databases as possible helps to make the metabolic model more accessible to other researchers. This does not only facilitate the use of a model in a broad array of computational pipelines, it also promotes the metabolic model itself to become an organism-specific knowledge base.
For this test to pass, each metabolite annotation should contain cross-references to a number of databases (listed in annotation.py). For each database this test checks for the presence of its corresponding namespace ID to comply with the MIRIAM guidelines i.e. they have to match those defined on https://identifiers.org/.
Since each database is quite different and some potentially incomplete, it may not be feasible to achieve 100% coverage for each of them. Generally it should be possible, however, to obtain cross-references to at least one of the databases for all metabolites consistently.
test_annotation.test_metabolite_annotation_presence(read_only_model)[source]¶Expect all metabolites to have a non-empty annotation attribute.
This test checks if any annotations at all are present in the SBML annotations field for each metabolite, irrespective of the type of annotation i.e. specific database cross-references, ontology terms, additional information. For this test to pass the model is expected to have metabolites and each of them should have some form of annotation.
test_annotation.test_metabolite_annotation_wrong_ids(read_only_model, db)[source]¶Expect all annotations of metabolites to be in the correct format.
To identify databases and the identifiers belonging to them, computational tools rely on the presence of specific patterns. Only when these patterns can be identified consistently is an ID truly machine-readable. This test checks if the database cross-references in metabolite annotations conform to patterns defined according to the MIRIAM guidelines, i.e. matching those that are defined at https://identifiers.org/.
The required formats, i.e., regex patterns are further outlined in annotation.py. This test does not carry out a web query for the composed URI, it merely controls that the regex patterns match the identifiers.
test_annotation.test_metabolite_id_namespace_consistency(read_only_model)[source]¶Expect metabolite identifiers to be from the same namespace.
In well-annotated models it is no problem if the pool of main identifiers for metabolites consists of identifiers from several databases. However, in models that lack appropriate annotations, it may hamper the ability of other researchers to use it. Running the model through a computational pipeline may be difficult without first consolidating the namespace.
Hence, this test checks if the main metabolite identifiers can be attributed to one single namespace based on the regex patterns defined at https://identifiers.org/
test_annotation.test_reaction_annotation_overview(read_only_model, db)[source]¶Expect all reactions to have annotations from common databases.
Specific database cross-references are paramount to mapping information. To provide references to as many databases as possible helps to make the metabolic model more accessible to other researchers. This does not only facilitate the use of a model in a broad array of computational pipelines, it also promotes the metabolic model itself to become an organism-specific knowledge base.
For this test to pass, each reaction annotation should contain cross-references to a number of databases (listed in annotation.py). For each database this test checks for the presence of its corresponding namespace ID to comply with the MIRIAM guidelines i.e. they have to match those defined on https://identifiers.org/.
Since each database is quite different and some potentially incomplete, it may not be feasible to achieve 100% coverage for each of them. Generally it should be possible, however, to obtain cross-references to at least one of the databases for all reactions consistently.
test_annotation.test_reaction_annotation_presence(read_only_model)[source]¶Expect all reactions to have a non-empty annotation attribute.
This test checks if any annotations at all are present in the SBML annotations field for each reaction, irrespective of the type of annotation i.e. specific database cross-references, ontology terms, additional information. For this test to pass the model is expected to have reactions and each of them should have some form of annotation.
test_annotation.test_reaction_annotation_wrong_ids(read_only_model, db)[source]¶Expect all annotations of reactions to be in the correct format.
To identify databases and the identifiers belonging to them, computational tools rely on the presence of specific patterns. Only when these patterns can be identified consistently is an ID truly machine-readable. This test checks if the database cross-references in reaction annotations conform to patterns defined according to the MIRIAM guidelines, i.e. matching those that are defined at https://identifiers.org/.
The required formats, i.e., regex patterns are further outlined in annotation.py. This test does not carry out a web query for the composed URI, it merely controls that the regex patterns match the identifiers.
test_annotation.test_reaction_id_namespace_consistency(read_only_model)[source]¶Expect reaction identifiers to be from the same namespace.
In well-annotated models it is no problem if the pool of main identifiers for reactions consists of identifiers from several databases. However, in models that lack appropriate annotations, it may hamper the ability of other researchers to use it. Running the model through a computational pipeline may be difficult without first consolidating the namespace.
Hence, this test checks if the main reaction identifiers can be attributed to one single namespace based on the regex patterns defined at https://identifiers.org/
Callbacks for command line parameters.
memote.suite.cli.callbacks.validate_collect(context, param, value)[source]¶Handle the report collection flag.
memote.suite.cli.callbacks.validate_model(context, param, value)[source]¶Load model from path if it exists.
memote.suite.cli.callbacks.validate_pytest_args(context, param, value)[source]¶Handle additional arguments to pytest.
Define and make parseable the memote configuration file.
memote.suite.cli.config.ConfigFileProcessor[source]¶Bases: click_configfile.ConfigFileReader
Determine which files to look for and what sections.
config_files = ['memote.ini', 'setup.cfg']¶config_section_schemas = [<class 'memote.suite.cli.config.ConfigSectionSchema.Memote'>]¶config_sections = ['memote']¶memote.suite.cli.config.ConfigSectionSchema[source]¶Bases: object
Describes all sections of the memote configuration file.
Memote[source]¶Bases: click_configfile.SectionSchema
Describes the memote configuration keys and values.
addargs = <click_configfile.Param object>¶collect = <click_configfile.Param object>¶directory = <click_configfile.Param object>¶exclusive = <click_configfile.Param object>¶git = <click_configfile.Param object>¶github_repository = <click_configfile.Param object>¶github_username = <click_configfile.Param object>¶model = <click_configfile.Param object>¶section_names = ['memote']¶skip = <click_configfile.Param object>¶solver = <click_configfile.Param object>¶Provide commands for generating report files.
Provide commands for running the test suite on a metabolic model.
memote command line interface.
Compare two models with one another.
memote.suite.reporting.reports.diff.DiffReport(**kwargs)[source]¶Bases: memote.suite.reporting.reports.report.Report
Render a report from the comparison of two models.
Render results into pretty HTML.
memote.suite.reporting.reports.history.HistoryReport(repository, directory, index='time', **kwargs)[source]¶Bases: memote.suite.reporting.reports.report.Report
Render a rich report using the git repository history.
Render results into pretty HTML.
Render a basic one-time report.
memote.suite.reporting.reports.snapshot.SnapshotReport(data, **kwargs)[source]¶Bases: memote.suite.reporting.reports.report.Report
Render a basic report from the given data.
Subpackage for creating visually pleasing reports of test results.
There are three types of reports that we support:
Utilities that handle a dask.bag.
Subpackage for gathering information and creating reports.
Programmatically interact with the memote test suite.
memote.suite.api.test_model(model, filename=None, results=False, pytest_args=None, exclusive=None, skip=None, solver=None, custom=(None, None))[source]¶Test a model and optionally store results as JSON.
| Parameters: | model : cobra.Model
filename : str or pathlib.Path, optional
results : bool, optional
pytest_args : list, optional
exclusive : iterable, optional
skip : iterable, optional
custom : tuple, optional
|
|---|---|
| Returns: | int
dict, optional
|
memote.suite.api.snapshot_report(results, filename)[source]¶Test a model and save a basic report.
| Parameters: | results : dict
filename : str or pathlib.Path
|
|---|
memote.suite.api.history_report(repository, directory, filename, index='hash')[source]¶Test a model and save a history report.
| Parameters: | repository : git.Repo, optional
directory : str or pathlib.Path
filename : str or pathlib.Path
index : {“hash”, “time”}, optional
|
|---|
Collect results for reporting model quality.
memote.suite.collect.ResultCollectionPlugin(model, repository=None, branch=None, commit=None, exclusive=None, skip=None, custom_config=None, **kwargs)[source]¶Bases: object
Provide functionality for complex test result collection.
The plugin exposes the fixture store which can be used in test
functions to store values in a dictionary. The dictionary is namespaced to
the module so within a module the same keys should not be re-used
(unless intended).
pytest_report_teststatus(report)[source]¶Log pytest results for each test.
The categories are passed, failed, error, skipped and marked to fail.
| Parameters: | report : TestReport
|
|---|
results¶Return the test results as a nested dictionary.
Supporting functions for annotation checks performed on the model object.
memote.support.annotation.find_components_without_annotation(model, components)[source]¶Find model components with empty annotation attributes.
| Parameters: | model : cobra.Model
components : {“metabolites”, “reactions”, “genes”}
|
|---|---|
| Returns: | list
|
memote.support.annotation.generate_component_annotation_miriam_match(elements, component, db)[source]¶Tabulate which MIRIAM databases the element’s annotation match.
If the relevant MIRIAM identifier is not in an element’s annotation it is ignored.
| Parameters: | elements : list
component : {“metabolites”, “reactions”}
db : str
|
|---|---|
| Returns: | list
|
memote.support.annotation.generate_component_annotation_overview(elements, db)[source]¶Tabulate which MIRIAM databases the component’s annotation match.
| Parameters: | elements : list
db : str
|
|---|---|
| Returns: | list
|
memote.support.annotation.generate_component_id_namespace_overview(model, components)[source]¶Tabulate which MIRIAM databases the component’s identifier matches.
| Parameters: | model : cobra.Model
components : {“metabolites”, “reactions”, “genes”}
|
|---|---|
| Returns: | pandas.DataFrame
|
Supporting functions for basic checks performed on the model object.
Supporting functions for biomass consistency checks.
memote.support.biomass.sum_biomass_weight(reaction)[source]¶Compute the sum of all reaction compounds.
| Parameters: | reaction : cobra.core.reaction.Reaction
|
|---|
memote.support.biomass.find_biomass_precursors(reaction)[source]¶Return a list of all biomass precursors excluding ATP and H2O.
| Parameters: | reaction : cobra.core.reaction.Reaction
|
|---|
memote.support.biomass.find_blocked_biomass_precursors(reaction, model)[source]¶Return a list of all biomass precursors that cannot be produced.
| Parameters: | reaction : cobra.core.reaction.Reaction
model : cobra.Model
|
|---|
Supporting functions for stoichiometric consistency checks.
memote.support.consistency.check_stoichiometric_consistency(model)[source]¶Verify the consistency of the model stoichiometry.
| Parameters: | model : cobra.Model
|
|---|
Notes
See [R16] section 3.1 for a complete description of the algorithm.
| [R16] | Gevorgyan, A., M. G Poolman, and D. A Fell. “Detection of Stoichiometric Inconsistencies in Biomolecular Models.” Bioinformatics 24, no. 19 (2008): 2245. |
memote.support.consistency.detect_energy_generating_cycles(model, metabolite_id)[source]¶Detect erroneous energy-generating cycles for a a single metabolite.
The function will first build a dissipation reaction corresponding to the input metabolite. This reaction is then set as the objective for optimization, after closing all exchanges. If the reaction was able to carry flux, an erroneous energy-generating cycle must be present. In this case a list of reactions with a flux greater than zero is returned. Otherwise, the function returns False.
| Parameters: | model : cobra.Model
metabolite_id : str
|
|---|
Notes
“[…] energy generating cycles (EGC) […] charge energy metabolites without a source of energy. […] To efficiently identify the existence of diverse EGCs, we first add a dissipation reaction to the metabolic network for each metabolite used to transmit cellular energy; e.g., for ATP, the irreversible reaction ATP + H2O → ADP + P + H+ is added. These dissipation reactions close any existing energy-generating cycles, thereby converting them to type-III pathways. Fluxes through any of the dissipation reactions at steady state indicate the generation of energy through the metabolic network. Second, all uptake reactions are constrained to zero. The sum of the fluxes through the energy dissipation reactions is now maximized using FBA. For a model without EGCs, these reactions cannot carry any flux without the uptake of nutrients. [R27].”
References
| [R27] | (1, 2) Fritzemeier, C. J., Hartleb, D., Szappanos, B., Papp, B., & Lercher, M. J. (2017). Erroneous energy-generating cycles in published genome scale metabolic networks: Identification and removal. PLoS Computational Biology, 13(4), 1–14. http://doi.org/10.1371/journal.pcbi.1005494 |
memote.support.consistency.find_charge_imbalanced_reactions(model)[source]¶Find metabolic reactions that are not charge balanced.
This will exclude biomass, exchange and demand reactions as they are unbalanced by definition. It will also fail all reactions where at least one metabolite does not have a charge defined.
| Parameters: | model : cobra.Model
|
|---|
memote.support.consistency.find_deadends(model)[source]¶Return metabolites that are only produced in reactions.
| Parameters: | model : cobra.Model
|
|---|
memote.support.consistency.find_disconnected(model)[source]¶Return metabolites that are not in any of the reactions.
| Parameters: | model : cobra.Model
|
|---|
memote.support.consistency.find_elementary_leakage_modes(model, atol=1e-13)[source]¶Detect elementary leakage modes.
| Parameters: | model : cobra.Model
atol : float, optional
|
|---|
Notes
See [R38] section 3.4 for a complete description of the algorithm.
References
| [R38] | (1, 2) Gevorgyan, A., M. G Poolman, and D. A Fell. “Detection of Stoichiometric Inconsistencies in Biomolecular Models.” Bioinformatics 24, no. 19 (2008): 2245. |
memote.support.consistency.find_inconsistent_min_stoichiometry(model, atol=1e-13)[source]¶Detect inconsistent minimal net stoichiometries.
| Parameters: | model : cobra.Model
atol : float, optional
|
|---|
Notes
See [R49] section 3.3 for a complete description of the algorithm.
| [R49] | Gevorgyan, A., M. G Poolman, and D. A Fell. “Detection of Stoichiometric Inconsistencies in Biomolecular Models.” Bioinformatics 24, no. 19 (2008): 2245. |
memote.support.consistency.find_mass_imbalanced_reactions(model)[source]¶Find metabolic reactions that are not mass balanced.
This will exclude biomass, exchange and demand reactions as they are unbalanced by definition. It will also fail all reactions where at least one metabolite does not have a formula defined.
| Parameters: | model : cobra.Model
|
|---|
memote.support.consistency.find_metabolites_consumed_with_closed_bounds(model)[source]¶Return metabolites that can be consumed when boundary reactions are closed.
Reverse case from ‘find_metabolites_produced_with_closed_bounds’, just like metabolites should not be produced from nothing, mass should not simply be removed from the model.
| Parameters: | model : cobra.Model
|
|---|
memote.support.consistency.find_metabolites_produced_with_closed_bounds(model)[source]¶Return metabolites that can be produced when boundary reactions are closed.
| Parameters: | model : cobra.Model
|
|---|
memote.support.consistency.find_orphans(model)[source]¶Return metabolites that are only consumed in reactions.
| Parameters: | model : cobra.Model
|
|---|
memote.support.consistency.find_reactions_with_unbounded_flux_default_condition(model)[source]¶Return list of reactions whose flux is unbounded in the default condition.
| Parameters: | model : cobra.Model
|
|---|
memote.support.consistency.find_stoichiometrically_balanced_cycles(model)[source]¶Find metabolic rxns in stoichiometrically balanced cycles (SBCs).
The flux distribution of nominal FVA is compared with loopless FVA (loopless=True) to determine reactions that participate in loops, as participation in loops would increase the flux through a given reactions to the maximal bounds. This function then returns reactions where the flux differs between the two FVA calculations.
| Parameters: | model : cobra.Model
|
|---|
Notes
“SBCs are artifacts of metabolic reconstructions due to insufficient constraints (e.g., thermodynamic constraints and regulatory constraints) [R510].” They are defined by internal reactions that carry flux in spite of closed exchange reactions.
References
| [R510] | (1, 2) Thiele, I., & Palsson, B. Ø. (2010, January). A protocol for generating a high-quality genome-scale metabolic reconstruction. Nature protocols. Nature Publishing Group. http://doi.org/10.1038/nprot.2009.203 |
memote.support.consistency.find_unconserved_metabolites(model)[source]¶Detect unconserved metabolites.
| Parameters: | model : cobra.Model
|
|---|
Notes
See [R611] section 3.2 for a complete description of the algorithm.
| [R611] | Gevorgyan, A., M. G Poolman, and D. A Fell. “Detection of Stoichiometric Inconsistencies in Biomolecular Models.” Bioinformatics 24, no. 19 (2008): 2245. |
memote.support.consistency.find_universally_blocked_reactions(model)[source]¶Find metabolic reactions that are blocked.
| Parameters: | model : cobra.Model
|
|---|
Notes
Blocked reactions are those reactions that when optimized for cannot carry any flux while all exchanges are open.
Helper functions for stoichiometric consistency checks.
memote.support.consistency_helpers.stoichiometry_matrix(metabolites, reactions)[source]¶Return the stoichiometry matrix representation of a set of reactions.
The reactions and metabolites order is respected. All metabolites are expected to be contained and complete in terms of the reactions.
| Parameters: | reactions : iterable
metabolites : iterable
|
|---|---|
| Returns: | numpy.array
dict
dict
|
memote.support.consistency_helpers.nullspace(matrix, atol=1e-13, rtol=0.0)[source]¶Compute the nullspace of a 2D numpy.array.
Notes
Adapted from: https://scipy.github.io/old-wiki/pages/Cookbook/RankNullspace.html
Helper functions that are used all over the memote package.
memote.support.helpers.close_boundaries_sensibly(model)[source]¶Return a cobra model with all boundaries closed and changed constraints.
In the returned model previously fixed reactions are no longer constrained as such. Instead reactions are constrained according to their reversibility. This is to prevent the FBA from becoming infeasible when trying to solve a model with closed exchanges and one fixed reaction.
| Parameters: | model : cobra.Model
|
|---|---|
| Returns: | cobra.Model
|
memote.support.helpers.find_biomass_reaction(model)[source]¶Return a list of the biomass reaction(s) of the model.
| Parameters: | model : cobra.Model
|
|---|
memote.support.helpers.find_converting_reactions(model, pair)[source]¶Find reactions which convert a given metabolite pair.
| Parameters: | model : cobra.Model
pair: tuple or list
|
|---|---|
| Returns: | frozenset
|
memote.support.helpers.find_demand_reactions(model)[source]¶Return a list of demand reactions.
| Parameters: | model : cobra.Model
|
|---|
Notes
[1] defines demand reactions as: – ‘unbalanced network reactions that allow the accumulation of a compound’ – reactions that are chiefly added during the gap-filling process – as a means of dealing with ‘compounds that are known to be produced by the organism [..] (i) for which no information is available about their fractional distribution to the biomass or (ii) which may only be produced in some environmental conditions – reactions with a formula such as: ‘met_c -> ‘
Demand reactions differ from exchange reactions in that the metabolites are not removed from the extracellular environment, but from any of the organism’s compartments.
References
| [R1315] | Thiele, I., & Palsson, B. Ø. (2010, January). A protocol for generating a high-quality genome-scale metabolic reconstruction. Nature protocols. Nature Publishing Group. http://doi.org/10.1038/nprot.2009.203 |
memote.support.helpers.find_exchange_rxns(model)[source]¶Return a list of exchange reactions.
| Parameters: | model : cobra.Model
|
|---|
Notes
[1] defines exchange reactions as: – reactions that ‘define the extracellular environment’ – ‘unbalanced, extra-organism reactions that represent the supply to or removal of metabolites from the extra-organism “space”’ – reactions with a formula such as: ‘met_e -> ‘ or ‘ -> met_e’ or ‘met_e <=> ‘
Exchange reactions differ from demand reactions in that the metabolites are removed from or added to the extracellular environment only. With this the uptake or secretion of a metabolite is modeled, respectively.
References
| [R1416] | Thiele, I., & Palsson, B. Ø. (2010, January). A protocol for generating a high-quality genome-scale metabolic reconstruction. Nature protocols. Nature Publishing Group. http://doi.org/10.1038/nprot.2009.203 |
memote.support.helpers.find_functional_units(gpr_str)[source]¶Return an iterator of gene IDs grouped by boolean rules from the gpr_str.
The gpr_str is first transformed into an algebraic expression, replacing the boolean operators ‘or’ with ‘+’ and ‘and’ with ‘*’. Treating the gene IDs as sympy.symbols this allows a mathematical expansion of the algebraic expression. The expanded form is then split again producing sets of gene IDs that in the gpr_str had an ‘and’ relationship.
| Parameters: | gpr_str : string
|
|---|
memote.support.helpers.find_sink_reactions(model)[source]¶Return a list of sink reactions.
| Parameters: | model : cobra.Model
|
|---|
Notes
[1] defines sink reactions as: – ‘similar to demand reactions’ but reversible, thus able to supply the model with metabolites – reactions that are chiefly added during the gap-filling process – as a means of dealing with ‘compounds that are produced by nonmetabolic cellular processes but that need to be metabolized’ – reactions with a formula such as: ‘met_c <-> ‘
Sink reactions differ from exchange reactions in that the metabolites are not removed from the extracellular environment, but from any of the organism’s compartments.
References
| [R1517] | Thiele, I., & Palsson, B. Ø. (2010, January). A protocol for generating a high-quality genome-scale metabolic reconstruction. Nature protocols. Nature Publishing Group. http://doi.org/10.1038/nprot.2009.203 |
memote.support.helpers.find_transport_reactions(model)[source]¶Return a list of all transport reactions.
| Parameters: | model : cobra.Model
|
|---|
Notes
A transport reaction is defined as follows: 1. It contains metabolites from at least 2 compartments and 2. at least 1 metabolite undergoes no chemical reaction, i.e., the formula stays the same on both sides of the equation.
This function will not identify transport via the PTS System.
memote.support.helpers.find_transported_elements(rxn)[source]¶Return a dictionary showing the amount of transported elements of a rxn.
Collects the elements for each metabolite participating in a reaction,
multiplies the amount by the metabolite’s stoichiometry in the reaction and
bins the result according to the compartment that metabolite is in. This
produces a dictionary of dictionaries such as this
{'p': {'C': -1, 'H': -4}, c: {'C': 1, 'H': 4}} which shows the
transported entities. This dictionary is then simplified to only include
the non-zero elements of one single compartment i.e. showing the precise
elements that are transported.
| Parameters: | rxn : cobra.Reaction
|
|---|
memote.support.helpers.run_fba(model, rxn_id, direction='max', single_value=True)[source]¶Return the solution of an FBA to a set objective function.
| Parameters: | model : cobra.Model
rxn_id : string
direction: string
single_value: boolean
|
|---|---|
| Returns: | cobra.solution
|
Supporting functions for syntax checks performed on the model object.
memote.support.syntax.find_abc_tag_transporter(model)[source]¶Find Atp-binding cassette transport rxns without ‘abc’ tag.
| Parameters: | model : cobra.Model
|
|---|
Notes
An ABC transport reaction is defined as follows: 1. It contains metabolites from at least 2 compartments, 2. at least 1 metabolite undergoes no chemical reaction, i.e., the formula stays the same on both sides of the equation, and 3. ATP is converted to ADP (+ Pi + H, yet this isn’t checked for explicitly).
Reactions that only transport protons (‘H’) across the membrane are excluded, as well as reactions with redox cofactors whose formula is either ‘X’ or ‘XH2’
memote.support.syntax.find_false_demand_rxns(model)[source]¶Find reactions which are tagged with DM_ but which are not demand rxns.
| Parameters: | model : cobra.Model
|
|---|
memote.support.syntax.find_false_exchange_rxns(model)[source]¶Find reactions that are tagged with EX_ but are not exchange reactions.
| Parameters: | model : cobra.Model
|
|---|
memote.support.syntax.find_false_sink_rxns(model)[source]¶Find reactions which are tagged with SK_ but which are not sink rxns.
| Parameters: | model : cobra.Model
|
|---|
memote.support.syntax.find_reaction_tag_transporter(model)[source]¶Return incorrectly tagged transport reactions.
Make an exception for the ATP synthase reaction (ATPS) which a unique case for a transport reaction and thus does not get the tag.
| Parameters: | model : cobra.Model
|
|---|
Notes
A transport reaction is defined as follows: 1. It contains metabolites from at least 2 compartments and 2. at least 1 metabolite undergoes no chemical reaction, i.e., the formula stays the same on both sides of the equation.
Reactions that only transport protons (‘H’) across the membrane are excluded, as well as reactions with redox cofactors whose formula is either ‘X’ or ‘XH2’
memote.support.syntax.find_rxn_id_compartment_suffix(model, suffix)[source]¶Find un-tagged non-transport reactions.
Find non-transport reactions with metabolites in the given compartment whose ID is not tagged accordingly.
| Parameters: | model : cobra.Model
suffix : str
|
|---|---|
| Returns: | list
|
memote.support.syntax.find_rxn_id_suffix_compartment(model, suffix)[source]¶Find mis-tagged non-transport reactions.
Find non-transport reactions whose ID bear a compartment tag but which do not contain any metabolites in the given compartment.
| Parameters: | model : cobra.Model
suffix : str
|
|---|---|
| Returns: | list
|
memote.support.syntax.find_untagged_demand_rxns(model)[source]¶Find demand reactions whose IDs do not begin with DM_.
| Parameters: | model : cobra.Model
|
|---|
memote.support.syntax.find_untagged_exchange_rxns(model)[source]¶Find exchange reactions whose identifiers do not begin with EX_.
| Parameters: | model : cobra.Model
|
|---|
memote.support.syntax.find_untagged_sink_rxns(model)[source]¶Find demand reactions whose IDs do not begin with SK_.
| Parameters: | model : cobra.Model
|
|---|
memote.support.syntax.find_upper_case_mets(model)[source]¶Find metabolites whose ID roots contain uppercase characters.
| Parameters: | model : cobra.Model
|
|---|
Notes
In metabolite names, individual uppercase exceptions are allowed: – Dextorotary prefix: ‘D’ – Levorotary prefix: ‘L’ – Prefixes for the absolute configuration of a stereocenter: ‘R’ and ‘S’ – Prefixes for the absolute stereochemistry of double bonds ‘E’ and ‘Z’ – Acyl carrier proteins can be labeled as ‘ACP’
Helper functions for the metabolic model test suite.
Utility functions used by memote and its tests.
memote.utils.register_with(registry)[source]¶Register a passed in object.
Intended to be used as a decorator on model building functions with a
dict as a registry.
Examples
REGISTRY = dict() @register_with(REGISTRY) def build_empty(base):
return base
memote.utils.annotate(title, type, message=None, data=None, metric=1.0)[source]¶Annotate a test case.
| Parameters: | title : str
type : str
message : str
data
metric: float
|
|---|---|
| Returns: | function
|
Notes
Adds “annotation” attribute to the function object, which stores values for predefined keys as a dictionary.
(Me)tabolic (Mo)del (Te)sts.
The memote Python package provides a number of hard and soft expectations about genome-scale metabolic models.
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Report bugs at https://github.com/opencobra/memote/issues.
If you are reporting a bug, please include:
Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.
Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.
memote could always use more documentation, whether as part of the official memote docs, in docstrings, or even on the web in blog posts, articles, and such.
The best way to send feedback is to file an issue at https://github.com/opencobra/memote/issues.
If you are proposing a feature:
Ready to contribute? Here’s how to set up memote for local development.
Fork the memote repo on GitHub.
Clone your fork locally:
git clone git@github.com:your_name_here/memote.git
Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
mkvirtualenv memote
cd memote/
pip install -e .
Create a branch for local development using fix or feat as a prefix:
git checkout -b fix-name-of-your-bugfix
Now you can make your changes locally.
When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions. This is all included with tox:
tox
You can run all tests in parallel using detox. To get tox and detox, just pip install them into your virtualenv.
Commit your changes and push your branch to GitHub. Please use semantic commit messages:
git add .
git commit -m "fix: Your detailed description of your changes."
git push origin fix-name-of-your-bugfix
Submit a pull request through the GitHub website.
Before you submit a pull request, check that it meets these guidelines:
--exclusive test_biomass).--skip test_model_id_presence).@register_with that can be used in all
test_for* modules and replaces the model_builder function.print statement from memote.support.annotation
.generate_component_annotation_miriam_match.memote.memote.suite.tests.test_basic
.test_gene_protein_reaction_rule_presence.memote.support.consistency_helpers.get_internals that did
not exclude the (by definition) imbalanced biomass reactions.test_find_stoichiometrically_balanced_cyclesmemote online.memote.suite.api (#162).memote (#172).memote online (#95, #153).memote.show_versions() for easy dependency checking.