cobramod.core.extension ======================= .. py:module:: cobramod.core.extension .. autoapi-nested-parse:: Pathway extension This module handles the addition of reactions as a pathway into a model and the corresponding test that comes with it. Most important functions: - add_pathway: Adds a pathway or multiple reactions into a model. - test_non_zero_flux: Checks that the given reaction in a model is active and gives a non-zero flux. Attributes ---------- .. autoapisummary:: cobramod.core.extension.debug_log cobramod.core.extension.cobra_tolerance Classes ------- .. autoapisummary:: cobramod.core.extension.Pathway cobramod.core.extension.DataModel Functions --------- .. autoapisummary:: cobramod.core.extension.summarize cobramod.core.extension.yield_reaction_from_list cobramod.core.extension.find_problem cobramod.core.extension.recursive_flux_test cobramod.core.extension.non_zero_core cobramod.core.extension.test_non_zero_flux cobramod.core.extension.add_reactions_to_Pathway cobramod.core.extension.remove_avoid_reactions cobramod.core.extension.add_pathway_from_file cobramod.core.extension.add_pathway_from_data cobramod.core.extension.add_pathway_from_strings cobramod.core.extension.add_pathway Module Contents --------------- .. py:class:: Pathway(id, name = '', members = None, kind = None) Bases: :py:obj:`cobra.core.Group` A Sub-class from the original COBRApy :class:`cobra.Group`, which inherits all attributes and adds the method solution, to get a Solution for the members of this Class. Attributes vertical (bool, optional): Variable that determines whether the display should be vertical or horizontal using Escher. Defaults to False. color_negative (str or list of int, optional) : The color to use as the endpoint for the negative fluxes during the creation of the color gradient. All colors of the CSS standard can be used here or their RGB representation. color_positive (str or list of int, optional) : The color to use as the endpoint for the positive fluxes during the creation of the color gradient. All colors of the CSS standard can be used here or their RGB representation. color_min_max (list of float, optional) : The maximum and minimum to be taken into account when creating the color gradient. This creates these two values artificially to allow the creation of a data-independent color gradient. Fluxes larger or smaller are ignored accordingly. color_quantile (bool, optional) : Attribute that defines whether the color gradient should be determined through quantiles or equally distributed between the maximum and the minimum. Defaults to False which means that the gradations are evenly distributed. color_n_steps (int, optional) : The number of steps used when creating the color gradient. Uses the number of fluxes by default. The default value is None. color_max_steps (int, optional) : The maximum number of steps to use when creating the color gradient. Default value is 100. .. seealso:: Color names according to the css standard: https://www.w3schools.com/cssref/css_colors.asp .. py:method:: add_members(new_members) Add given list of :class:`cobra.core.reaction.Reaction` into the Pathway. :param new_members: List of Reactions to add to the class. :type new_members: list :raises TypeError: If not all members are proper Reaction objects. .. py:method:: solution(solution) Returns a :class:`cobra.Solution` with only the members of the pathway. :param solution: Original COBRApy :class:`cobra.Solution` to filter. :type solution: Solution :returns: Filtered solution containing only members of the Pathway class. :rtype: Solution .. py:method:: modify_graph(reaction, next_reaction) Modifies the order of the graph. This is useful when merging multiple pathways or joining reactions. In the graph, the selected reaction will be forced to show "next_reaction" as its successor. :param reaction: Identifier of the reaction to modify in the graph. :type reaction: str :param next_reaction: Identifier of the next reaction. This reaction will take place after "reaction". If None is passed, then "reaction" will not have successors. :type next_reaction: str, None :raises GraphKeyError: If the reaction or the next_reaction does not appear :raises in the graph of the pathway.: .. py:method:: visualize(solution_fluxes = None, filename = None, vis = 'escher', never_ask_before_quit = False) .. versionchanged:: 1.3.0 The 'vis' parameter has been added. This allows one to choose between different visualization tools. Returns a :class:`escher.Builder`, which can be used to create visual representations of the pathway. :param solution_fluxes: Series or Dictionary with fluxes. The values will be then showed in the Builder. Defaults to None. :param filename: Path for the HTML. Defaults to "pathway.html" in the current working directory. :param vis: .. versionadded:: 1.3.0 Parameter that determines the visualization tool used. It is possible to choose between the original Escher integration [escher], the one embedded in CobraMod [escher-custom] and a 3-dimensional force directed graph visualization [3d-force]. .. deprecated:: 1.3.0 The original python integration of Escher will be removed in a future version due to dependency conflicts with Jupyter. The integration embedded in CobraMod will take its place in the future. This can already be used by setting 'vis' to "escher-custom". :param never_ask_before_quit: .. versionadded:: 1.3.0 Option to control whether a warning dialog is displayed when the Escher Builder window is closed. Only has an effect when using Escher for visualization. .. py:class:: DataModel(lists) A class that can create a snapshot of a model and generates the summary based on those snapshots. Contains methods to identify differences and save them in multiple formats. .. py:method:: from_model(model) :classmethod: Method to create a DataModel object based on a model object. :param model: Model based on which a DataModel object is to be created. :type model: Model .. py:method:: diff(other) Creates a new DataModel object consisting of the differences between the original and the passed DataModel object. :param other: DataModel to be compared with this one. :type other: DataModel .. py:method:: to_excl(path, model = None, additions=None, deletions=None) Method to save a DataModel as an Excel file. Can also be used to save the changes between two points in time, in an Excel file format. For other formats see :func:`cobramod.summary.DataModel.to_csv` or :func:`cobramod.summary.DataModel.to_txt`. :param path: Location where the file is to be saved. :type path: Path :param model: Model for the extraction of model id and name. :type model: Model :param additions: DataModel that contains the new entities in the model. :type additions: DataModel :param deletions: DataModel that contains the remote entities in the model. :type deletions: DataModel .. py:method:: to_csv(path, model = None, additions=None, deletions=None) Method to save a DataModel as a CSV file. Can also be used to save the changes between two points in time, as a CSV. For other formats see :func:`cobramod.summary.DataModel.to_excl` or :func:`cobramod.summary.DataModel.to_txt`. :param path: Location where the file is to be saved. :type path: Path model (Model): Model for the extraction of model id and name. additions (DataModel): DataModel that contains the new entities in the model. deletions (DataModel): DataModel that contains the remote entities in the model. .. py:method:: to_txt(path, model = None, additions=None, deletions=None) Method to save a DataModel as a txt file. Can also be used to save the changes between two points in time, as a txt. For other formats see :func:`cobramod.summary.DataModel.to_excl` or :func:`cobramod.summary.DataModel.to_csv`. :param path: Location where the file is to be saved. :type path: Path :param model: Model for the extraction of model id and name. :type model: Model :param additions: DataModel that contains the new entities :type additions: DataModel :param in the model.: :param deletions: DataModel that contains the remote entities :type deletions: DataModel :param in the model.: .. py:function:: summarize(model, original, filename) Produces the short summary and another one in the defined format. :param model: model with recent changes. :type model: Model :param original: Object with data from the previous model. Use method :func:`cobramod.summary.DataModel`. :type original: DataModel :param filename: Location where the summary should be stored. The file format is determined by the suffix of the filename. Thus, '.txt', '.csv' or '.xlsx' can be used. :type filename: Path .. py:data:: debug_log .. py:data:: cobra_tolerance :type: float .. py:function:: yield_reaction_from_list(sequence, compartment, directory, database, show_imbalance, stop_imbalance, replacement, model, model_id, genome) Yields a Reaction from given list of identifiers . .. hint:: Hyphens will become underscores. Double hyphens become single underscores. :param sequence: Identifiers for the reactions. :type sequence: list :param directory: Path to directory where data is located. :type directory: Path :param database: Name of the database. Check :obj:`cobramod.available_databases` for a list of names. :type database: Optional[str] :param compartment: Location of the reaction. :type compartment: str :param replacement: Original identifiers to be replaced. Values are the new identifiers. This applies to metabolites. :type replacement: dict :param stop_imbalance: If unbalanced reaction is found, stop process. :type stop_imbalance: bool :param show_imbalance: If unbalanced reaction is found, show output. :type show_imbalance: bool :param model_id: Exclusive for BIGG. Retrieve object from specified model. :type model_id: str :param genome: Exclusive for KEGG. Abbreviation for the specie involved. Genes will be obtained for this specie. :type genome: str, optional :returns: New Reactions objects :rtype: Generator .. py:function:: find_problem(model, identifier) Return a List with the metabolite identifiers that must have a sink reaction to make the reaction carry a non-zero flux. .. py:function:: recursive_flux_test(model, identifier, times = 0) Main part of the non-zero flux test. It is a recursive function. Firstly, the function checks if there a non-zero flux. If not, it will create the necessary sink reactions and rerun the test. This function warns the user if sink reactions were created. :param model: Model where the reactions are located :type model: Model :param reaction: identifier of the reaction :type reaction: str :param times: Tracks how many times this function was called. :type times: int :returns: optimization value :rtype: Optional[float] :raises OptimizationError: Whenever a reaction needs manual intervention .. py:function:: non_zero_core(model, identifier) Performs non-zero flux test. In this test, a reaction is tested to make sure it can carry a flux. If necessary, CobraMod creates sink reactions to simulate turnover of metabolites that participate in the reaction. Warnings will be shown for these cases. :param model: Model that contains the reaction :type model: Model :param reaction: identifier of the reaction :type reaction: str :raises OptimizationError: If given reaction needs manual curation .. py:function:: test_non_zero_flux(model, reaction) Performs non-zero flux test. In this test, a reaction is tested to make sure it can carry a flux. If necessary, CobraMod creates sink reactions to simulate turnover of metabolites that participate in the reaction. Warnings will be shown for these cases. :param model: Model that contains the reaction :type model: Model :param reaction: identifier of the reaction :type reaction: str :raises OptimizationError: If given reaction needs manual curation .. py:function:: add_reactions_to_Pathway(model, pathway, sequence, ignore_list) From a sequence of Reaction objects, add each Reaction into given model. It checks if new reactions do not break the optimized value. All reactions are added to a common CobraMod Pathway. :param model: Model to expand. :type model: Model :param pathway: Common Pathway to add the reaction. :type pathway: Pathway :param sequence: List with :class:`cobra.core.reaction.Reaction` objects :type sequence: list :param ignore_list: A sequence of reactions that should be added but not tested for a non-zero-flux. :type ignore_list: list, optional :raises TypeError: if reactions are not valid Reaction objects .. py:function:: remove_avoid_reactions(sequence, avoid_list) Updates the given sequence taking into consideration reactions to avoid in the sequence :param sequence: identifier of the reactions to update :type sequence: list :param avoid_list: Reactions that should not be included in the model :type avoid_list: list .. py:function:: add_pathway_from_file(model, file, identifier, database, replacement, ignore_list, stop_imbalance, show_imbalance, directory, genome, model_id) Adds a Pathway into given model. The reactions are created from:: - Path or str: A file with components. E. g. : Path.cwd().joinpath("file_with_names.txt") or "./file_with_names.txt" This applies for both options : :code:`reaction_identifier, compartment` For custom reactions :code:`reaction_identifier, reaction_name | coefficient metabolite <-> coefficient metabolite :param model: Model to expand. :type model: Model :param path: Location of the file. :type path: Union[str, Path] :param database: Name of the database. Check :obj:`cobramod.available_databases` for a list of names. :type database: str :param identifier: Common :class:`cobramod.pathway.Pathway` identifier :type identifier: str Argument for complex pathways: avoid_list (list, optional): A sequence of reactions identifiers to avoid adding to the model. replacement (dict, optional): Original identifiers to be replaced. Values are the new identifiers. This applies to metabolites as well. User can rename or replace identifiers using this argument. ignore_list (list, optional): A sequence of reactions that should be added but not tested for a non-zero-flux. Arguments for utilities: stop_imbalance (bool, optional): If an unbalanced reaction is found, stop the process. Defaults to False. show_imbalance (bool, optional): If an unbalanced reaction is found, print output. Defaults to True. model_id (str, optional): Exclusive for BIGG. Retrieve object from specified model. Pathways are not available. Defaults to: "universal" genome (str, optional): Exclusive for KEGG. Abbreviation for the species involved. Genes will be obtained for this species. List available at https://www.genome.jp/kegg/catalog/org_list.html .. py:function:: add_pathway_from_data(model, data, group, directory, database, compartment, avoid_list, replacement, ignore_list, stop_imbalance, show_imbalance, model_id, genome) Adds a pathway into given model from a dictionary with the information of the pathway into given model from a dictionary with the information of the model. :param model: Model to expand. :type model: Model :param data_dict: Dictionary with the information for the pathway. :type data_dict: dict :param directory: Path for directory to stored and retrieve data. :type directory: Path :param database: Name of the database to search for reactions and metabolites. Check :obj:`cobramod.available_databases` for a list of names. :type database: str :param compartment: Location of the reactions. Arguments for complex pathways: avoid_list (list, optional): A sequence of reactions identifiers to avoid adding to the model. replacement (dict, optional): Original identifiers to be replaced. Values are the new identifiers. This applies to metabolites as well. User can rename or replace identifiers using this argument. ignore_list (list, optional): A sequence of reactions that should be added but not tested for a non-zero-flux. Arguments for utilities: stop_imbalance (bool): If unbalanced reaction is found, stop process. show_imbalance (bool): If unbalanced reaction is found, show output. model_id (str, optional): Exclusive for BIGG. Retrieve object from specified model. Pathway are not available. Defaults to: "universal" genome (str, optional): Exclusive for KEGG. Abbreviation for the specie involved. Genes will be obtained from this specie. List available at https://www.genome.jp/kegg/catalog/org_list.html .. py:function:: add_pathway_from_strings(model, identifier, sequence, database, compartment, directory, avoid_list, replacement, ignore_list, stop_imbalance, show_imbalance, model_id, genome) Adds a sequence of identifiers to given model. It will automatically test for valid optimized values. :param model: Model to expand. :type model: Model :param identifier: Common :class:`cobramod.pathway.Pathway` identifier. :type identifier: str :param sequence: List reaction identifiers. :type sequence: list :param database: Name of the database. Check :obj:`cobramod.available_databases` for a list of names. :type database: Optional[str] :param compartment: Location of the reactions. :param directory: Path for directory to store and retrieve data. :type directory: Path Arguments for complex pathways: avoid_list (list, optional): A sequence of reactions identifiers to avoid adding to the model. replacement (dict, optional): Original identifiers to be replaced. Values are the new identifiers. This applies to metabolites as well. User can rename or replace identifiers using this argument. ignore_list (list, optional): A sequence of reactions that should be added but not tested for a non-zero-flux. Arguments for utilities: stop_imbalance (bool): If unbalanced reaction is found, stop process. show_imbalance (bool): If unbalanced reaction is found, show output. model_id (str, optional): Exclusive for BIGG. Retrieve object from specified model. Pathway are not available. genome (str): Exclusive for KEGG. Abbreviation for the specie involved. Genes will be obtained from this specie. List available at https://www.genome.jp/kegg/catalog/org_list.html .. py:function:: add_pathway(model, pathway, directory, compartment, database = None, group = None, avoid_list = [], replacement = {}, ignore_list = [], filename = None, stop_imbalance = False, show_imbalance = True, model_id = '', genome = None) Adds a pathway from the given database into a model. The argument 'pathway' can be a list of reactions identifiers or explicitly a pathway identifier. A group of reactions will be included in a custom group. The data will be downloaded and structured according to the database. :param model: Model to expand. :type model: Model :param pathway: Sequence of reaction identifiers or a single identifier for a pathway. Examples: ["RXN-2206", "RXN-207"], (Reaction to download from a database) "PWY-886", (Pathway to download from a database) ["ACALDt, RXN_2206_c"], (which are reactions already in the model) :type pathway: list, str :param directory: Path for the directory to store and retrieve data. :type directory: Path :param database: Name of the database. Check :obj:`cobramod.available_databases` for a list of names. When adding reactions of the model, this argument is not necessary Defaults to None. :type database: str, Optional :param compartment: Location of the reactions. If adding reaction already in the model, this argument will not change the reaction's compartment. :param group: Common :class:`cobramod.pathway.Pathway` identifier. This will overwrite the name of the pathway. :type group: str, optional Arguments for complex pathways: avoid_list (list, optional): A sequence of reactions identifiers to avoid adding to the model. replacement (dict, optional): Original identifiers to be replaced. Values are the new identifiers. This applies to metabolites as well. User can rename or replace identifiers using this argument. ignore_list (list, optional): A sequence of reactions that should be added but not tested for a non-zero-flux. Arguments for summary: filename (Path, optional): Location for the summary. Defaults to "summary" in the current working directory. The file format is defined by the suffix. The suffixes '.txt', '.csv' and '.xlsx' can be used. If the filename is set to None, no summary will be created. Arguments for utilities: stop_imbalance (bool, optional): If an unbalanced reaction is found, stop the process. Defaults to False. show_imbalance (bool, optional): If an unbalanced reaction is found, print output. Defaults to True. model_id (str, optional): Exclusive for BIGG. Retrieve object from specified model. Pathways are not available. Defaults to: "universal" genome (str, optional): Exclusive for KEGG. Abbreviation for the species involved. Genes will be obtained for this species. List available at https://www.genome.jp/kegg/catalog/org_list.html