refinegems.analysis subpackage

comparison module

Provides functions to compare and visualize multiple models

Can mainly be used to compare growth behaviour of multiple models. All other stats are shown in the memote report.

refinegems.analysis.comparison.plot_venn(models: list[cobra.Model], entity: str, perc: bool = False, rename=None) → matplotlib.axes.Axes[source]

Creates Venn diagram to show the overlap of model entities

Args:
  • models (list[cobraModel]):

    Models loaded with cobrapy

  • entity (str):

    Compare on metabolite|reaction

  • perc (bool, optional):

    True if percentages should be used. Defaults to False.

  • rename (dict, optional):

    Rename model ids to custom names. Defaults to None.

Returns:
matplotlib.axes.Axes:

Venn diagram

refinegems.analysis.comparison.sbo_terms(models: list[libsbml.Model]) → MultiSBOTermReport[source]

Analyse and compare the SBO term annotations of a given list of models.

Args:
  • models (list[libModel]):

    A list containing models loaded with libSBML.

Returns:
MultiSBOTermReport:

A MultiSBOTermReport instance.

core_pan module

Handling, creating and working with pan-core models.

refinegems.analysis.core_pan.collect_reacs_from_model(model: cobra.Model, reac_id_list: list[str], based_on: Literal['id'] = 'id', notes: tuple[str] = ('core-pan', 'core')) → list[cobra.Reaction][source]

Based on a model and a list of reactions IDs, collects the corresponding reactions.

Args:
  • model (cobra.Model):

    The model.

  • reac_id_list (list[str]):

    List of reactions IDs. are treated as actual cobra ID or not depending on ‘based_on’.

  • based_on (Literal[‘id’], optional):

    Defines, if the IDs are to be treated literal (‘id’) or not. Defaults to ‘id’.

  • notes (tuple, optional):

    What kind of reactions have been collected. Expects a tuple of two strings. Uses the tuple to create a notes entry in the reaction object. Defaults to (‘core-pan’,’core’).

Raises:

  • ValueError: Unknown input for parameter based_on.

Returns:
list[cobra.Reaction]:

List of the extracted reactions.

refinegems.analysis.core_pan.compare_to_core_pan(model: cobra.Model, cp_model: cobra.Model, based_on: Literal['id'] = 'id') → CorePanAnalysisReport[source]

Compare a model to a pan-core model.

Comparison can be done based on:

  • id: uses the reaction IDs for a simple and direct comparison.

Note

Currently, this requires the model reactions to be annotated with ‘core-pan’ notes. This function however, is object to change and will be extended in the future.

Args:
  • model (cobra.Model):

    The input model.

  • cp_model (cobra.Model):

    The core-pan model

  • based_on (Literal[‘id’], optional):

    How to perform the comparison. Defaults to ‘id’.

Raises:

  • ValueError: Unknown input for parameter based_on.

Returns:
CorePanAnalysisReport:

The analysis results in form of a report object.

refinegems.analysis.core_pan.extract_reactions_ids(model: cobra.Model, based_on: Literal['id'] = 'id') → list[str][source]

Extract reactions identifiers from a model.

Based on:

  • id: extracts the actual IDs as set in the model.

Args:
  • model (cobra.Model):

    The model to extract the IDs from. Loaded with COBRApy.

  • based_on (Literal[‘id’], optional):

    How and which IDs to extract. Defaults to ‘id’.

Raises:

  • ValueError: Unknown input for parameter based_on if not in given options.

Returns:
list[str]:

List of extracted IDs in the given format.

refinegems.analysis.core_pan.find_core_reaction_ids(all_reactions: dict[slice(<class 'str'>, list[str], None)]) → list[str][source]

Helper function for generate_core_pan_model(). Identify the core reactions from a set of reactions from different models. Core reactions are reactions that occur in ALL the models.

Args:
  • all_reactions (dict[str:list[str]]):

    List of reactions IDs for all model to be part of the core-pan model.

Returns:
list[str]:

List of the IDs of reactions that are defined as core.

refinegems.analysis.core_pan.find_pan_reactions(all_reactions: dict[slice(<class 'str'>, list[str], None)], core: list[str]) → list[str][source]

Helper function for generate_core_pan_model(). Identify the pan reactions for a set of reactions of different model. Pan reactions are reactions, that are found in AT LEAST one model but NOT in all.

Args:
  • all_reactions (dict[str:list[str]):

    List of reactions IDs for all model to be part of the core-pan model.

  • core (list[str]):

    List of core reaction IDs, output of find_core_reaction_ids().

Returns:
list[str]:

List of pan reaction IDs.

refinegems.analysis.core_pan.generate_core_pan_model(model_list: list[str], based_on: Literal['id'] = 'id', name: str = 'core_pan_model', remove_genes: bool = True) → cobra.Model[source]

Generate a core-pan model from a set of models.

Generation id based on:

  • id: uses the IDs to compare reactions

Args:
  • model_list (list[str]):

    List of paths to models.

  • based_on (Literal[‘id’], optional):

    How to decide which reactions are considered the same. Defaults to ‘id’.

  • name (str, optional):

    Name of the new model. Defaults to ‘core_pan_model’.

  • remove_genes (bool, optional):

    Flag to remove all genes from the model. Defaults to True.

Returns:
cobra.Model:

The generated core-pan model.

growth module

Provides functions to simulate growth on any medium and other functionalities replated to growth.

refinegems.analysis.growth.find_additives_to_enable_growth(model: cobra.Model, growth_medium: dict, standard_uptake: list[str], combine: bool = False) → list[str] | dict[source]

Based on a new medium for growth and a standard one the model already growths on, find additives from the standard, which can be added to the new one to enable growths.

Warning

This function currently only checks via single deletions not via correlated ones. Might lead to problems in complecated cases, e.g. missing carbon source but multiple ones in the standard medium.

Args:
  • model (cobraModel):

    The model to add the medium to.

  • growth_medium (dict):

    A medium definition, ready to be added to a COBRApy model. This is for the new medium for growth testing.

  • standard_uptake (list[str]):

    A list of exchange reactions, e.g. output of get_uptake. This is for the old medium where the model can grow on.

  • combine (bool, optional):

    Flag to directly combine the additives with the new medium or just return the additive’s IDs. Defaults to False (returns reaction IDs).

Returns:
  1. Case combine = False:
    list:

    List of the exchange reaction IDs of the additives.

  2. Case combine = True:
    Medium:

    Supplemented medium as a dictionary.

refinegems.analysis.growth.find_growth_enhancing_exchanges(model: cobra.Model, base_medium: dict) → pandas.DataFrame[source]

Iterates through all exchanges to find metabolites that lead to a higher growth rate compared to the growth rate yielded on the base_medium

Args:
  • model (cobraModel):

    Model loaded with COBRApy

  • base_medium (dict):

    Exchanges as keys and their flux bound as value (f.ex {‘EX_glc__D_e’ : 10.0})

Returns:
pd.DataFrame:

Exchanges sorted from highest to lowest growth rate improvement

refinegems.analysis.growth.find_growth_essential_exchanges(model: cobra.Model, growth_medium: dict, standard_uptake: list[str] | None) → list[str][source]

Find exchanges in a medium (with or without supplements) essential for the growth.

Note

This function currently only tests single deletions.

Args:
  • model (cobraModel):

    The model to be tested.

  • growth_medium (dict):

    The medium in dictionary form, ready to be added to the model.

  • standard_uptake (list[str]|None):

    Option to add a second medium list as supplements.

Returns:
list[str]:

The list of exchanges essential for growth.

refinegems.analysis.growth.get_essential_exchanges_via_bounds(model: cobra.Model) → list[str][source]

Knocks out reactions by setting their bounds to 0, if no growth is detected the reaction is seen as essential

Args:
  • model (cobraModel):

    Model loaded with COBRApy

Returns:
list[str]:

Ids of essential reactions

refinegems.analysis.growth.get_essential_reactions_via_single_knockout(model: cobra.Model) → list[str][source]

Knocks out each reaction, if no growth is detected the reaction is seen as essential

Args:
  • model (cobraModel):

    Model loaded with COBRApy

Returns:
list[str]:

Ids of essential reactions

refinegems.analysis.growth.get_metabs_essential_for_growth_wrapper(model: cobra.Model, media: list[Medium], only_additives: bool = True) → dict[source]

Returns metabolites necessary for growth and not in media

Args:
  • model (cobraModel):

    Model loaded with COBRApy

  • media (list[Medium]):

    Containing all media for which the growth essential metabolites not contained in the media should be returned

  • only_additives(bool, optional):

    Flag to only return the supplemented exchanges (True) or all essential ones (False). Defaults to True.

Returns:
dict:

Information on different media which metabs are missing (key: name of medium, values: list of exchanges).

refinegems.analysis.growth.get_production(model: cobra.Model) → list[str][source]

Checks fluxes after FBA, if positive the metabolite is produced.

Args:
  • model (cobraModel):

    Model loaded with COBRApy

Returns:
list[str]:

Ids of produced metabolites

refinegems.analysis.growth.get_secretion(model: cobra.Model) → list[str][source]

Returns the list of exchange reactions for compounds that are secreted in the current version of the model.

Args:
  • model (cobraModel):

    The cobra model to be tested.

Returns:
list[str]:

The list of IDs of secretion reactions

refinegems.analysis.growth.get_uptake(model: cobra.Model, type: str) → list[str][source]

Compute the list of exchange reactions that have fluxes > 0 under certain conditions.

Args:
  • model (cobraModel):

    A cobra Model to be tested.

  • type (str):

    Type of uptake, can be ‘minimal’/’min’ or ‘standard’/’std’.

Raises:

  • ValueError: Unknown type for uptake, if type not in [‘minimal’,’min’,’standard’,’std’]

Returns:
list[str]:

List of non-zero flux exchange reactions under the set type.

refinegems.analysis.growth.growth_analysis(models: cobra.Model | str | list[str] | list[cobra.Model], media: Medium | list[Medium] | str, namespace: Literal['BiGG'] = 'BiGG', supplements: None | list[Literal[None, 'std', 'min']] | Literal[None, 'std', 'min'] = None, retrieve: Literal['report', 'plot', 'both'] = 'plot') → GrowthSimulationReport | matplotlib.pyplot.Figure | tuple[source]

Perform a growth analysis

Args:
  • models (cobra.Model | str | list[str] | list[cobra.Model]):

    Model(s) to be tested. Can be a COBRA model, a path to one, or a list of either type.

  • media (Medium | list[Medium] | str):

    Medium or media to be tested. Can be single or a list of medium objects or a path to a medium config file.

  • namespace (Literal[‘BiGG’], optional):

    Namespace of the model. Defaults to ‘BiGG’.

  • supplements (None | list[Literal[None,’std’,’min’]] | Literal[None,’std’,’min’], optional):

    Option to supplement media to enable growth. Can be None, std or min. If a single string is given, uses it for all media. Alternatively, a list with one entry per medium can be given to choose different options for different media. Defaults to None.

  • retrieve (Literal[‘report’,’plot’,’both’], optional):

    Determine, what to return. Options are the report object, the plotted graph or both (As a tuple). Defaults to ‘plot’.

Raises:

  • TypeError: Unknown or mixed types in model list.

  • KeyError: Empty list for models detected.

  • ValueError: Unknown input type for models.

  • TypeError: Unknown type found in media, should be list fo Medium.

  • ValueError: Unknown input for media.

  • ValueError: Unknown input for retrieve

Returns:
  1. Case: retrieve = report:
    GrowthSimulationReport:

    The generated report object.

  2. Case: retrieve = plot:
    plt.Figure:

    The finished plot

  3. Case: retrieve = both:
    tuple:

    The (0) report and the graphic (1).

refinegems.analysis.growth.growth_sim_multi(models: cobra.Model | list[cobra.Model], media: Medium | list[Medium], namespace: Literal['BiGG', 'Name'] = 'BiGG', supplement_modes: list[Literal['None', 'min', 'std']] | None | Literal['None', 'min', 'std'] = None) → GrowthSimulationReport[source]

Simulate the growth of (at least one) models on (at least one) media.

Args:
  • models (cobraModel | list[cobraModel]):

    A COBRApy model or a list of multiple.

  • media (Medium | list[Medium]):

    A refinegems Medium object or a list of multiple.

  • supplement_modes (list[Literal[None,’min’,’std’]] | None | Literal[None, ‘min’, ‘std’], optional):

    Option to supplement the media to enable growth. Default to None. Further options include a list with one entry for each medium or a string to set the same default for all. The string can be ‘min’, ‘std’ or None.

Returns:
GrowthSimulationReport:

The compiled information of the simulation results.

refinegems.analysis.growth.growth_sim_single(model: cobra.Model, m: Medium, namespace: Literal['BiGG', 'Name'] = 'BiGG', supplement: Literal[None, 'std', 'min'] = None) → SingleGrowthSimulationReport[source]

Simulate the growth of a model on a given medium.

Args:
  • model (cobraModel):

    The model.

  • m (Medium):

    The medium.

  • supplement (Literal[None,’std’,’min’], optional):

    Flag to add additvites to the model to ensure growth. Defaults to None (no supplements). Further options include ‘std’ for standard uptake and ‘min’ for minimal uptake supplementation.

Returns:
SingleGrowthSimulationReport:

Object with the simulation results

refinegems.analysis.growth.model_minimal_medium(model: cobra.Model, objective: Literal['flux', 'medium', 'exchanges'] = 'flux', growth_rate: float = 0.5, open_exchanges: bool = False) → Medium[source]

Get the minimal medium based on different objectives:

  • ‘flux’: find the minimal fluxes based in current medium.

  • ‘medium’: find the minimal number of compounds for the current medium.

  • ‘exchanges’: find the minimal number of compounds in a medium based on all avaiblae exchange reactions in the model.

Note

There may be multiple solutions for the minimisation, but only 1 will be returned.

Args:
  • model (cobraModel):

    Model with a medium, that should be minimised.

  • objective (Literal[flux,medium,exchanges], optional):

    Objective for the minimisation task. Options listed above. Defaults to ‘flux’.

  • growth_rate (float, optional):

    Minimum growth rate the model has to archieve. Defaults to 0.5. Only needed for objectives medium and exchanges.

  • open_exchanges (bool, optional):

    If set to True assigns large upper bound to all import reactions. Defaults to False.

    Warning

    Running open_exchanges on True can lead to infeasible runtimes.

Raises:

  • ValueError: unknown objective.

Returns:
Medium:

The medium that is a solution for the minimisation task.

refinegems.analysis.growth.set_bounds_to_default(model: cobra.Model, reac_bounds: None | str | tuple[float] = None)[source]

Set the reactions bounds of a model to given default values. (Ir)reversibility is retained.

Args:
  • model (cobraModel):

    The model loaded with COBRApy.

  • reac_bounds (None|str|tuple[float], optional):

    The setting for the new reaction bounds. Defaults to None. If None or “cobra”, uses the COBRApy in-built default values (-1000.0, 1000.0). The user can set personal values by entering a tuple of two floats.

Raises:

  • ValueError: Problematic input for bounds, if neither None, “cobra” or a tuple of floats is entered for reac_bounds.

refinegems.analysis.growth.test_auxotrophies(model: cobra.Model, media_list: list[Medium], supplement_list: list[Literal[None, 'min', 'std']], namespace: Literal['BiGG', 'Name'] = 'BiGG') → AuxotrophySimulationReport[source]

Test for amino acid auxothrophies for a model and a list of media.

Tests, if the model growths on the media and if and with what fluxes the 20 proteinogenic amino acids are produced by temporarily adding a sink reaction for each of the amino acids to the model as the objective function.

Args:
  • model (cobraModel):

    The model to be tested. Loaded with COBRApy.

  • media_list (list[Medium]):

    List of media to be tested.

  • supplement_list (list[Literal[None,’min’,’std’]]):

    List of supplement modes for the media.

  • namespace (Literal[‘BiGG’,’Name’], optional):

    String for the namespace to be used for the model. Current options include ‘BiGG’, ‘Name’. Defaults to ‘BiGG’.

Raises:

  • ValueError: Unknown input for namespace parameter.

Returns:
AuxotrophySimulationReport:

The report for the test containing a table of the amino acids and the media names containing the simualted flux values.

refinegems.analysis.growth.test_growth_with_source(model: cobra.Model, element: str, substances: None | str | list[str] = None, medium: None | str | Medium = None, namespace: Literal['BiGG'] = 'BiGG') → SourceTestReport[source]

Test the growth of a model when switching out the source of a given chemical element for a set medium.

Args:
  • model (cobra.Model):

    The model loaded with COBRApy.

  • element (str):

    The chemical symbol e.g., N for nitrogen, to change the sources for.

  • substances (None | str | list[str], optional):

    Substances to switch out in the medium. Can be a list of substance names present in the database, a subset name to be loaded from the database or None, which results in all substances in the database, that contain the element being tested as a source. Option None can potentially run a while. Defaults to None.

  • medium (None | str | Medium, optional):

    The medium to start with. The chosen medium ideally should have all other necessary elements needed for the model to grow. Defaults to None.

  • namespace (Literal[‘BiGG’], optional):

    The namespace to work on. Defaults to ‘BiGG’.

Raises:

  • KeyError: No growth function in model. Please add one beforehand.

Returns:
SourceTestReport:

A report object with the results.

investigate module

Provides functions to investigate the model and test with MEMOTE

These functions enable simple testing of any model using MEMOTE and access to its number of reactions, metabolites and genes.

refinegems.analysis.investigate.get_mass_charge_unbalanced(model: cobra.Model) → tuple[list[str], list[str]][source]

Creates lists of mass and charge unbalanced reactions, without exchange reactions since they are unbalanced per definition

Args:
  • model (cobraModel):

    Model loaded with COBRApy

Returns:
tuple:

Lists of reactions that might cause errors (1) & (2)

  1. list: List of mass unbalanced reactions

  2. list: List of charge unbalanced reactions

refinegems.analysis.investigate.get_metabs_with_one_cvterm(model: libsbml.Model) → list[str][source]

Reports metabolites which have only one annotation, can be used as basis for further annotation research

Args:
  • model (libModel):

    Model loaded with libSBML

Returns:
list:

Metabolite Ids with only one annotation

refinegems.analysis.investigate.get_orphans_deadends_disconnected(model: cobra.Model) → tuple[list[str], list[str], list[str]][source]

Uses MEMOTE functions to extract orphans, deadends and disconnected metabolites

Args:
  • model (cobraModel):

    Model loaded with COBRApy

Returns:
tuple:

Lists of metabolites that might cause errors (1) - (3)

  1. list: List of orphans

  2. list: List of deadends

  3. list: List of disconnected metabolites

refinegems.analysis.investigate.get_reac_with_gpr(model: cobra.Model) → tuple[list[str], list[str]][source]

Extract the reactions that have a gene production rule from a given model.

Args:
  • model (cobra.Model):

    The model loaded with COBRApy.

Returns:
tuple:

Lists of reactions with GPR (1) & (2):

  1. list: List of normal reactions with gpr

  2. list: List of pseudoreactions with gpr

refinegems.analysis.investigate.get_reactions_per_sbo(model: libsbml.Model) → dict[source]

Counts number of reactions of all SBO Terms present

Args:
  • model (libModel):

    Model loaded with libSBML

Returns:
dict:

SBO Term as keys and number of reactions as values