booldog package

booldog: A Python package for analyses of Boolean and semi-qualitative Boolean networks

class booldog.RegulatoryNetwork(graph, **kwargs)

Bases: booldog.bool_graph.BooleanGraph

A class to represent a regulatory network.

Initialise a regulatory network from a Boolean graph.

Parameters
  • graph (booldog.BooleanGraph or dict or str) – If not a booldog.BooleanGraph instance, then correct input for initializing a booldog.BooleanGraph.

  • **kwargs – In the case graph is not a BooleanGraph instance, additional keyword arguments passed to booldog.BooleanGraph.

boolean_simulation(initial_values=None, plot=True, export=False, **kwargs)

Compute a Boolean simulation (or state transition) from optional initial values.

Parameters
  • initial_values (int, str, list, dict, optional) – Initial state, see Notes for format

  • plot (bool, optional) – Whether to plot the simulation results

  • export (bool or path object or string, optional) – False, or a file path to save simulation results. Exports valu

  • **kwargs – If plot=True , additional keyword arguments are passed to plot_boolean_simulation().

Notes

This is a wrapper for pyboolnet.state_transition_graphs.primes2stg, and therefore takes the same argument format for initial states.

From PyBoolNet documentation:

Either a list of states in dict or str format::

    init = ["000", "111"]
    init = ["000", {"v1":1,"v2":1,"v3":1}]

or as a function that is called on every state and must return
either True or False to indicate whether the state ought to be initial::

    init = lambda x: x["v1"]>=x["v2"]

or by a subspace in which case all the states contained in it are
initial::

    init = "--1"
    init = {"v3":1}
continuous_simulation(node_events={}, edge_events={}, t_min=0, t_max=30, initial_state=0, plot=True, export=False, ode_system=None, **kwargs)

Run continuous semi-qualitative simulation.

Parameters
  • node_events (None or list of dict, optional) – List of node events with a dictionary defining each event. See Notes for description of event definitions.

  • edge_events (None or list of dict, optional) – Disrupt connections #TODO not implemented

  • t_min (float, optional) – Interval of integration, simulation starts with t=t_min and integrates until it reaches t=t_max.

  • t_max (float, optional) – Interval of integration, simulation starts with t=t_min and integrates until it reaches t=t_max.

  • initial_state (float or int or array or dict, optional) – Initial state of nodes. See Notes for description of format.

  • plot (bool, optional) – Whether to plot the simulation results

  • export (bool or path object or string, optional) – False, or a file path to save simulation results. Exports values to 5 decimal points.

  • ode_system (None or booldog.ODE(), optional) – If none, the ODE is created with transform_bool_to_continuous()

  • **kwargs

    If ode_system is None, additional keyword arguments are passed to transform_bool_to_continuous(). For description of these arguments see booldog.ODE().

    If plot=True , additional keyword arguments are passed to plot_simulation().

Returns

  • t (ndarray, shape (n_time_points,)) – Time-points.

  • y (ndarray, shape (n_time_points, n_nodes)) – Values of the solution at t.

Notes

Format of the node_events parameter

The node events are passed as a list of dictionaries defining each event. Dictionary keys are:

  • time: time at which the event occurs

  • node: name of node which is perturbed

  • value: value to which the node is set

  • duration: (optional) duration for which the node is fixed if longer than 0, (i.e. not a point perturbation)

Example - at timepoint 10, node X is set to 0.25 for 5 time-steps. and at timepoint 12, node Y and Z are set to 1 for 0 timesteps:

node_events = [
    {'time':10, 'node':'X', 'value':.25, 'duration':5},
    {'time':12, 'node':'Y', 'value':1},
    {'time':12, 'node':'X', 'value':1}
]
Format of the initial_state parameter

If the initial state is an int or float, the value is assigned for all variables. Otherwise the parameter argument should be a dict with keys as node names and values for their initial state. In this case, if the initial state is not defined for all nodes, a default key with the default value should also be present in the dict.

generate_states(fixed=None)

Generate all possible states of the graph.

Parameters

fixed (dict) – A dictionary of {node:state} to be kept fixed, with node in graph.nodes, and state in {0, 1}.

Yields

state (np.array) – length n array with a state of the graph.

get_interactions(direction='out')

direction out: interactions[a][b] a –> b direction in: interactions[a][b] a <– b

get_parents(node)

Fetch regulators/inputs to a node

Parameters

node (str) – Node name

Returns

parents – Set of parent nodes

Return type

set

plot_boolean_simulation(fig, booldog_style=True, plot_nodes=None)

Plot the state transition graph, from optional initial values.

Parameters
  • fig (str) – File name of generated figure

  • initial_values (int, str, list, dict) – Initial state, see Notes for format

  • new_style (bool) – Whether to use booldog style, or PyBoolNet style (default) to plot the state transition graph. Requires pygraphviz (If not installed, will default to PyBoolNet version.)

  • plot_nodes (None or list of str, optional) – Subset of nodes to plot. If None, plot all nodes. Only valid if new_style is True.

plot_simulation(t, y, node_events=None, edge_events=None, plot_nodes=None, title=None, figsize=(20, 10), **kwargs)

Plot simulation results.

Called by continous_simulation().

Parameters
  • t (ndarray, shape (n_time_points,)) – Time-points.

  • y (ndarray, shape (n_time_points, n_nodes)) – Values of the solution at t.

  • plot_nodes (None or list of str or list of lists of str, optional) – Subset of nodes to plot. If None, plot all nodes. If a list of lists, each sublist is plotted as a subplot.

  • node_events (None or list of dict, optional) – List of node events with a dictionary defining each event. See Notes for description of event definitions.

  • edge_events (None or list of dict, optional) – Disrupt connections #TODO not implemented

  • title (None or string or list of string) – If str, main title of the plot. If a list of str, subtitles of subplots as defined by plot_node. In this case plot_nodes should be a list of lists, and title should be the same length as plot_nodes.

  • figsize ((float, float)) – Width, height in inches.

  • **kwargs – ignored

Returns

  • fig (matplotlib.figure.Figure)

  • axes (array of matplotlib.axes.Axes)

plot_state_transitions(fig, booldog_style=True, plot_nodes=None)

Plot the state transition graph, from optional initial values.

Parameters
  • fig (str) – File name of generated figure

  • initial_values (int, str, list, dict) – Initial state, see Notes for format

  • new_style (bool) – Whether to use booldog style, or PyBoolNet style (default) to plot the state transition graph. Requires pygraphviz (If not installed, will default to PyBoolNet version.)

  • plot_nodes (None or list of str, optional) – Subset of nodes to plot. If None, plot all nodes. Only valid if new_style is True.

primes_to_matrices()

Reduce graph to Activation and Inhibition Matrices.

Returns

  • Act (np.array) – n * n matrix with entry m_{i, j} = 1 iff node_j activates node_i

  • Inh (np.array) – n * n matrix with entry m_{i, j} = 1 iff node_j inhibits node_i

Notes

Only if graph is of type threshold (i.e. SQUAD) does this make sense. Used in SquadODE Create logic matrices

steady_states()

All steady states of the Boolean graph.

transform_bool_to_continuous(transform, **kwargs)

Generate an ODE from RegulatoryNetwork/Boolean graph.

Parameters
  • transform (str) – One of accepted transforms. See booldog.ode.transforms for accepted options.

  • **kwargs – Additional keyword arguments passed to booldog.ODE().

booldog.ODE_factory(graph, transform, **kwargs)

Create a booldog.ode.ODE from RegulatoryNetwork.

Parameters
  • graph (RegulatoryNetwork or BooleanGraph) – Input graph.

  • transform (str) – One of accepted transforms. See booldog.ode.transforms or Notes for options.

  • **kwargs – Additional arguments and keyword arguments passed to specific parent class initializer.

Returns

ode – A ODE system

Return type

booldog.ode.ODE

Notes

For specific transforms, see the relevant parent class for keyword arguments (**kwargs).

The parent class per transform is defined in booldog.ode.ode_parent_classes.

If the parameter is an int or float, the value is assigned for all variables. Otherwise the parameter argument should be a dict with keys as node names and values for their initial state. In this case, if the initial state is not defined for all nodes, a default key with the default value should also be present in the dict.

Here follows a summary of the transform-specific keyword arguments

‘squad’

‘boolecube’

‘hillcube’

‘normalisedhillcube’

Submodules