3.2. kda.calculations

3.2.1. State Probability & Flux Calculations

The calculations module contains code to calculate steady-state probabilities and fluxes from a user-defined kinetic diagram.

calc_state_probs(G, key='name', output_strings=True, dir_edges=None)

Generates the state probability expressions using the diagram method developed by King and Altman [1] and Hill [2].

Parameters:

• G (NetworkX.MultiDiGraph) – A kinetic diagram

• key (str, optional) – Attribute key used to retrieve edge data from G.edges. The default NetworkX edge key is "weight", however the kda edge keys are "name" (for rate constant names, e.g. "k12") and "val" (for the rate constant values, e.g. 100). Default is "name".

• output_strings (bool, optional) – Used to denote whether values or strings will be combined. Default is False, which tells the function to calculate the state probabilities using numbers. If True, this will assume the input 'key' will return strings of variable names to join into the analytic state multplicity and normalization function.

• dir_edges (ndarray, optional) – Array of all directional diagram edges (made from 2-tuples) for the input diagram G. Created using generate_directional_diagrams() with return_edges=True.

Returns:

state_probs – Array of state probabilities for N states of the form [p1, p2, p3, ..., pN] (output_strings=False), or a list of symbolic state probability expressions in the same order (output_strings=True).

Return type:

ndarray or list of SymPy expressions

Notes

The algebraic expressions for the state probabilities (at steady-state) are created directly from the directional diagrams. Subsets of the directional diagrams are summed based on a common target state. For some state \(i\) the sum of directional diagrams (i.e., rate-products) with target state \(i\) yields the unnormalized state probability expression [3],

\[\Omega_{i} = \sum \text{directional diagrams for state } i.\]

The state probabilities are

\[p_{i} = \frac{\Omega_{i}}{\Sigma},\]

where \(\Sigma\) is the sum of all directional diagrams (i.e. all \(\Omega_i\) s) for the kinetic diagram.

calc_cycle_flux(G, cycle, order, key='name', output_strings=True, dir_edges=None, net=True)

Generates the expression for the one-way or net cycle flux for a cycle in the kinetic diagram G.

Parameters:

• G (NetworkX.MultiDiGraph) – A kinetic diagram

• cycle (list of int) – List of node indices for cycle of interest, index zero. Order of node indices does not matter.

• order (list of int) – List of integers of length 2 (e.g. [0, 1]), where the integers are nodes in cycle. The pair of nodes should be ordered such that a counter-clockwise path is followed.

• key (str, optional) – Attribute key used to retrieve edge data from G.edges. The default NetworkX edge key is "weight", however the kda edge keys are "name" (for rate constant names, e.g. "k12") and "val" (for the rate constant values, e.g. 100). Default is "name".

• output_strings (bool, optional) – Used to denote whether values or strings will be combined. Default is False, which tells the function to calculate the cycle flux using numbers. If True, this will assume the input 'key' will return strings of variable names to join into the analytic cycle flux function.

• dir_edges (ndarray, optional) – Array of all directional diagram edges (made from 2-tuples) for the input diagram G. Given as an option for performance reasons (when calculating net cycle fluxes for multiple cycles it is best to generate the directional diagram edges up front and provide them). Created using generate_directional_diagrams() with return_edges=True.

• net (bool, optional) – Used to determine whether to return the one-way or net cycle flux. Default is True (i.e., to generate the net cycle flux).

Returns:

cycle_flux – The one-way or net cycle flux for the input cycle.

Return type:

float or SymPy expression

Notes

The net cycle flux for some cycle \(k\) is [3],

\[J_{k} = \frac{(\Pi_{+} - \Pi_{-}) \Sigma_{k}}{\Sigma},\]

where \((\Pi_{+} - \Pi_{-}) \Sigma_{k}\) is the sum of all flux diagrams for cycle \(k\) and \(\Sigma\) is the sum of all directional diagrams for the kinetic diagram. \(\Pi_{+}\) and \(\Pi_{-}\) are the forward and reverse rate-products along cycle \(k\) where the forward (i.e. positive) direction is counter-clockwise (CCW).

calc_sigma(G, dir_edges=None, key='name', output_strings=True, **kwargs)

Generates the normalization factor expression for state probabilities and cycle fluxes, which is the sum of directional diagrams for the kinetic diagram G [3].

Parameters:

• G (NetworkX.MultiDiGraph) – A kinetic diagram

• dir_edges (ndarray, optional) – Array of all directional diagram edges (made from 2-tuples) for the input diagram G. Created using generate_directional_diagrams() with return_edges=True.

• key (str, optional) – Attribute key used to retrieve edge data from G.edges. The default NetworkX edge key is "weight", however the kda edge keys are "name" (for rate constant names, e.g. "k12") and "val" (for the rate constant values, e.g. 100). Default is "name".

• output_strings (bool, optional) – Used to denote whether values or strings will be combined. Default is False, which tells the function to calculate the normalization factor using numbers. If True, this will assume the input 'key' will return strings of variable names to join into the analytic cycle flux function.

• kwargs (dict, optional) – Additional keyword arguments. Note that the alias dirpar_edges is deprecated; please use dir_edges.

Returns:

sigma – Sum of rate products of all directional diagrams for the input diagram G as a float (output_strings=False) or a string (output_strings=True).

Return type:

float or str

Warns:

DeprecationWarning – The dirpar_edges parameter is deprecated and will be removed in a future release. Please use dir_edges instead.

Raises:

TypeError – If the required argument dir_edges is not provided (including when the deprecated dirpar_edges parameter is not supplied).

Notes

The expression generated here is important for normalizing both state probabilities and net cycle fluxes. State probabilities are defined [3],

\[p_i = \Omega_{i} / \Sigma,\]

where \(\Omega_{i}\) is the state multiplicity for state \(i\) (the sum of directional diagrams for state \(i\)) and \(\Sigma\) is the sum of all directional diagrams.

Additionally \(\Sigma\) is used when calculating the net cycle flux for some cycle \(k\) [3],

\[J_{k} = \frac{(\Pi_{+} - \Pi_{-}) \Sigma_{k}}{\Sigma},\]

where \((\Pi_{+} - \Pi_{-}) \Sigma_{k}\) is the sum of all flux diagrams for cycle \(k\) and \(\Sigma\) is the sum of all directional diagrams for the kinetic diagram.

calc_sigma_K(G, cycle, flux_diags, key='name', output_strings=True)

Generates the expression for the path-based componenet of the sum of flux diagrams for some cycle in kinetic diagram G. The sum of flux diagrams is used in calculating net cycle fluxes [3].

Parameters:

• G (NetworkX.MultiDiGraph) – A kinetic diagram

• cycle (list of int) – List of node indices for cycle of interest, index zero. Order of node indices does not matter but should not contain all nodes.

• flux_diags (list) – List of relevant directional flux diagrams for input cycle.

• key (str, optional) – Attribute key used to retrieve edge data from G.edges. The default NetworkX edge key is "weight", however the kda edge keys are "name" (for rate constant names, e.g. "k12") and "val" (for the rate constant values, e.g. 100). Default is "name". Default is "name".

• output_strings (bool, optional) – Used to denote whether values or strings will be combined. Default is False, which tells the function to calculate the sum of all directional flux diagrams using numbers. If True, this will assume the input 'key' will return strings of variable names to join into the analytic function.

Returns:

sigma_K – Sum of rate products of directional flux diagram edges pointing to input cycle as a float (output_strings=False) or as a string (output_strings=True).

Return type:

float or str

Notes

The expression generated here is important for generating the net cycle flux expressions. The net cycle flux for some cycle \(k\) is [3],

\[J_{k} = \frac{(\Pi_{+} - \Pi_{-}) \Sigma_{k}}{\Sigma},\]

where \((\Pi_{+} - \Pi_{-}) \Sigma_{k}\) is the sum of all flux diagrams for cycle \(k\) and \(\Sigma\) is the sum of all directional diagrams for the kinetic diagram. \(\Sigma_{k}\) is the path-based component of the flux diagram sum. For cycles with no flux diagrams, \(\Sigma_{k} = 1\).

calc_pi_difference(G, cycle, order, key='name', output_strings=True, net=True)

Generates the expression for the cycle-based componenet of the sum of flux diagrams for some cycle in kinetic diagram G. The sum of flux diagrams is used in calculating net cycle fluxes [3].

Parameters:

• G (NetworkX.MultiDiGraph) – A kinetic diagram

• cycle (list of int) – List of node indices for cycle of interest, index zero. Order of node indices does not matter unless your cycle contains all nodes.

• order (list of int) – List of integers of length 2 (e.g. [0, 1]), where the integers are nodes in cycle. The pair of nodes should be ordered such that a counter-clockwise path is followed.

• key (str, optional) – Attribute key used to retrieve edge data from G.edges. The default NetworkX edge key is "weight", however the kda edge keys are "name" (for rate constant names, e.g. "k12") and "val" (for the rate constant values, e.g. 100). Default is "name".

• output_strings (bool, optional) – Used to denote whether values or strings will be combined. Default is False, which tells the function to calculate the difference using numbers. If True, this will assume the input 'key' will return strings of variable names to join into the analytic function.

• net (bool, optional) – Used to determine whether to return the forward cycle product (i.e., net=False) or the difference of the forward and reverse cycle products (i.e., net=True). Default is True.

Returns:

pi_difference – Difference of the counter-clockwise and clockwise cycle rate-products as a float (output_strings=False) or a string (output_strings=True).

Return type:

float or str

Notes

The expression generated here is important for generating the net cycle flux expressions. The net cycle flux for some cycle \(k\) is [3],

\[J_{k} = \frac{(\Pi_{+} - \Pi_{-}) \Sigma_{k}}{\Sigma},\]

where \((\Pi_{+} - \Pi_{-}) \Sigma_{k}\) is the sum of all flux diagrams for cycle \(k\) and \(\Sigma\) is the sum of all directional diagrams for the kinetic diagram. \(\Pi_{+} - \Pi_{-}\) is the cycle-based component of the flux diagram sum, where \(\Pi_{+}\) and \(\Pi_{-}\) are the forward and reverse rate-products along cycle \(k\) and the forward (i.e. positive) direction is counter-clockwise (CCW).

calc_thermo_force(G, cycle, order, key='name', output_strings=True)

Generates the expression for the thermodynamic driving force for some cycle in the kinetic diagram G.

Parameters:

• G (NetworkX.MultiDiGraph) – A kinetic diagram

• cycle (list of int) – List of node indices for cycle of interest, index zero. Order of node indices does not matter unless your cycle contains all nodes.

• order (list of int) – List of integers of length 2 (e.g. [0, 1]), where the integers are nodes in cycle. The pair of nodes should be ordered such that a counter-clockwise path is followed.

• key (str, optional) – Attribute key used to retrieve edge data from G.edges. The default NetworkX edge key is "weight", however the kda edge keys are "name" (for rate constant names, e.g. "k12") and "val" (for the rate constant values, e.g. 100). Default is "name". Default is "name".

• output_strings (bool, optional) – Used to denote whether values or strings will be combined. Default is False, which tells the function to calculate the thermodynamic force using numbers. If True, this will assume the input 'key' will return strings of variable names to join into the analytic function.

Returns:

thermo_force – The thermodynamic force for the input cycle returned as a float (output_strings=False) or a SymPy expression (output_strings=True). The returned value is unitless and should be multiplied by kT to calculate the actual thermodynamic force.

Return type:

float or SymPy expression

Notes

The expression generated here is used to calculate the thermodynamic driving force. The thermodynamic driving force for some cycle \(k\) is [3],

\[\chi_{k} = kT \ln \left( \frac{\Pi_{+}}{\Pi_{-}} \right),\]

where \(\Pi_{+}\) and \(\Pi_{-}\) are the forward and reverse rate-products along cycle \(k\) and the forward (i.e. positive) direction is counter-clockwise (CCW). The returned expression does not include \(kT\). At equilibrium the thermodynamic driving force for any cycle is zero (i.e. \(\chi_{k} = 0\)).

References

[1] (1,2,3)

Edward L. King and Carl Altman. A Schematic Method of Deriving the Rate Laws for Enzyme-Catalyzed Reactions. The Journal of Physical Chemistry, 60(10):1375–1378, October 1956. doi:10.1021/j150544a010.

[2] (1,2,3)

Terrell L. Hill. Studies in irreversible thermodynamics IV. Diagrammatic representation of steady state fluxes for unimolecular systems. Journal of Theoretical Biology, 10(3):442–459, April 1966. doi:10.1016/0022-5193(66)90137-8.

[3] (1,2,3,4,5,6,7,8,9,10,11)

Terrell L. Hill. Free Energy Transduction and Biochemical Cycle Kinetics. Springer-Verlag, New York, 1989. ISBN 978-0-387-96836-0. doi:10.1007/978-1-4612-3558-3.

Functions

calc_cycle_flux(G, cycle, order[, key, ...])	Generates the expression for the one-way or net cycle flux for a cycle in the kinetic diagram G.
calc_net_cycle_flux(G, cycle, order[, key, ...])	Generates the expression for the net cycle flux for some cycle in kinetic diagram G.
calc_net_cycle_flux_from_diags(G, cycle, order)	Generates the expression for the net cycle flux for some cycle in kinetic diagram G.
calc_pi_difference(G, cycle, order[, key, ...])	Generates the expression for the cycle-based componenet of the sum of flux diagrams for some cycle in kinetic diagram G.
calc_sigma(G[, dir_edges, key, output_strings])	Generates the normalization factor expression for state probabilities and cycle fluxes, which is the sum of directional diagrams for the kinetic diagram G [3].
calc_sigma_K(G, cycle, flux_diags[, key, ...])	Generates the expression for the path-based componenet of the sum of flux diagrams for some cycle in kinetic diagram G.
calc_state_probs(G[, key, output_strings, ...])	Generates the state probability expressions using the diagram method developed by King and Altman [1] and Hill [2].
calc_state_probs_from_diags(G[, dir_edges, ...])	Generates the state probability expressions using the diagram method developed by King and Altman [1] and Hill [2].
calc_thermo_force(G, cycle, order[, key, ...])	Generates the expression for the thermodynamic driving force for some cycle in the kinetic diagram G.