10. freeflux

10.1. Submodules

10.2. Attributes

__author__

__version__

10.3. Classes

Metabolite

Define Metabolite object which constitutes a Reaction.

Reaction

Define Reaction object which constitute a Model.

Model

Model class is the fundamental class of FreeFlux hosting operations for 13C MFA.

EMU

Define EMU (i.e., elementary metabolite unit) object and its operations.

MDV

Define MDV (i.e., mass isotopomer distribution vector) object and its operations.

10.4. Functions

apply_patch()

get_natural_MDV(n_atoms[, base_atom])

Calculate the MDV of an unlabeled fragment.

get_substrate_MDV(atom_nos, labeling_pattern, ...[, ...])

Calculate the MDV of a fragment from labeled substrate.

conv(mdv1, mdv2)

Perform convolution between two MDVs.

10.5. Package Contents

freeflux.__author__ = 'Chao Wu'[source]
freeflux.__version__ = '0.3.8'[source]
freeflux.apply_patch()[source]
class freeflux.Metabolite(id, atoms=None)[source]

Define Metabolite object which constitutes a Reaction.

Metabolites are considered identical when they have the same IDs and atoms.

Parameters:

  • id (str) – Metabolite ID.

  • atoms (str or list of str or None) – Carbons in metabolite, e.g., ‘abcd’ for metabolite without equivalents, and [‘abcd’, ‘dcba’] for metabolite with equivalents.

id

Metabolite ID.

Type:

str

atoms_info

equivalent => coefficient, e.g., {‘abcd’: 1.0} or {‘abcd’: 0.5, ‘dcba’: 0.5}.

Type:

dict

n_carbons

# of carbons in metabolite.

Type:

int

host_reactions

Reactions hosting the metabolite.

Type:

set of Reaction or None

id
atoms = None
host_reactions = None
__hash__()[source]
__eq__(other)[source]
Parameters:

other (Metabolite)

property atoms_info
property n_carbons
__repr__()[source]
class freeflux.Reaction(id, reversible=True)[source]

Define Reaction object which constitute a Model.

Duplicate substrates or products could appear in one reaction, but with different atoms.

Parameters:

  • id (str) – Reaction ID.

  • reversible (bool) – Reversibility.

id

Reaction ID.

Type:

str

reversible

Reversibility.

Type:

bool

substrates_info

Index are substrate IDs (there could be duplicate substrates), columns are Metabolite object and its stoichiometric number.

Type:

df

products_info

Index are product IDs (there could be duplicate products), columns are Metabolite object and stoichiometrc number.

Type:

df

substrates

Unique substrate IDs, in order of alphabet.

Type:

list

products

Unique product IDs, in order of alphabet.

Type:

list

substrates_with_atoms

Unique IDs of substrates with atoms, in order of alphabet.

Type:

list

products_with_atoms

Unique IDs of products with atoms, in order of alphabet.

Type:

list

_substrates_atom_mapping

For example, reactants like: A({‘ab’: 0.5, ‘ba’: 0.5}) + B({‘c’: 1}) will be transformed to [{‘a’: [A, 1, 0.5], ‘b’: [A, 2, 0.5], ‘c’: [C, 1, 1]},

{‘a’: [A, 2, 0.5], ‘b’: [A, 1, 0.5], ‘a’: [C, 1, 1]}]

Type:

list of dict or None

_products_atom_mapping

For example, reactants like: A({‘ab’: 0.5, ‘ba’: 0.5}) + B({‘c’: 1}) will be transformed to [{‘a’: [A, 1, 0.5], ‘b’: [A, 2, 0.5], ‘c’: [C, 1, 1]},

{‘a’: [A, 2, 0.5], ‘b’: [A, 1, 0.5], ‘a’: [C, 1, 1]}]

Type:

list of dict or None

flux(fflux and bflux for reversible reaction)

Reaction flux (forward flux and backward flux for reversible reaction).

Type:

Symbol

host_models

Model hosting the reaction.

Type:

set of Model or None

id
reversible = True
substrates_info
products_info
host_models = None
add_substrates(substrates, stoichiometry)[source]
Parameters:
add_products(products, stoichiometry)[source]
Parameters:

  • products (Metabolite or list of Metabolite.)

  • stoichiometry (float or list of float) – stoichiometric number(s) of corresponding product(s).

remove_substrates(substrates)[source]
Parameters:

substrates (Metabolite or list of Metabolite)

remove_products(products)[source]
Parameters:

products (Metabolite or list of Metabolite)

property substrates
property products
property substrates_with_atoms
property products_with_atoms
_atom_mapping(reactant)[source]
Parameters:

reactant (str,) – ‘substrate’ or ‘product’

Notes

Reactants like: A({‘ab’: 0.5, ‘ba’: 0.5}) + B({‘c’: 1}) will be transformed to [{‘a’: [A, 1, 0.5], ‘b’: [A, 2, 0.5], ‘c’: [C, 1, 1]},

{‘a’: [A, 2, 0.5], ‘b’: [A, 1, 0.5], ‘a’: [C, 1, 1]}].

property _substrates_atom_mapping
property _products_atom_mapping
_find_precursor_EMUs(emu, direction='forward')[source]
Parameters:

  • emu (EMU)

  • direction (str) –

    • For reversible reaction,

    ’forward’ if emu is product and precursor emu(s) are substrates; ‘backward’ if emu is substrate and precursor emu(s) are products. * For irreversible reaction, only ‘forward’ is acceptable.

Returns:

preEMUsInfo

Return type:

list

Notes

For reaction like: A({‘ab’: 0.5, ‘ba’: 0.5}) + B({‘c’: 1}) -> C({‘abc’: 0.5, ‘cba’: 0.5}), _find_precursor_EMUs(C12) returns [[[A_12], 0.5],

[[B_1, A_2], 0.25], [[B_1, A_1], 0.25]].

__repr__()[source]
class freeflux.Model(name='unnamed')[source]

Model class is the fundamental class of FreeFlux hosting operations for 13C MFA. A model can be built by adding reactions one by one or reading set of reactions from .tsv or .xlsx file.

Parameters:

name (str) – Model name.

name

Model name.

Type:

str

metabolites_info

Metabolite ID => list of Metabolites.

Type:

dict

reactions_info

Reaction ID => Reaction.

Type:

OrderedDict

metabolites

Metabolite IDs, in alphabetical order.

Type:

list

metabolites_with_atoms

IDs of metabolite with atom assignment, in alphabetical order.

Type:

list

end_substrates

Initial substrates of the model, in alphabetical order.

Type:

list

end_products

Final products of the model, in alphabetical order.

Type:

list

reactions

Reaction IDs, in order of addition.

Type:

list

n_metabolites

# of metabolites.

Type:

int

n_reactions

# of reactions.

Type:

int

_full_net_stoichiometric_matrix[source]

Complete stoichiometric matrix for net reaction with all metabolites in rows, net reactions in columns.

Type:

df

_full_total_stoichiometric_matrix[source]

Complete stoichiometric matrix for total reaction with all metabolites in rows, total reactions in columns.

Type:

df

metabolite_adjacency_matrix

Metabolite adjacency matrix (MAM). Metabolites with atoms are in index and columns (no duplicates). List of Reactions are in cells if reactions exists between (sub, pro), [] otherwise.

Type:

df

net_fluxes_bounds

Reaction ID => [lb, ub] by setting.

Type:

dict

net_fluxes_range

Reaction ID => estimeted [lb, ub]. All required net fluxes are included.

Type:

dict

netfluxids

Net flux IDs, alias of reactions.

Type:

list

concentrations

Concentrations, metabolite ID => float.

Type:

ser

concentrations_bounds

Metabolite ID => [lb, ub] by setting.

Type:

dict

concentrations_range

Metabolite ID => [lb, ub]. All required concentrations are included.

Type:

dict

concids

Concentration IDs (used only in computation process).

Type:

list

total_fluxes

Total fluxes, fluxe ID (e.g., ‘v1_f’ or ‘v2’) => float.

Type:

ser

totalfluxids

Total flux IDs.

Type:

list

target_EMUs

Target EMU IDs.

Type:

list

timepoints

Sorted time points for MDV simulation.

Type:

list

substrate_MDVs

Substrate EMU => MDV.

Type:

dict

substrate_MDVs_der_p

Substrate EMU => derivatives of substrate MDV w.r.t. variables in shape of (len(MDV), # of vars). # of vars = # of free fluxes for steady state MFA; # of vars = # of free fluxes + # of concentrations for INST MFA.

Type:

dict

initial_matrix_Xs

Size => initial MDVs of EMU in matrix X, i.e., the natural MDVs. The initial MDV matrix has the same shape of matrix X.

Type:

dict

initial_matrix_Ys

Size => initial MDVs of EMU in matrix Y, i.e., either natural MDVs or labeled MDVs. The initial MDV matrix has the same shape of matrix Y.

Type:

dict

initial_matrix_Xs_der_p, initial_matrix_Ys_der_p

Size => 3-D array in shape of (# of vars), X(Y).shape[0], X(Y).shape[1]) which is the initial MDV derivatives of EMUs in matrix X(Y) w.r.t. variables. # of vars = # of free fluxes + # of concentrations for INST MFA.

Type:

dict

initial_sim_MDVs

EMU ID => {t0 => MDV}. MDV of target EMUs at t0.

Type:

dict

EAMs

Size => EMU adjacency matrix (EAM). Cells are symbolic expression of flux.

Type:

dict of df

matrix_As, matrix_Bs

Size => [lambdified matrix A(B), [flux IDs], [EMUs]].

Type:

dict

matrix_As_der_p, matrix_Bs_der_p

Size => 3-D array in shape of (# of vars, A(B).shape[0], A(B).shape[1]) which is the derivatives of matrix A(B) w.r.t. variables. # of vars = # of free fluxes for steady state MFA; # of vars = # of free fluxes + # of concentrations for INST MFA.

Type:

dict

matrix_Ms

Size => [lambdified matrix M, [metabolite IDs]].

Type:

dict

matrix_Ms_der_p

Size => 3-D array in shape of (# of vars, M.shape[0], M.shape[1]), which is the derivatives of matrix M w.r.t. variables. # of vars = # of free fluxes for steady state MFA; # of vars = # of free fluxes + # of concentrations for INST MFA.

Type:

dict

label_atom

Labeled atom, i.e., the base atom in MDV, currently only supprts “H”, “C” and “N”.

Type:

str

labeling_strategy

Metabolite ID => [labeling_pattern(s), percentage(s), purity(s)].

Type:

dict

measured_MDVs

EMU ID (metabolite ID + ‘_’ + atom NOs) => [means of MDV, SDs of MDV].

Type:

dict

measured_MDVs_inv_cov

Inversed covariance matrix of measured MDVs with variances on the diagnol, other elements are zero.

Type:

array

measured_fluxes

Irreversible reaction ID => [mean, SD].

Type:

dict

measured_fluxes_inv_cov

Inversed covariance matrix of measured fluxes with variances on the diagnol, other elements are zero.

Type:

array

measured_fluxes_der_p

Derivative of measured fluxes w.r.t. variables in shape of (# of measured fluxes, # of vars), # of vars = # of free fluxes for steady state MFA; # of vars = # of free fluxes + # of concentrations for INST MFA.

Type:

array

measured_inst_MDVs

EMU ID (metabolite ID + ‘_’ + atom NOs) => {timepoint => [means of MDV, SDs of MDV]}.

Type:

dict

measured_inst_MDVs_inv_cov

Inversed covariance matrix of measured concatenated MDVs with variances on the diagnol, other elements are zero. Timepoints are concatenated except t0.

Type:

array

null_space

Null space of total stoichiometric matrix.

Type:

2-D array

transform_matrix

Transform matrix letting vnet = transform_matrix*v.

Type:

2-D array

name = 'unnamed'
reactions_info
target_EMUs = []
timepoints = []
substrate_MDVs
substrate_MDVs_der_p
EAMs
matrix_As
matrix_Bs
matrix_Ms
matrix_As_der_p
matrix_Bs_der_p
matrix_Ms_der_p
null_space = None
transform_matrix = None
initial_matrix_Xs
initial_matrix_Ys
initial_matrix_Xs_der_p
initial_matrix_Ys_der_p
initial_sim_MDVs
label_atom = None
labeling_strategy
measured_MDVs
measured_fluxes
measured_inst_MDVs
measured_MDVs_inv_cov = None
measured_inst_MDVs_inv_cov = None
measured_fluxes_inv_cov = None
measured_fluxes_der_p = None
unbalanced_metabolites
net_fluxes_bounds
net_fluxes_range
concentrations_bounds
concentrations_range
total_fluxes
concentrations
add_reactions(reactions)[source]
Parameters:

reactions (Reaction or list of Reaction)

remove_reactions(reactions)[source]
Parameters:

reactions (Reaction or list of Reaction)

read_from_file(file)[source]
Parameters:

file (file path) –

tsv or excel file with reactions with fields “reaction_ID”, “substrate_IDs(atom)”, “product_IDs(atom)” and “reversibility”.

Header line starts with “#”, and will be skiped.

property metabolites_info

returns: metabsInfo – metabolite ID => list of Metabolites :rtype: dict

property metabolites
property metabolites_with_atoms
property reactions
property n_metabolites
property n_reactions
_full_net_stoichiometric_matrix(metabolites, reactions)[source]

Re-estimate stoichiometric matrix if metabolites or reactions changes.

Parameters:

  • metabolites (tuple) – metabolite IDs

  • reactions (tuple) – reaction IDs

Returns:

netS – Complete stoichiometric matrix for net reaction with all metabolites in rows and net reactions in columns.

Return type:

df

_full_total_stoichiometric_matrix(metabolites, reactions)[source]

Re-estimate stoichiometric matrix if metabolites or reactions changes.

Parameters:

  • metabolites (tuple) – metabolite IDs

  • reactions (tuple) – reaction IDs

Returns:

totalS – Complete stoichiometric matrix for total reaction with all metabolites in rows and total reactions in columns.

Return type:

df

property end_substrates
property end_products
get_net_stoichiometric_matrix(exclude_metabs=None, include_ends=False)[source]
Parameters:

  • exclude_metabs (list or set) – Excluded metabolites.

  • include_ends (bool) – Whether to include end metabolites (i.e., initial substrates and final products).

  • Returns

  • netS (df) – Net stoichiometric matrix with balanced metabolites in rows and net reactions in columns

get_total_stoichiometric_matrix(exclude_metabs=None, include_ends=False)[source]
Parameters:

  • exclude_metabs (list or set) – Excluded metabolites.

  • include_ends (bool) – Whether to include end metabolites (initial substrates and final products).

  • Returns

  • totalS (df) – Total stoichiometric matrix with balanced metabolites in rows and total reactions in columns

property netfluxids
property totalfluxids
property concids
property metabolite_adjacency_matrix
returns: MAM – Metabolite adjacency matrix (MAM). Metabolites with atoms are in index and columns

(no duplicates). List of Reactions are in cells if reactions exists between sub (index) and pro (columns), [] otherwise

Return type:

df

__repr__()[source]
_BFS(iniEMU)[source]
Parameters:

iniEMU (EMU) – Starting EMU of the decomposition. Metabolite of iniEMU can be any Metabolite instance with the same id.

Returns:

EAMsInfo – Size => list of [EMU, [precursor EMUs], symbolic expression of flux].

Return type:

dict of list

_get_original_EAMs(iniEMU)[source]
Parameters:

iniEMU (EMU) – Starting EMU of the decomposition.

Returns:

EAMs – Size => original EMU adjacency matrix (EAM), cells are symbolic expression of flux。

Return type:

dict of df

_replace_list_item(iterable, toReplace, value)[source]
Parameters:

  • iterable (iterable) – Iterable can be nested.

  • toReplace (scalar) – Value to be replaced.

  • value (scalar) – Value that replaces toReplace.

Returns:

newLst – New tuple with toReplace recursively replaced.

Return type:

tuple

_uniquify_dataFrame_index(df)[source]
Parameters:

df (df) – DataFrame to be uniquify.

Returns:

uniqueDf – DataFrame with duplicate rows combined (summated).

Return type:

df

_lump_linear_EMUs(EAMs, iniEMU)[source]
Parameters:

  • EAMs (dict of df) – Size => original EMU adjacency matrix (EAM), cells are symbolic expression of flux.

  • iniEMU (EMU) – Starting EMU of the decomposition.

Returns:

lumpedEAMs – Size => lumped EMU adjacency matrix (EAM), cells are symbolic expression of flux.

Return type:

dict of df

_combine_equivalent_EMUs(EAMs)[source]
Parameters:

EAMs (dict of df) – Size => original EMU adjacency matrix (EAM), cells are symbolic expression of flux.

Returns:

combinedEAMs – Size => EAM with equivalent EMUs combined, cells are symbolic expression of flux.

Return type:

dict df

get_emu_adjacency_matrices(iniEMU, lump=True)[source]
Parameters:

  • iniEMU (EMU) – Starting EMU of the decomposition.

  • lump (bool) – Whether to lump linear EMUs.

Returns:

EAMs – Size => EMU adjacency matrix (EAM) after lumping of linear EMUs and combination of equivalent EMUs. Index and columns are EMUs, cells are symbolic expression of flux.

Return type:

dict of df

Notes

EMUs in sequential reactions can not be lumped in transient MFA.

_merge_EAMs(EAM1, EAM2)[source]
Parameters:

  • EAM1 (df) – EMU adjacency matrix (EAM) to merge

  • EAM2 (df) – EMU adjacency matrix (EAM) to merge

Returns:

mergedEAM – merged EAM

Return type:

df

_merge_all_EAMs(*EAMsAll)[source]
Parameters:

EAMsAll (tuple of EAMs) – EAMs is dict of DataFrame, i.e., Size => EMU adjacency matrix (EAM).

Returns:

mergedEAMs – Size => merged EAM

Return type:

dict of df

_decompose_network(metabolites, atom_nos, lump=True, n_jobs=1)[source]
Parameters:

  • metabolites (list of str) – List of metabolite IDs from which initial EMU will be generated to start the decomposition.

  • atom_nos (list of str) – Atom NOs of corresponding metabolites, len(atom_nos) should be equal to len(metabolites).

  • lump (bool) – Whether to lump linear EMUs.

  • n_jobs (int) – # of jobs to run in parallel.

Returns:

mergedEAMs – Size => merged EMU adjacency matrix (EAM).

Return type:

dict of df

Notes

EMUs in sequential reactions can not be lumped in transient MFA.

decompose_network(ini_emus, lump=True, n_jobs=1)[source]
Parameters:

  • ini_emus (dict) – Metabolite ID => atom NOs or list of atom NOs. Atom NOs can be int list or str, e.g., {‘Ala’: [[1,2,3], ‘23’], ‘Ser’: ‘123’}

  • lump (bool) – Whether to lump linear EMUs.

  • n_jobs (int) – # of jobs to run in parallel.

Returns:

mergedEAMs – Size => merged EMU adjacency matrix (EAM)

Return type:

dict of df

Notes

EMUs in sequential reactions can not be lumped in transient MFA.

optimizer()[source]
simulator(kind)[source]
Parameters:

kind ({"ss", "inst"}) –

  • If “ss”, simulation at isotopic steady state is performed.

  • If “inst”, simulation at isotopically nonstationary state is performed.

fitter(kind)[source]
Parameters:

kind ({"ss", "inst"}) –

  • If “ss”, fitting at isotopic steady state is performed.

  • If “inst”, fitting at isotopically nonstationary state is performed.

class freeflux.EMU(id, metabolite, atom_nos)[source]

Define EMU (i.e., elementary metabolite unit) object and its operations.

EMUs in the same metabolite and with the same atom NOs are considered as identical, while metabolites which they derived from could be different.

EMUs can be compared based self.metabolite_id and self.atom_nos. EMU and iterable object of EMUs can also be compared. In this case EMU will be put into the same iterable object with single item, and comparison between two iterables are performed.

Currently only binary equivalents are considered.

Parameters:

  • id (str) – EMU ID

  • metabolite (Metabolite or str) – Which metabolite the EMU comes from.

  • atom_nos (list of int or str) – Atom NOs, sorted by number.

id

EMU ID

Type:

str

metabolite

Which metabolite the EMU comes from.

Type:

Metabolite

metabolite_id

Metabolite ID.

Type:

str

atom_nos

Atom NOs, sorted by number.

Type:

list of int

size

Size of EMU.

Type:

int

equivalent_atom_nos

Equivalent atom NOs, sorted by number.

Type:

None or list of int

equivalent

Equivalent of EMU.

Type:

EMU

id
size
__hash__()[source]
__eq__(other)[source]
Parameters:

other (EMU or iterable)

__lt__(other)[source]
Parameters:

other (EMU or iterable)

__gt__(other)[source]
Parameters:

other (EMU or iterable)

property equivalent_atom_nos

returns: equivAtomNOs – Equivalent atom NOs, sorted by number. :rtype: list of int or None

property equivalent

returns: EMU – Equivalent of current EMU. :rtype: EMU

__repr__()[source]
class freeflux.MDV(fractions, nonnegative=True, normalize=True, base_atom='C')[source]

Define MDV (i.e., mass isotopomer distribution vector) object and its operations.

Convolution between mdv1 and mdv2 can be performed in three ways: 1. mdv1.conv(mdv2); 2. mdv1*mdv2; 3. mdv.conv(mdv1, mdv2).

The zero element for convolution is MDV([0]), and the identity element is MDV([1]).

Scalar multiplication (a*mdv) and MDV addition (mdv1 + mdv2) are also supported. In these cases, the resulting MDV are not automatically normalized.

In addition to C, MDV can be built based on H, N, O, Si, and S.

Parameters:

  • fractions (list or array) – MDV vector.

  • nonnegative (bool) – Whether to keep the elements >= 0.

  • normalize (bool) – Whether to normalize MDV vector to ensure the sum equals one.

  • base_atom (str) – Base atom for MDV.

value

MDV vector.

Type:

array

n_atoms

# of atom.

Type:

int

base_atom

Base atom for MDV.

Type:

str

fl(or fractional_labeling)

Fractional labeling.

Type:

float

value
base_atom = 'C'
__iter__()[source]
__getitem__(key)[source]
Parameters:

key (int or slice) – Index.

__array__()[source]
conv(mdv)[source]

Note. Assume that the mdv convolved has the same base atom.

Parameters:

mdv (list or array or MDV)

__mul__(other)[source]
Parameters:

other (scalar, list, array or MDV)

__rmul__(other)[source]
Parameters:

other (MDV)

__add__(other)[source]
Parameters:

other (MDV)

__radd__(other)[source]
Parameters:

other (MDV)

_correction_matrix(X, n_Xs)[source]
Parameters:

  • X (str) – Which element the correction matrix will be generated for.

  • n_Xs (int) – # of X atoms in metabolite or metabolite fragment, these atoms will be corrected.

correct_for_natural_abundance(atom_dict)[source]
Parameters:

atom_dict (dict) – element needs to be corrected => # of corresponding atoms in metabolite (fragment).

correct_for_inoculum(fraction)[source]
Parameters:

fraction (float in [0, 1]) – Fraction of inoculum in biomass measured.

property n_atoms
property fl
fractional_labeling
__repr__()[source]
freeflux.get_natural_MDV(n_atoms, base_atom='C')[source]

Calculate the MDV of an unlabeled fragment.

Parameters:

  • n_atoms (int) – # of atoms.

  • base_atom (str) – Base atom for MDV.

freeflux.get_substrate_MDV(atom_nos, labeling_pattern, percentage, purity, label_atom='C')[source]

Calculate the MDV of a fragment from labeled substrate. Currently this function only supports H, C or N-labeled substrate.

Parameters:

  • atom_nos (list of int) – Atom NOs, starting from 1.

  • labeling_pattern (str or list of str) –

    Labeling pattern of substrate, ‘0’ for unlabeled atom, ‘1’ for labeled atom, e.g., ‘100000’ for 1-13C glucose.

    List if tracer with multiple labeling patterns are used.

    Natural substrate (with all ‘0’s) don’t need to be explicitly set.

    If str, labeling_pattern should not be natural substrate.

  • percentage (float or list of float) –

    Molar percentage (in range of [0,1]) of corresponding tracer. Sum of percentage should be <= 1, and the rest will be considered as natural substrate.

    List if tracer with multiple labeling patterns are used.

    • If list, len(percentage) should be equal to len(labeling_pattern).

    • If float, labeling_pattern should not be natural substrate.

  • purity (float or list of float) –

    Labeled atom purity (in range of [0,1]) of corresponding tracer.

    List if tracer with multiple labeling patterns are used.

    • If list, len(purity) should be equal to len(labeling_pattern).

    • If float, labeling_pattern should not be natural substrate.

  • label_atom (str) – Labeled atom, i.e., base atom in the MDV. Currently supports only “H”, “C” and “N”.

freeflux.conv(mdv1, mdv2)[source]

Perform convolution between two MDVs.

Parameters:
Returns:

mdv

Return type:

MDV