API Documentation

Core modules

Model

A model with thermodynamic properties

class thermo_flux.core.model.ThermoModel(model, pH: ~typing.Dict[str, ~pint.Quantity] = None, I: ~typing.Dict[str, ~pint.Quantity] = None, pMg: ~typing.Dict[str, ~pint.Quantity] = None, T: ~typing.Dict[str, ~pint.Quantity] = None, phi: ~typing.Dict[str, ~pint.Quantity] = None, gdiss_lim: ~pint.Quantity = None, dfG0_cov_sqrt=None, update_thermo_info=False, rmse_inf=<Quantity(100000.0, 'kilojoule / mole')>, cc=None, lc=None, m=None, max_drG=None, split_biomass=True, update_biomass_dfG0=False, add_charge_exchange=True, phi_dict: ~typing.Dict[str, ~pint.Quantity] = None, **kwargs)

Bases: Model

Thermodynamic model object.

takes cobra model and adds thermodynamic properties

property I
property T
add_TFBA_variables(m=None, conds=[''], error_type='covariance', qnorm=2, alpha=0.95, epsilon=0.5, nullspace=None, gdiss_constraint=False, sigmac_limit=12.3, split_v=False, big_M=False)
add_charge_exchange()

function to add charge transport and exchange reactions to the model. Skips compartment if there is already a proton transport reaction

add_proton_exchange()

function to add charge transport and exchange reactions to the model. Skips compartment if there is already a proton transport reaction

property cc
property charge_dict
property dfG0_cov_sqrt

Gets the square root of the covariance of the standard formation energies

property gdiss_lim
get_charge_transporters()

Get the charge transporters in the model

get_compounds(search=False, update_annotations=False, check_consisitency=True)
get_proton_transporters()

Get the proton transporters in the model

property lc
property m
property max_drG
property mg_dict
property pH
property pMg
property phi
property phi_dict
property proton_dict
regression(conds, flux_data, metabolite_data, volume_data, conc_fit=True, flux_fit=True, drG_fit=True, resnorm=1, qm_resnorm=2, error_type='covariance', conc_units=None, extracellular=None)
property rmse_inf
solution()

return a thermo optimization solution object for the model

split_biomass(biomass_rxn=None)

Automatically expand the biomass reaction to include transport of biomass out of the cell. This ensures the gibbs energy balance is maintained as biomass contains protons that have been transported into the cell, the energy of those protons leaving the cell must also be accounted for.

update_biomass_dfG0()

update the dfG0 of the biomass reaction based on the formula of biomass_c if no formula is defined it will be automatically calcualted from the biomass_c reaction

update_parameters()
update_thermo_info(fit_unknown_dfG0=False, search=False, round_dp=False, report=False)
thermo_flux.core.model.copy(self) → ThermoModel

Modified from COBRApy: Provide a partial ‘deepcopy’ of the Model.

All the Metabolite, Gene, and Reaction objects are created anew but in a faster fashion than deepcopy.

Returns

cobra.Model: new model copy

thermo_flux.core.model.custom_formatwarning(message, category, filename, lineno, line=None)

Reactions

A reaction with thermodynamic properties

class thermo_flux.core.reaction.ThermoReaction(reaction, model=None, drG0: float = 0, ignore_snd: bool = False)

Bases: Reaction

Thermodynamic metabolite object.

takes cobra reaction and adds thermodynamic properties

property balanced

Defines if a reaction has already been charge and proton balanced

check_atom_balance(round_dp=False, electrons=False, pMg=<Quantity(14, 'dimensionless')>)

Check the mass balance of a reaction

Uses the eQuilibrator compound atom bag to check the mass balance. If this is not available the COBRA model formula is used. Note magnesium balance is ignored by default.

Parameters

rxncobra.Reaction

Reaction to check

round_dpint

Number of decimal places to round to

electronsbool

Include electrons in the balance

pMgfloat

pMg of the reaction

Returns

net_elementsdict

a dict of {element: amount} for unbalanced elements.

This should be empty for balanced reactions.

property drG

Gibbs free energy of the reaction. drG0’ + RTlnC

property drG0

Standard Gibbs energy of a reaction before transformation.

property drG0prime

Transformed Gibbs energy of a reaction.

property drG_SE

standard error on the gibbs free energy estimate. Can be set explicitly or calcualted from the covariance

property drG_c_transport

Charge transport component of the transport component of the gibbs energy of a transporter reaction

property drG_h_transport

Proton transport component of the transport component of the gibbs energy of a transporter reaction

property drGmprime

Transformed Gibbs energy of a reaction.

property drGtransform

Gibbs energy to be added to the standard gibbs energy of a reaction to get the transformed gibbs free energy

property drGtransport

Transport componenent of gibbs energy of a transporter reaction.

property ignore_snd

Flag to ignore the second law constraint for a reaction

net_elements(balance_mg=False, round_dp=False, rxn_already_balanced=True)
split_reaction()

Split a multiple compartment reaction into subunits of 2 compartments or less

transported_c_h(round_dp=False)
property transported_charge

Free or additional charge transported in a transport reaction. Represents a generic positive ion

property transported_h

Free or additional protons transported in a transport reaction

property transported_mets

explicitly define metabolite transported in a reaction. This is useful for transporters that include chemical transformation during transport. Leave empty for automatic calculation of transported metabolites

Metabolites

A metabolite with thermodynamic properties

class thermo_flux.core.metabolite.ThermoMetabolite(metabolite, model=None, upper_bound: ~pint.Quantity = <Quantity(10, 'millimolar')>, lower_bound: ~pint.Quantity = <Quantity(0.1, 'micromolar')>, concentration: ~pint.Quantity = <Quantity(1, 'molar')>, accession: str = None, dfG0: ~pint.Quantity = None, dfG0prime: ~pint.Quantity = None, compound=None, dfG_SE: ~pint.Quantity = None, redox: bool = False, biomass: bool = False, unknown: bool = False, ignore_conc: bool = False)

Bases: Metabolite

Thermodynamic metabolite object.

takes cobra metabolite and adds thermodynamic properties

property accession
average_charge_protons(pH=None, pMg=None, ionic_strength=None, temperature=None, accuracy=0.1, round_dp=False, cobra_formula=False)
property biomass
check_consistency(ignore_H=True)

Check the consistency of a metabolite between the original model definiton and the metabolite identified in equilibrator database for thermodynamic analysis

property compound
property concentration
property dfG0
property dfG0prime
property dfG_SE
property dfGprime
property ignore_conc
property lower_bound
major_microspecies(pH=None, pMg=None, ionic_strength=None, temperature=None)
property redox
property unknown
property upper_bound

Solver modules : gurobi

thermo_flux.solver.gurobi.add_TFBA_variables(tmodel, m, conds=[''], error_type='linear', qnorm=1, alpha=0.95, epsilon=0.5, nullspace=None, gdiss_constraint=False, sigmac_limit=12.3, split_v=False, big_M=False)

Generates gurobi model from thermo model. Contains constraints for FBA optimization

thermo_flux.solver.gurobi.calc_conc_bounds(tmodel, conds, metabolite_data=None, extracellular_data=None, volume_data=None, extracellular='e', CI=2.6, conc_units=None)

Calcualte concentration bounds for individual metabolites based on data from whole cell metabolomics and extracellular measurements.

Parameters

tmodel: ThermoModel

Thermodynamic model

conds: list

List of conditions to calculate bounds for (must match data)

metabolite_data: pd.DataFrame

Dataframe of metabolite concentrations (mean and sd) for each condition

extracellular_data: pd.DataFrame

Dataframe of extracellular concentrations (lo and up) for each condition (to match legacy GAMS data)

volume_data: pd.DataFrame

Dataframe of volume fractions for each compartment for each condition

extracellular: str

Name of extracellular compartment (default = ‘e’)

CI: float

Zvalue for Confidence interval for data (default = 2.6 to match GAMS legacy ~99.9% CI)

conc_units: str

Units of concentration data (default = mM)

Returns

data_bounds_conc_df: pd.DataFrame

Dataframe of bounds for each metabolite for each condition

thermo_flux.solver.gurobi.compute_IIS(tmodel)
thermo_flux.solver.gurobi.drG_bounds(tmodel, concentration=True, drG_error=True, alpha=0.95, condition_index=0)

calculate the drg bounds for a given model

modified from equilibrator-api examples https://equilibrator.readthedocs.io/en/latest/equilibrator_examples.html

thermo_flux.solver.gurobi.gdiss_model(tmodel)

Print the individual gibbs energy balance for different components of drG. This can be used to identify why the Gibbs enery balance might not be met

thermo_flux.solver.gurobi.gdiss_var(tmodel, var, verbose=False)

Return the gibbs energy dissiaption of a specific variable

thermo_flux.solver.gurobi.get_solution(tmodel)
thermo_flux.solver.gurobi.model_start(tmodel, sol_file, ignore_vars=[], fix_vars=[], fix='start')

Set the model start point from a saved gurobi solution fix_vars: the variables that you want to import the starting points from fix: [‘start’, hint, bounds], Note that for some solutions numerical issue make an imported start point ifeasible. Therefore it is beneficial to only fix some start points and allow the remining unknwon variables to be calcualted

thermo_flux.solver.gurobi.multi_scenario_sol(tmodel, var)

Return the solution for a variable from a multiple scenario optimization

thermo_flux.solver.gurobi.read_bounds(bounds_file)

Read in bounds text file from hpc optimisation and returns a dataframe of the bounds. Parameters ———-

bounds_file: str

Path to bounds file with format variable_name: [lb, ub]

Returns

drG_bounds: pandas.DataFrame

DataFrame of bounds for each drG

thermo_flux.solver.gurobi.regression(tmodel, m, mvars, conds, flux_data, metabolite_data, volume_data, conc_fit=True, flux_fit=True, drG_fit=True, resnorm=1, qm_resnorm=2, error_type='covariance', conc_units=None, extracellular=None)

Add variables and constraints for regression to data.

Parameters

tmodel: ThermoModel

ThermoModel object to be used for regression

m: gurobipy.Model

gurobipy model object to add variables and constraints to

mvars: dict

dictionary of variables to be updated with new variables

conds: list

list of conditions to be used for regression

flux_data: pandas.DataFrame

dataframe of flux data to be regressed to

metabolite_data: pandas.DataFrame

dataframe of metabolite data to be regressed to

volume_data: pandas.DataFrame

dataframe of volume data to be used for total cell concentration constraints

conc_fit: bool

if True add constraints for metabolite concentration regression

flux_fit: bool

if True add constraints for flux regression

drG_fit: bool

if True add constraints for drG regression

resnorm: int

1 for linear residual formulation (sum of absolute differences), 2 for quadratic residual formulation (sum of squared differences)

error_type: str

‘covariance’ for covariance based error, ‘linear’ for linear error

conc_units: str

units of concentration data to be regressed to

Returns

m: gurobipy.Model

gurobipy model object with added variables and constraints

mvars: dict

dictionary of variables now updated with new variables

thermo_flux.solver.gurobi.regression_legacy(tmodel, m, mvars, conds, flux_data, metabolite_data, volume_data, conc_fit=True, flux_fit=True, drG_fit=True, resnorm=1, error_type='linear')

legacy function to set up regession optimization to replicated GAMS results included incorect assigning of cytosolic volume to entire cell

thermo_flux.solver.gurobi.total_cell_conc(tmodel, conds=[''], metabolites=[], volume_data=None, extracellular=None, GAMS_style=False)

add total cell concentrations constraints

thermo_flux.solver.gurobi.variability_analysis(tmodel, vars=[])

Set up a multiscenario optimisation problem to perform variability analysis on a given variable

Parameters

tmodel: ThermoModel

ThermoModel object to be used for variability analysis

vars: list

list of variables to perform variability analysis on

Returns

m: gurobipy.Model

gurobipy model object with added variables and constraints

thermo_flux.solver.gurobi.variability_results(tmodel)
thermo_flux.solver.gurobi.variable_scan(tmodel, scan_range, var)

Scan a variable over a range of values and return the solution for each value

Tools modules : drg_tools

thermo_flux.tools.drg_tools.add_transporter_charge_varaint(reaction, charge_state, round_dp=False)

Function to add a transporter variant with a specific net charge transport. Protons are added to either side of the equation to represent different charge states. Negative values are represented by protons with an opposite transport stoichiometry.

Parameters

reaction: tmodel.reaction

reaction to add variants of

charge_state: int

desired net charge to be transported (can represent different charge states of the transported metabolite)

round_dp: int

for charge and proton balaning if rounded values are used

Returns

ThermoReaction with a the desired net charge transport

thermo_flux.tools.drg_tools.add_transporter_varaints(reaction, add_charge_neutral=True, balance_charge=False, round_dp=False)

Function to add all transporter variants of a reaction. Variants are added for all species of transported metabolites with an abundance of >10% in the inner compartment. Additional transporters to represent a charge neutral transporter can also be added (including intermediate charge transport)

Parameters

reaction: tmodel.reaction

reaction to add transporter variants of

add_charge_neutral: bool

if True then a charge neutral variants of the transporter will be added

balance_charge: bool

if True then the reaction will be balanced for charge (if original reaction contains charge then this will be forced True)

round_dp: int

for charge and proton balaning if rounded values are used (should match original reaction rounding)

Returns

list of ThermoReaction objects representing the transporter variants

thermo_flux.tools.drg_tools.calc_average_charge_protons(compound, pH, pMg, ionic_strength, temperature, accuracy=0.1, round_dp=False, cobra_formula=False)

Modified from Elad Noor Function for calculating microspecies distribution of metabolites Microspcies below a certain theshold can be ignored by changing the accuracy. i.e accuracy = 0.1 only considers micorspecies >10% of population

thermo_flux.tools.drg_tools.calc_biomass_formula(biomass_rxn)

calculate biomass elemental compositon from biomass equation

thermo_flux.tools.drg_tools.calc_dfG0(tmodel, fit_unknown_dfG0=False)
thermo_flux.tools.drg_tools.calc_dfG0prime(tmodel, fit_unknown_dfG0=False)
thermo_flux.tools.drg_tools.calc_dfG_transform(met)
thermo_flux.tools.drg_tools.calc_drG0(S, dfG0)
thermo_flux.tools.drg_tools.calc_drGtransport(reaction, round_dp=False, rxn_already_balanced=True)
thermo_flux.tools.drg_tools.calc_model_drG0(tmodel)
thermo_flux.tools.drg_tools.calc_model_drG0prime(tmodel)
thermo_flux.tools.drg_tools.calc_phys_correction(tmodel)
thermo_flux.tools.drg_tools.calc_transported_mets(reaction)

calculates metabolites transported in a transport reaction

thermo_flux.tools.drg_tools.calculate_biomass_dfG0(biomass)

calculate the formation energy of biomass from the biomass formula

Parameters

biomass: cobra metabolite object

Returns

dfG0_bm: Quantity

formation energy of biomass units are defined as kJ/mol for compatibility with other reactions however, actual units for this value are J/gDW due to conversion in biomass eqation from mmol to gDW

thermo_flux.tools.drg_tools.charge_dict(tmodel)

identifies charge in the model so they can be added to reactions for balancing

thermo_flux.tools.drg_tools.comp_split(reaction, compartment)
thermo_flux.tools.drg_tools.custom_formatwarning(message, category, filename, lineno, line=None)
thermo_flux.tools.drg_tools.dfGbm(formula={}, units='kJ/mol', Mr_bio=None)

Calculates the formation energy of biomass or macromolecules based on their empirical formula modified from Saadat et. al Entropy 2020, 22(3), 277; https://doi.org/10.3390/e22030277 https://gitlab.com/qtb-hhu/thermodynamics-in-genome-scale-models/-/blob/master/EnergyOfFormationBiomass.py?ref_type=heads

Parameters

formuladict

Empirical formula of macromolecule.

unitsstr, optional

Units of the output. The default is ‘kJ/mol’.

Mr_bioQuantity, optional

Molecular weight of biomass in units carbon mol/gDW . The default is None and will be automatically calcualted from the elemental composition.

Returns

GfQuantity

Gibbs energy of formation in units of ‘units’

GcQuantity

Gibbs energy of combustion in units of ‘units’

yfloat

Degree of reduction

stoicharray

Stoichiometry of combustion reaction

thermo_flux.tools.drg_tools.formula_dict_to_string(formula)
thermo_flux.tools.drg_tools.generate_combinations(dictionary)
thermo_flux.tools.drg_tools.get_compound(met)

takes an identifier string, thermo metabolite or equilibrator compound and returns an equilibrator compound

thermo_flux.tools.drg_tools.get_suitable_ids(met, search=False, update_annotations=False)
thermo_flux.tools.drg_tools.leading_zeros(decimal)

Calculate the leading 0s in a decimal i.e 0.001 returns 2

thermo_flux.tools.drg_tools.major_microspecies(met, pH, pMg, ionic_strength_M, T_in_K, cobra_formula=False)

Calculates the major microspecies of a compound. Useful for transporter calculations

thermo_flux.tools.drg_tools.mg_dict(tmodel)

identifies magnesiums in the model so they can be added to reactions for balancing

thermo_flux.tools.drg_tools.net_elements(reaction, balance_mg=True, round_dp=False, rxn_already_balanced=True)

Calculates the net protons, charge, and mg of a reaction

thermo_flux.tools.drg_tools.new_eq_metabolite(met)

function to add a new metabolite to the local eq database if it does not already exist

thermo_flux.tools.drg_tools.new_reaction_name(reaction, charge_states)

Function to generate a new reaction name for a transporter variant with a specific charge state.

Parameters

reaction: tmodel.reaction

reaction to add variants of

charge_states: list of int

list of charge states of the transported metabolites

Returns

str: name of the new reaction

thermo_flux.tools.drg_tools.pka_graph(metabolite, pMg=None, ionic_strength=None, temperature=None, accuracy=0, round_dp=False)

returns a dataframe of the charge distribution of a metabolite at different pHs Parameters ———- metabolite: cobra metabolite object pMg: float or pint quantity ionic_strength: pint quantity

Returns

dataframe with pH as index and charge as columns

thermo_flux.tools.drg_tools.proton_dict(tmodel)

identifies protons in the model so they can be added to reactions for balancing

thermo_flux.tools.drg_tools.reaction_balance(reaction, balance_charge=True, balance_mg=True, round_dp=False, rxn_already_balanced=False)

Docstring for reaction_balance

Parameters:

  • reaction – Description

  • balance_charge – Description

  • balance_mg – Description

  • round_dp – Description

  • rxn_already_balanced – Description

Returns:

Description

Return type:

Any

thermo_flux.tools.drg_tools.round_and_normalize(numbers, round_dp=2)
thermo_flux.tools.drg_tools.transported_c_h(reaction, round_dp=False, verbose=False, rxn_already_balanced=True)