cobramod ======== .. py:module:: cobramod .. autoapi-nested-parse:: CobraMod Package CobraMod is a tool for pathway-centric metabolic network curation and extension based on COBRApy. This package facilitates the retrieval of biochemical data from multiple databases and help users extend metabolic networks. CobraMod ensures an easy-friendly API, customization and a record of all the changes made to metabolic models. Important functions from CobraMod that can be imported directly: - get_data: Store and retrieve data from given database. - create_object: Create a corresponding COBRApy object from given identifier. - add_metabolites: Add metabolites from different objects - add_reactions: Add reactions from different objects - add_pathway: Extend given pathway into given model. - test_non_zero_flux: Test given reaction to check for a feasible solution. - add_crossreferences: Check for cross-references. The exclusive class :func:`cobramod.pathway.Pathway` is an extension of :class:`cobra.core.group.Group`. CobraMod uses :mod:`Escher` to visualize the pathway and fluxes of that specific class. Some new methods added: - visualize: Return a Builder for the representation of the pathway. - solution: Filters solution and returns fluxes of only members of the class. By default, CobraMod creates the file "debug.log", which displays the changes, which occurred when running a script. In order to modify the logging, import "debug_log" from "cobramod.debug". The default logging level is defined as INFO. Read the documentation of logging for more information. For a list of databases, load variable :obj:`cobramod.available_databases` Subpackages ----------- .. toctree:: :maxdepth: 1 /autoapi/cobramod/core/index /autoapi/cobramod/data/index /autoapi/cobramod/parsing/index /autoapi/cobramod/visualization/index Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/cobramod/debug/index /autoapi/cobramod/error/index /autoapi/cobramod/retrieval/index /autoapi/cobramod/test/index /autoapi/cobramod/utils/index Classes ------- .. autoapisummary:: cobramod.Pathway Functions --------- .. autoapisummary:: cobramod.add_metabolites cobramod.add_reactions cobramod.create_object cobramod.add_crossreferences cobramod.test_non_zero_flux cobramod.add_pathway cobramod.model_convert cobramod.get_data Package Contents ---------------- .. py:function:: add_metabolites(model, obj, directory = Path.cwd().joinpath('data'), database = None, **kwargs) Adds given object into the model. The options are: - Path or str: A file with the metabolites. E. g: Path.cwd().joinpath("file_with_names.txt") or "./file_with_names.txt" - List[Metabolites]: A list with multiple Metabolite objects. Custom metabolite syntax: :code:`formatted_identifier, name, compartment, chemical_formula, molecular_charge` Metabolite from database: :code:`metabolite_identifier, compartment` - List[str]: A list with multiple str with the mentioned syntax. CobraMod will try to download the biochemical information and create instead custom metabolites if not found in the database. In case of only custom metabolites, it is recommended to use None for the argument database :param model: Model to be expanded and searched for metabolites. :type model: Model :param obj: A Path; a list with either strings or Metabolite objects, or a single string. See syntax above. :param database: Name of database. Check :obj:`cobramod.available_databases` for a list of names. Defaults to None (This is useful for custom metabolites). :type database: str :param directory: Path to directory where the data is located. If nothing is specified, then it defaults to the directory "data" in the current working directory. :type directory: Path :keyword replacement: Dictionary with either the new identifier and/or the identifier of an object inside the model. :kwtype replacement: dict :keyword include_metanetx_specific_ec: Determines whether MetaNetX specific EC numbers should be taken over. These are generally not found in other databases. Furthermore, this could result in non-existing Brenda IDs being created. The default value is False. :raises WrongSyntax (from str): If the syntax is not followed correctly as mentioned above. :raises ValueError: If Keyword Arguments are missing. :raises FileNotFoundError (from Path): if file does not exists .. py:function:: add_reactions(model, obj, directory, database = None, stop_imbalance = False, show_imbalance = True, **kwargs) Adds given object into the model. The options are: - Path: A file with components. E. g. : Path.cwd().joinpath("file_with_names.txt") - List[Reactions]: A list with regular Reactions - List[str]: Either the identifier with its corresponding compartment or a string with all components. This applies for the Path option. E.g. : :code:`reaction_identifier, compartment` For custom reactions :code:`reaction_identifier, reaction_name | coefficient metabolite <-> coefficient metabolite Identifiers of metabolites have to end with an underscore and a compartment: E.g. **`4 OXYGEN-MOLECULE_c`** - List[str]: A list with multiple str with the mentioned syntax. CobraMod will try to use the same metabolites and reactions inside of the model. If not found, then CobraMod will try to download its biochemical information or create custom objects. :param model: Model to expand and search for reactions. :type model: Model :param obj: A Path; a list with either strings or Reaction objects, or a single string. See syntax above. :param database: Name of database. Check :obj:`cobramod.available_databases` for a list of names. Defaults to None (Useful for custom reactions). :type database: str :param directory: Path to directory where data is located. :type directory: Path :param stop_imbalance: If an unbalanced reaction is found, stop the process. Defaults to False. :type stop_imbalance: bool :param show_imbalance: If an unbalanced reaction is found, print output. Defaults to True. :type show_imbalance: bool :keyword replacement: Dictionary with either the new identifier and/or the identifier of an object inside the model. :kwtype replacement: dict :keyword genome: Exclusive for KEGG. Abbreviation for the species involved. Genes will be obtained for this species. :kwtype genome: str :keyword consider_sub_elements: Specifies whether additional cross-references should also be added to the subelements. For example, you can specify whether only the reaction or also its metabolites should be expanded. Defaults to True :keyword include_metanetx_specific_ec: Determines whether MetaNetX specific EC numbers should be taken over. These are generally not found in other databases. Furthermore, this could result in non-existing Brenda IDs being created. The default value is False. :raises WrongSyntax (from str): If the syntax is not followed correctly as mentioned above. :raises ValueError: If Keyword Arguments are missing. :raises FileNotFoundError (from Path): If the file does not exists. .. py:function:: create_object(identifier, directory, database, compartment, replacement = {}, show_imbalance = True, stop_imbalance = False, model = cobra_core.Model(), model_id = None, genome = None) Creates and returns a COBRApy object based on given identifier and database. Identifier names will be formatted. .. hint:: Hyphens will become underscores. :param identifier: Original identifier of the database. :type identifier: str :param directory: Path to directory where data is stored. :type directory: Path :param database: Name of database. Check :obj:`cobramod.retrieval.available_databases` for a list of names. :type database: Optional[str] :param compartment: Location of the object. In case of reaction, all metabolites will be included in the same location. :type compartment: str :param replacement: Dictionary with either the new identifier and/or the identifier of an object inside the model. :type replacement: dict[str, str] :Arguments for reactions: * **stop_imbalance** (*bool*) -- If an unbalanced reaction is found, stop the process. Defaults to False. * **show_imbalance** (*bool*) -- If an unbalanced reaction is found, print output. Defaults to True. * **model** (*Model*) -- Model in which cross-references for reaction and metabolites might be found and used. If nothing is specified, it uses an empty model by default :Special arguments for databases: * **model_id** (*str, optional*) -- Exclusive for BIGG. Retrieve object from specified model. Internal functions use the default: "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 :returns: A Reaction or Metabolite object :rtype: cobra.core.Object .. py:function:: add_crossreferences(object, directory, consider_sub_elements = True, include_metanetx_specific_ec = False) Extends the passed object by cross-references. Here, only the cross-references of reactions or metabolites are expanded. There must be at least one MetaNetX resolvable identifier in the annotation of the object in order to get as many cross-references as possible. Overall, an attempt is made to add all cross-references required by Memote. The only exception are reactom reactions. These are not added due to the current lack of query capabilities on the part of reactom. (Depending on the number of objects this function can take some time). :param object: The CobraPy object to be extended. :param directory: The directory for storing the data. This is where the cache is stored in a folder called XRef. :param consider_sub_elements: Specifies whether additional cross-references should also be added to the subelements. For example, you can specify whether only the reaction or also its metabolites should be expanded. :param include_metanetx_specific_ec: Determines whether MetaNetX specific EC numbers should be taken over. These are generally not found in other databases. Furthermore, this could result in non-existing Brenda IDs being created. The default value is False. .. 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_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 .. 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:function:: model_convert(model) Converts all Group objects in the given model to proper cobramod :class:`cobramod.pathway.Pathway` .. py:function:: get_data(identifier, directory, database, model_id = None, genome = None) Retrieves the Data for given identifier. This function either retrieves from the server of the databases or locally. :param identifier: Name of the object to retrieve :type identifier: str :param dictionary: Location of the files to retrieve or store :type dictionary: str or Path :param database: Name of the database. Check cobramod.retrieval.available_databases for more information :type database: Optional[str] :param model_id: BIGG-specific argument. Name of the model to retrieve information :type model_id: Optional[str] :param genome: (Optional[str]): Name of the genome to retrieve :returns: Data