booldog.simulation_result.boolean_result

Boolean simulation results

Classes returned by boolean_simulation() (BooleanSimulationResult, wrapping the state transition graph) and used to represent/plot subsets of the Boolean state space (BooleanStateSpace).

Attributes

`_CYTOSCAPE_AVAILABLE`
`_PILLOW_AVALIBLE`
`logger`
`DEFAULT_COLOURS`	Default hex colours used to represent node states of

Classes

`BooleanStateSpace`	Class representing a subspace (a collection of states) of a Boolean
`BooleanSimulationResult`	Class to contain the result of a Boolean (synchronous) simulation:

Module Contents

booldog.simulation_result.boolean_result._CYTOSCAPE_AVAILABLE = True

booldog.simulation_result.boolean_result._PILLOW_AVALIBLE = True

booldog.simulation_result.boolean_result.logger

booldog.simulation_result.boolean_result.DEFAULT_COLOURS

Default hex colours used to represent node states of 1 (“on”, light green) and 0 (“off”, medium grey) in heatmaps, state transition graph tables, and animations.

Type:: dict of int -> str

class booldog.simulation_result.boolean_result.BooleanStateSpace(network, state_space)

Class representing a subspace (a collection of states) of a Boolean network, e.g. the state space explored by a BooleanSimulationResult, or an arbitrary user-supplied set of states.

network

the Boolean network this state space belongs to.

Type:: BoolDogModel

state_space

the states of the state space, each a mapping of node identifier to state (0 or 1).

Type:: list of dict

set_node_state(node_id, state)

Set the state of a node in all states of the state space.

Parameters:

node_id (str) – The identifier of the node to set the state for.
state (int) – The state to set for the node (0 or 1).

Raises:

ValueError – If node_id is not a valid node identifier in the network, or if state is not 0 or 1.

plot_state_space(title='State Heatmap', plot_nodes=None, cmap=None)

Plot the states of the Boolean network as a heatmap.

Parameters:

title (str, optional) – Title of the heatmap, default is “State Heatmap”.
plot_nodes (None or list of str, optional) – Subset of nodes to plot. If None, plot all nodes.
cmap (ListedColormap, optional) – Colormap to use for the heatmap. Default is binary with green (1) and grey (0).

Returns:

Displays the heatmap directly via plt.show(); the figure is not returned or saved to file.

Return type:

None

__repr__(): str : BooleanStateSpace(network=..., state_space=...).

class booldog.simulation_result.boolean_result.BooleanSimulationResult(network, stg, initial_states)

Class to contain the result of a Boolean (synchronous) simulation: the explored state transition graph together with the initial state(s) it was generated from. Returned by boolean_simulation().

network

the Boolean network the simulation was run on.

Type:: BoolDogModel

stg

the state transition graph, with node labels as '0'/'1' strings (see BooleanSimulationResult).

Type:: networkx.DiGraph

initial_states

the initial state(s) used to generate the state transition graph.

Type:: list of str or None

plot_stg(file=None, booldog_style=True, plot_nodes=None, use_names=True, num_characters=5)

Plot the state transition graph.

Parameters:

file (str or None, optional) – File name to save the generated figure to. If None (default), the figure is not saved to file.
booldog_style (bool, optional) – Whether to use booldog style (default, True) or PyBoolNet style to plot the state transition graph. The booldog style requires pygraphviz; if it is not installed, falls back to the PyBoolNet style with a warning.
plot_nodes (None or list of str, optional) – List of identifiers of subset of nodes to plot. If None, plot all nodes. Only valid if booldog_style is True.
use_names (bool, optional) – Whether to use node names instead of node identifiers in the labels. Only valid if booldog_style is True. Default True.
num_characters (int, optional) – Number of characters to truncate node names/identifiers to in the labels. Only valid if booldog_style is True. Default 5.

Returns:

If booldog_style is True and pygraphviz is available, the pygraphviz AGraph built from the state transition graph (with table-styled node labels) is returned. Otherwise, the graph attribute dictionary of the underlying networkx state transition graph (self.stg.graph) is returned.

Return type:

pygraphviz.AGraph or dict

Notes

If booldog_style is True, the nodes in the state transition graph are represented as tables, with each cell representing a node in the Boolean network. The cells are coloured using DEFAULT_COLOURS (green for “on”/1, grey for “off”/0). If use_names is True, the node names are used instead of the node identifiers in the labels.

plot_state_space(title='State Heatmap', cmap=None)

Plot the states visited in the state transition graph as a heatmap.

Builds a BooleanStateSpace from every node (state) currently in self.stg and delegates to its BooleanStateSpace.plot_state_space().

Parameters:

title (str, optional) – Title of the heatmap, default is “State Heatmap”.
cmap (ListedColormap, optional) – Colormap to use for the heatmap. Default is binary with green (1) and grey (0).

Returns:

Displays the heatmap directly via plt.show().

Return type:

None

export(file)

Export the Boolean simulation result to a file.

Notes

Not yet implemented: this currently does nothing.

Parameters:: file (str or Path) – Path to the output file.

make_animation(base_suid, gif=None, mp4=None, initial_state=None, colour_on=None, colour_off=None, cycle_repeats=3, max_steps=None, duration=400, loop=0, sleep=1)

Render an animated GIF and/or MP4 of the trajectory from initial_state, coloured over a live Cytoscape network view.

Requires py4cytoscape (a running Cytoscape session with the network already loaded) and Pillow.

Parameters:

base_suid (int) – The network SUID from Cytoscape, of the network to base the animation on.
gif (str or Path or None, optional) – Path to save animation (GIF) to. At least one of gif/mp4 must be given.
mp4 (str or Path or None, optional) – Not recommended to use, as this feature is experimental. Path to save animation (MP4) to. At least one of gif/mp4 must be given.
initial_state (str or None, optional) – Initial state to start the animated trajectory from, as a '0'/'1' string matching self.stg node labels. For valid initial states, see the object attribute initial_states. If None (default), uses the single state in self.initial_states (raises ValueError if there is more than one).
colour_on (str or None, optional) – Hex code for colour of “on” (1) nodes, default None uses "#b2df8a" (light green).
colour_off (str or None, optional) – Hex code for colour of “off” (0) nodes, default None uses "#6f6f6f" (medium grey).
cycle_repeats (int, optional) – If there’s a cycle in the trajectory, how many times it should repeat when computing the default max_steps. Only used if max_steps is None. Default 3.
max_steps (int or None, optional) – Maximum number of frames to include in the animation. If None (default), computed as num_states + cycle_len * cycle_repeats, where num_states is the number of distinct states reached from initial_state, and cycle_len is the length of the cycle reached (0 if the trajectory does not cycle back on itself).
duration (int, optional) – Time on each frame, in milliseconds. Default 400. Also used to derive the repeat_delay for the MP4 animation (duration * 4).
loop (int, optional) – Number of times the GIF should loop. 0 is infinite. Default 0. Only applies to gif output.
sleep (int, optional) – Seconds to sleep between Cytoscape network image exports (one per state visited). Default 1. (See Notes.)

Returns:

The animation is written directly to gif and/or mp4; nothing is returned.

Return type:

None

Raises:

ValueError – If neither gif nor mp4 is given, or if initial_state is given but is not a member of self.initial_states, or if initial_state is None and self.initial_states does not contain exactly one state.
ImportError – If py4cytoscape and/or Pillow are not installed.

Notes

The animated trajectory is built by repeatedly following the first successor of each state in self.stg starting from initial_state; it is intended for deterministic (e.g. synchronous) trajectories.

Do not interact with Cytoscape while the networks are being rendered, as this will interfere with the selection and colouring of nodes.

Occasionally Cytoscape exports get corrupted (e.g. node borders are rendered in the wrong order, node fills are placed on the wrong node). This is independent of booldog, and it is unclear why it happens. Rerunning the function may help, and increasing the sleep parameter may also help.

Mp4 export is in development, and not recommended to use.