3.5. kda.plotting

3.5.1. Diagram Plotting

The plotting module contains code to plot partial diagrams (undirected spanning trees), directional diagrams, and flux diagrams, as well as cycles and ode_solver() results.

The two main functions used for plotting KDA-generated diagrams are draw_diagrams() and draw_cycles(). draw_diagrams is used for plotting kinetic diagrams, partial diagrams, directional diagrams, and flux diagrams, while draw_cycles is used for plotting cycles in the kinetic diagram.

For example, for a 4-state model we start by generating the KineticModel and plotting the kinetic diagram:

import os
import numpy as np
import kda
from kda import plotting

# define matrix with reaction rates set to 1
K = np.array([
    [0, 1, 0, 1],
    [1, 0, 1, 1],
    [0, 1, 0, 1],
    [1, 1, 1, 0],
])
# create a KineticModel from the rate matrix
model = kda.KineticModel(K=K, G=None)
# specify the positions of all nodes in NetworkX fashion
node_positions = {0: [1, 1], 1: [-1, 1], 2: [-1, -1], 3: [1, -1]}
# plot and save the input diagram in the current directory
plotting.draw_diagrams(model.G, pos=node_positions, path=os.getcwd(), label="input")

The output kinetic diagram figure, input.png:

We can also plot all cycles:

# build the cycles for the model
model.build_cycles()
# plot cycles with coral-colored nodes
plotting.draw_cycles(
    G=model.G,
    cycles=model.cycles,
    pos=node_positions,
    path=os.getcwd(),
    # set color-by-target to label the target nodes
    cbt=True,
    label="cycles_panel",
)

The output cycles figure, cycles_panel.png:

Lastly, we can generate the directional and flux diagrams:

# generate the flux and directional diagrams
model.build_flux_diagrams()
model.build_directional_diagrams()
# plot and save the directional diagrams as a panel
plotting.draw_diagrams(
    model.directional_diagrams,
    pos=node_positions,
    rows=model.G.number_of_nodes(),
    path=os.getcwd(),
    # set color-by-target to label the target nodes
    cbt=True,
    label="directional_panel",
)
# flatten the flux diagrams since they are stored in nested lists
flux_diagrams = [g for l in model.flux_diagrams if not l is None for g in l]
# plot and save the flux diagrams as a panel
plotting.draw_diagrams(
    flux_diagrams,
    pos=node_positions,
    path=os.getcwd(),
    # set color-by-target to label the target nodes
    cbt=True,
    label="flux_panel",
)

The output directional and flux diagrams figures, directional_panel.png and flux_panel.png:

directional_panel.png

flux_panel.png

NOTE: For more examples visit the KDA examples repository.

draw_diagrams(diagrams, pos=None, panel=True, panel_scale=2, font_size=12, cbt=False, rows=None, cols=None, path=None, label=None, curved_arrows=False)[source]

Plots any number of input diagrams. Typically used for plotting kinetic diagrams, or arrays of partial, directional, or flux diagrams.

Parameters:

diagrams (list of NetworkX graph objects) – List of diagrams or single diagram to be plotted.
pos (dict, optional) – Dictionary where keys are the indexed states (e.g. 0, 1, 2, …, N) and the values are the x, y coordinates for each node. If not specified, NetworkX.spring_layout() is used.
panel (bool, optional) – Tells the function to output diagrams as an NxM matrix of subplots, where N and M are the number of rows and columns, respectively. True will output a panel figure, False will output each figure individually. Default is False.
panel_scale (float, optional) – Parameter used to scale figure if panel=True. Linearly scales figure height and width. Default is 2.
font_size (int, optional) – Sets the font size for the figure. Default is 12.
cbt (bool, optional) – ‘Color by target’ option that paints target nodes with a coral red. Typically used for plotting directional and flux diagrams. Default is False.
rows (int, optional) – Number of rows. Default is None, which results in the number of rows being determined based on the number of diagrams input.
cols (int, optional) – Number of columns. Default is None, which results in the number of columns being determined based on the number of diagrams input.
path (str, optional) – String of save path for figure. If a path is specified the figure(s) will be saved at the specified location. Default is None.
label (str, optional) – Figure label used to create unique filename if path is input. Includes .png file extension. Default is None.
curved_arrows (bool, optional) – Switches on arrows with a slight curvature to separate double arrows for directional diagrams. Default is False.

Notes

When using panel=True, if number of diagrams is not a perfect square, extra plots will be generated as empty coordinate axes.

Examples

The draw_diagrams() function allows for easy plotting of KDA-generated diagrams:

import os
import numpy as np
import kda
from kda import plotting

# define matrix with reaction rates set to 1
K = np.array([
    [0, 1, 1],
    [1, 0, 1],
    [1, 1, 0],
])
# create a KineticModel from the rate matrix
model = kda.KineticModel(K=K, G=None)
# generate the directional diagrams
model.build_directional_diagrams()
# specify the positions of all nodes in NetworkX fashion
node_positions = {0: [0, 1], 1: [-0.5, 0], 2: [0.5, 0]}
# plot and save the input diagram in the current directory
plotting.draw_diagrams(model.G, pos=node_positions, path=os.getcwd(), label="input")
# plot and save the directional diagrams as a panel
plotting.draw_diagrams(
    model.directional_diagrams,
    pos=node_positions,
    path=cwd,
    # set color-by-target to label the target nodes
    cbt=True,
    label="directional_panel",
)

This will save two files, input.png and directional_panel.png, in your current working directory.

draw_cycles(G, cycles, pos=None, panel=True, panel_scale=2, rows=None, cols=None, font_size=12, cbt=False, curved_arrows=False, path=None, label=None)[source]

Plots a diagram with a cycle labeled.

Parameters:

G (NetworkX.MultiDiGraph) – Input diagram used for plotting the cycles.
cycles (list of lists of int) – List of cycles or individual cycle to be plotted, index zero. Order of node indices does not matter.
pos (dict, optional) – Dictionary where keys are the indexed states (e.g. 0, 1, 2, …, N) and the values are the x, y coordinates for each node. If not specified, NetworkX.spring_layout() is used.
panel (bool, optional) – Tells the function to output diagrams as an NxM matrix of subplots, where N and M are the number of rows and columns, respectively. True will output a panel figure, False will output each figure individually. Default is False.
panel_scale (float, optional) – Parameter used to scale figure if panel=True. Linearly scales figure height and width. Default is 2.
font_size (int, optional) – Sets the font size for the figure. Default is 12.
cbt (bool, optional) – ‘Color by target’ option that paints target nodes with a coral red. Default is False.
curved_arrows (bool, optional) – Switches on arrows with a slight curvature to separate double arrows for directional diagrams. Default is False.
path (str, optional) – String of save path for figure. If a path is specified the figure(s) will be saved at the specified location. Default is None.
label (str, optional) – Figure label used to create unique filename if path is input. Includes .png file extension. Default is None.

Notes

When using panel=True, if number of diagrams is not a perfect square, extra plots will be generated as empty coordinate axes.

Examples

The draw_cycles() function allows for easy plotting of cycles in kinetic diagrams:

import os
import numpy as np
import kda
from kda import plotting

# define matrix with reaction rates set to 1
K = np.array([
    [0, 1, 0, 1],
    [1, 0, 1, 1],
    [0, 1, 0, 1],
    [1, 1, 1, 0],
])
# create a KineticModel from the rate matrix
model = kda.KineticModel(K=K, G=None)
# specify the positions of all nodes in NetworkX fashion
node_positions = {0: [1, 1], 1: [-1, 1], 2: [-1, -1], 3: [1, -1]}
# build the cycles for the model
model.build_cycles()
# plot cycles with coral-colored nodes
plotting.draw_cycles(
    G=model.G,
    cycles=model.cycles,
    pos=node_positions,
    path=os.getcwd(),
    # set color-by-target to label the target nodes
    cbt=True,
    label="cycles_panel",
)

This will save a file cycles_panel.png in your current working directory displaying all 3 cycles for the 4-state model.

draw_ode_results(results, figsize=(5, 4), legendloc='best', bbox_coords=None, path=None, label=None)[source]

Plots probability time series for all states generated by ode_solver().

Parameters:

results (Bunch object) – Contains time information (results.t) and function information at time t (results.y), as well as various other fields.
figsize (tuple, optional) – Tuple of the form (x, y), where x and y are the x and y-axis figure dimensions in inches. Default is (5, 4).
legendloc (str, optional) – String passed to determine where to place the legend for the figure. Default is "best".
bbox_coords (tuple, optional) – Tuple of the form (x, y), where x and y are the x and y-axis coordinates for the legend. Default is None.
path (str, optional) – String of save path for figure. If a path is specified the figure will be saved at the specified location. Default is None.
label (str, optional) – Figure label used to create unique filename if path is input. Includes .png file extension. Default is None.

Functions

`draw_cycles`(G, cycles[, pos, panel, ...])	Plots a diagram with a cycle labeled.
`draw_diagrams`(diagrams[, pos, panel, ...])	Plots any number of input diagrams.
`draw_ode_results`(results[, figsize, ...])	Plots probability time series for all states generated by `ode_solver()`.