booldog.continuous.ode_factory

Build ODE systems (continuous relaxations) from Boolean networks.

ode_factory() is the main entry point: given a booldog.BoolDogModel and a transform name, it returns an ODE subclass instance (BooleCubeODE or SquadODE) whose dxdt callable is suitable for scipy.integrate.solve_ivp.

Attributes

logger
ode_classes	transform to ODE class translation
transforms	list of accepted ODE transforms

Classes

ODE	Base class for the ODE systems built by ode_factory().
BooleCubeODE	ODE system built via multivariate polynomial (multilinear)
SquadODE	ODE system built via the SQUAD sigmoidal transform of a Boolean

Functions

ode_factory(network, transform, **kwargs)

Create an ODE instance from a Boolean network.

Module Contents

booldog.continuous.ode_factory.logger

booldog.continuous.ode_factory.ode_factory(network, transform, **kwargs)

Create an ODE instance from a Boolean network.

Parameters:

• network (booldog.BoolDogModel) – Input Boolean network to transform.

• transform (str) – One of the accepted transforms (case-insensitive). See transforms or Notes for options.

• **kwargs – Additional arguments and keyword arguments passed to the selected ODE class’s constructor.

Returns:

ode – A BooleCubeODE or SquadODE instance (an ODE subclass), depending on transform.

Return type:

ODE

Notes

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

The class per transform is defined in ode_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’

• SquadODE

• gamma : decay rate

• h : sigmoidal gain

‘boolecube’

• BooleCubeODE

• tau : life-time of species

‘hillcube’

• BooleCubeODE

• tau : life-time of species

• n : Hill coefficient

• k : Hill dissociation constant

‘normalisedhillcube’

• BooleCubeODE

• tau : life-time of species

• n : Hill coefficient

• k : Hill dissociation constant

class booldog.continuous.ode_factory.ODE(network, transform)

Base class for the ODE systems built by ode_factory().

Not intended to be instantiated directly. Its subclasses (BooleCubeODE, SquadODE — selected via the transform argument) each build their own dxdt right-hand-side function; this class only provides the shared event_function (used by scipy.integrate.solve_ivp to stop integration exactly at a perturbation time) and update (rebuild dxdt, e.g. after freezing a subset of nodes) machinery.

n

number of nodes in the network.

Type:

int

boolean_network

the underlying Boolean network.

Type:

booldog.BoolDogModel

transform

name of the transform used to build this ODE system.

Type:

str

event_function(t, x, event_t, *args)

Event function for events of scipy.integrate.solve_ivp.

Returns the signed time-to-event (t - event_t); its root is event_t, so solve_ivp uses it to stop integration exactly at that time (e.g. so a node perturbation can then be applied).

Parameters:

• t (float) – Current time-point of the simulation.

• x (ndarray) – Current state (unused; present to match the event-function signature expected by solve_ivp).

• event_t (float) – Time-point at which the event should trigger.

• *args – Ignored; absorbs any extra positional arguments solve_ivp passes via its args= parameter.

update(off_nodes=None)

Recompute and reset self.dxdt.

Shortcut to the ODE subclass’s _get_system method; used e.g. to change which nodes are held constant partway through a simulation.

Parameters:

off_nodes (list of int, optional) – List of node indices to set derivative to 0, i.e. these nodes will remain constant in simulation.

class booldog.continuous.ode_factory.BooleCubeODE(network, transform, tau=1, n=3, k=0.5, **kwargs)

Bases: ODE

ODE system built via multivariate polynomial (multilinear) interpolation of a Boolean network’s prime implicants.

Backs the 'boolecube', 'hillcube', and 'normalisedhillcube' transforms; transform selects which transform_function (identity, hill, or normalised_hill respectively) is applied to the state before interpolation.

param_n = 3

Hill coefficient

Type:

arraylike

param_k = 0.5

Hill dissociation constant

Type:

arraylike

param_tau = 1

life-time of species

Type:

arraylike

param_dict

convenience mapping from parameter name (“n”, “k”, “tau”) to its per-node array (param_n, param_k, param_tau).

Type:

dict

B1

multilinear interpolation of the network’s Boolean rules, B1(x) -> ndarray; see homologue_b1.

Type:

function

dxdt

the ODE system’s right-hand side, dx/dt = f(t, x)

Type:

function

hill(x_array)

Hill-function transform of a state vector.

Parameters:

x_array (ndarray) – State to transform, shape (n,) (per-node values, typically in [0, 1]).

Returns:

x_array**n / (x_array**n + k**n), computed element-wise using the per-node param_n/param_k arrays. Same shape as x_array.

Return type:

ndarray

normalised_hill(x_array)

Hill-function transform, normalised so that normalised_hill(1) == 1.

Parameters:

x_array (ndarray) – State to transform, shape (n,).

Returns:

hill(x_array) / hill(1), element-wise. Same shape as x_array.

Return type:

ndarray

identity(x_array)

No-op transform, used for the 'boolecube' transform.

Parameters:

x_array (ndarray) – State to transform, shape (n,).

Returns:

x_array, unchanged.

Return type:

ndarray

_get_system(off_nodes=None)

Build the dxdt(t, x_array, *args) right-hand-side function.

Nodes with param_tau == 0 are automatically added to off_nodes (their derivative is always 0), in addition to any indices passed in explicitly.

Parameters:

off_nodes (iterable of int, optional) – Node indices whose derivative should be forced to 0 (held constant), on top of any zero-tau nodes.

Returns:

dxdt – Function dxdt(t, x_array, *args) -> ndarray giving dx/dt = (B1(transform_function(x)) - x) / tau element-wise, after clipping x_array to [0, 1]; suitable as the fun argument of scipy.integrate.solve_ivp.

Return type:

callable

homologue_b1()

Build the multilinear-interpolation function B1(x).

For each node, enumerates the states consistent with its positive prime implicants (expanding any parents left free by a prime over all their combinations) and sums, over those states, a product of x[j] (parent j on in that state) or (1-x[j]) (parent j off) terms - the standard multilinear extension of a Boolean function to the unit hypercube [1]. The resulting per-node expression strings are compiled with eval into a single vectorised function operating on the whole state array.

If a node’s expression is too large to compile (eval raising RecursionError), that node’s contribution is left as the constant string '0' and a message is logged.

Returns:

B1 – Function B1(x) -> ndarray mapping a state vector x (length self.n) to the per-node multilinear-interpolation values.

Return type:

callable

References

[1] Wittmann et al. (2009); see the references on BooleCubeODE.

abstractmethod write_c_code()

Not implemented.

Raises:

NotImplementedError –

class booldog.continuous.ode_factory.SquadODE(network, transform, gamma=1, h=10, **kwargs)

Bases: ODE

ODE system built via the SQUAD sigmoidal transform of a Boolean network’s activator/inhibitor structure.

Backs the 'squad' transform.

activations

n x n activator matrix (activations[i, j] == 1 iff node j activates node i); see booldog.boolean.boolean. BooleanNetworkMixin.primes_to_matrices.

Type:

arraylike

inhibitions

n x n inhibitor matrix (inhibitions[i, j] == 1 iff node j inhibits node i); see primes_to_matrices.

Type:

arraylike

param_gamma = 1

decay rate

Type:

arraylike

param_h = 10

sigmoidal gain

Type:

arraylike

param_dict

track parameters (same purpose as BooleCubeODE.param_dict; used e.g. by booldog.simulation_result.continuous_result.ContinuousSimulationResult.export).

Type:

dict

_A1

_a1

_B1

_b1

dxdt

the ODE system’s right-hand side, dx/dt = f(t, x)

Type:

function

_omega(x)

Equation (2) of Di Cara et al (2007) http://bmcbioinformatics.biomedcentral.com/articles/10.1186/1471-2105-8-462 Based on Andre Blejec R code.

_dxdt_transform(x, w)

Equation (2) of Di Cara et al (2007).

The numerator’s second exponent here uses (w - 0.5); the 2007 paper’s equation has just w (no shift). This matches the boundary-normalised variant used in later work building on SQUAD (e.g. Martinez-Sosa & Mendoza, 2013), which gives f(0)=0 and f(1)=1 exactly whilethe 2007 form does not (f(0) != 0, f(1) != 1 for finite h). Confirmed against a later SQUAD reimplementation in https://github.com/caramirezal/SQUADBookChapter

_get_system(off_nodes=None)

Build the dxdt(t, x_array, *args) right-hand-side function.

Parameters:

off_nodes (iterable of int, optional) – Node indices whose derivative should be forced to 0 (held constant).

Returns:

dxdt – Function dxdt(t, x_array, *args) -> ndarray computing _dxdt_transform(x, _omega(x)) element-wise, after clipping x_array to [0, 1]; suitable as the fun argument of scipy.integrate.solve_ivp.

Return type:

callable

booldog.continuous.ode_factory.ode_classes

transform to ODE class translation

Type:

dict

booldog.continuous.ode_factory.transforms

list of accepted ODE transforms

Type:

set