2. Visualization¶

CobraMod provides users with two different options for visualizing pathways. The first option is Escher, which allows the creation of a 2-dimensional representation. The second option is ‘3d-force-directed-graph’, which enables the creation of an interactive three-dimensional representation using three.js and WebGL.

CobraMod effortlessly combines both tools into the curation and retrieval process. Additionally, they can operate separately to provide visual representations of CobraPy objects.

2.1. Escher¶

Deprecated since version 1.3.0: The original Python integration of Escher will be removed in an upcoming release due to dependency conflicts with Jupyter. Starting with version 1.3.0 of CobraMod, it will no longer be included as a dependency, nor will it be automatically installed or tested. It will only be accessible to ensure compatibility with older environments. In the future, the integration incorporated within CobraMod will replace it. (Refer to Escher-custom for more information.)

CobraMod leverages Escher for visualizing pathways and fluxes. Each CobraMod Pathway comes equipped with the visualize() method, which effortlessly creates pathway maps for the associated reactions. These pathway maps can be displayed using Escher and enhanced with flux distributions. Furthermore, various color schemes and gradients, including linear or quantile normalized options, can be applied to enrich the visualization.

The following is a simple example that includes flux values and a user-defined color scheme.

Warning

The example may or may not work for you due to dependency issues within Escher’s Python binding, as described in the deprecation warning.

from cobramod import Pathway
from random import randint
from cobramod.test import textbook_biocyc_groups

test_model = textbook_biocyc_groups.copy()

# Test fluxes
test_pathway = test_model.groups.get_by_id("test_group")
test_pathway = Pathway._transform(test_pathway)

test_solution = {
    reaction.id: randint(-4, 4) for reaction in test_pathway.members
}
test_pathway.color_negative = "red"
test_pathway.color_positive = "green"
builder = test_pathway.visualize(
    solution_fluxes=test_solution,
)
builder

class cobramod.Pathway(id, name='', members=None, kind=None)¶

A Sub-class from the original COBRApy 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.

2.2. Escher-custom¶

Added in version 1.3.0.

The original Escher integration for Jupyter has dependencies that conflict with current versions of Jupyter Notebook and Jupyter Lab. As a result, it can be challenging to install or may not work at all. Consequently, installation can be pretty challenging or may not work altogether. CobraMod offers its own Escher integration, which currently has limitations on the options that can be set from Python, although the frontend functionality remains unrestricted.

from cobramod import Pathway
from random import randint
from cobramod.test import textbook_biocyc_groups

test_model = textbook_biocyc_groups.copy()

# Test fluxes
test_pathway = test_model.groups.get_by_id("test_group")
test_pathway = Pathway._transform(test_pathway)

test_solution = {
    reaction.id: randint(-4, 4) for reaction in test_pathway.members
}
test_pathway.color_negative = "red"
test_pathway.color_positive = "green"
builder = test_pathway.visualize(
    solution_fluxes=test_solution,
    vis="escher-custom",
    never_ask_before_quit= True,
)
builder

class cobramod.visualization.escher.EscherIntegration(**kwargs)¶

Bases: AnyWidget

Added in version 1.3.0.

An alternative Python integration for Escher .

Parameters:

map_name (str | None) – The name to be used by Escher for the map.
map_json (str | None) – The data structure to be displayed encoded in JSON. Please refer to Escher’s documentation for more information or to the JSON schema.
reaction_data (Dict[str, float] | None) – A dictionary of key-value pairs, where the keys are reaction IDs and the values are flux values.
reaction_scale (List[ReactionScale] | None) – A list consisting of ReactionScale. This list must consist of at least two ReactionScales when it is used.
reaction_styles (List[Any] | None) – Style options for the reactions see Escher’s JavaScript API for options and formatting.
never_ask_before_quit (bool) –
Option to control whether a warning dialog is displayed when the Escher Builder window is closed. See Escher’s JavaScript API for reference.

save_html(filepath)¶

This method creates a standalone HTML file that contains all the data of the Escher map and loads it automatically when it is opened.

Parameters:: filepath (str | Path) – The file in which the HTML file is to be saved.

class cobramod.visualization.escher.ReactionScale¶

Bases: TypedDict

Added in version 1.3.0.

A Python class that represents the options available in Escher. It defines one point on the color scale.

Parameters:

type (Literal["min", "max", "mean", "median", "Q1", "Q3", "value"]) – The type of definition. A specific value can be used here (value), by means of quantiles (“Q1” or “Q3”) or by means of minimum maximum median or mean.
value (Optional[float]) – It is only used to set the value if type value was used.
color (str) – The color to be used for the specified area.
size (int) – The width of the reactions covered by this definition.

Notes

ReactionScale should only be an orientation for the possible options in Python. For further explanations and examples, please refer to Escher’s JavaScript documentation for ‘escher.Builder.options.reaction_scale’.

2.3. Force-directed graph¶

Added in version 1.3.0.

CobraMod provides an integration of ‘3d-force-directed-graph’ that enables a direct representation of a CobraPy Group, Reaction, or CobraMod Pathway object in a three-dimensional format. This offers the benefit of increased space compared to a two-dimensional representation. Moreover, it facilitates the visualization of data, such as fluxes, through animated representations, thereby enhancing the overall comprehension of the information.

The same pathway previously visualized using Escher is now presented in three dimensions below. Additional customization options can be found in the class definition of the ForceGraphIntegration.

from random import randint
from cobramod.test import textbook_biocyc_groups
from cobramod.visualization.force_graph import ForceGraphIntegration

model = textbook_biocyc_groups.copy()
group = model.groups.get_by_id("test_group")


solution = {
    reaction.id: randint(-4, 4) for reaction in group.members
}

w = ForceGraphIntegration()
w.model = group
w.solution = solution
w

class cobramod.visualization.force_graph.ForceGraphIntegration(**kwargs)¶

Added in version 1.3.0.

Widget for displaying a cobra.core.group.Group or cobra.Reaction as a force directed graph.

property model: Type[Group] | Type[Reaction] | None¶

The Model to be represented. It can ether be a cobra.core.group.Group or cobra.Reaction. It is set to None upon initialization.

Return type:: Optional[Union[Type[cobra.core.Group], Type[cobra.Reaction]]]

property solution: Type[Solution] | dict[str, float] | None¶

The flux values to be taken into account when creating the graph. These scale the stoichiometry of the respective reaction. If a reaction is not found in this object, a flux of 1 is assumed. The flux values can either be passed as cobra.Solution or as dict, where the key is the reaction ID and the value is the flux value. It is set to None upon initialization.

Return type:: Optional[Union[Type[cobra.Solution], dict[str, float]]]

save_layout(file)¶

Method to save the layout of the current display. The resulting file is a CSV containing the ID of the metabolite and its X, Y and Z position in the other columns.

Parameters:: file (str | Path) – The path where the layout is to be saved.

load_layout(file)¶

Method to restore the layout that was saved using save_layout().

Parameters:: file (str | Path) – Path to the file containing the saved layout.