Thermokernel

• Thermoqp

extractSemiSteadyStateModel(model, rxnWeights, metWeights, param)

Extract a semi-steady-state thermodynamically consistent submodel by keeping only the metabolites with a non-zero, non-NaN weight, then calling thermoKernel

USAGE:

[thermoModel, thermoModelMetBool, thermoModelRxnBool] = extractSemiSteadyStateModel (model, rxnWeights, metWeights, param)

INPUTS:

• model – COBRA model with fields:

  • .S - m x n stoichiometric matrix

  • .b - m x 1 accumulation (right hand side of S*v = b)

  • .csense - m x 1 constraint sense for each metabolite

  • .mets - m x 1 metabolite identifiers

  • .SConsistentMetBool - m x 1 boolean, stoichiometrically consistent metabolites

  • .fluxConsistentMetBool - m x 1 boolean, flux consistent metabolites

• rxnWeights – n x 1 real-valued penalties on reactions (negative promotes active, positive promotes inactive)

• metWeights – m x 1 real-valued penalties on metabolites (negative promotes present, positive promotes absent); metabolites with a zero or NaN weight are dropped

OPTIONAL INPUT:

param – a structure of parameters passed through to thermoKernel

OUTPUTS:

• thermoModel – the extracted semi-steady-state COBRA submodel

• thermoModelMetBool – m x 1 boolean, true for metabolites retained in thermoModel

• thermoModelRxnBool – n x 1 boolean, true for reactions retained in thermoModel

plotThermoKernelExtractStats(model, activeInactiveRxn, rxnWeights, presentAbsentMet, metWeights, thermoModelMetBool, thermoModelRxnBool)

Plot statistics comparing reaction and metabolite weights against the thermodynamic submodel extracted by thermoKernel

USAGE:

plotThermoModelExtractStats (model, activeInactiveRxn, rxnWeights, presentAbsentMet, metWeights, thermoModelMetBool, thermoModelRxnBool)

INPUTS:

• model – COBRA model with field:

  • .h0 - metabolite weights used by thermoKernel

• activeInactiveRxn – n x 1 with entries {1, -1, 0} for reactions that must be active, inactive, or unspecified

• rxnWeights – n x 1 real-valued penalties on reactions

• presentAbsentMet – m x 1 with entries {1, -1, 0} for metabolites that must be present, absent, or unspecified

• metWeights – m x 1 real-valued penalties on metabolites

• thermoModelMetBool – m x 1 boolean, true for metabolites retained in the extracted model

• thermoModelRxnBool – n x 1 boolean, true for reactions retained in the extracted model

plotThermoKernelStats(activeInactiveRxn, rxnWeights, thermoModelRxnBool, presentAbsentMet, metWeights, thermoModelMetBool)

Plot confusion matrices for active/inactive reactions and present/absent metabolites

USAGE:

plotThermoKernelStats (activeInactiveRxn, rxnWeights, thermoModelRxnBool, presentAbsentMet, metWeights, thermoModelMetBool)

INPUTS:

• activeInactiveRxn – n x 1 with entries {1, -1, 0} for reactions that must be active, inactive, or unspecified

• rxnWeights – n x 1 real-valued penalties on reaction flux (negative promotes active, positive promotes inactive)

• thermoModelRxnBool – n x 1 boolean vector of thermodynamically consistent reactions in the input model

• presentAbsentMet – m x 1 with entries {1, -1, 0} for metabolites that must be present, absent, or unspecified

• metWeights – m x 1 real-valued penalties on metabolite activity (negative promotes present, positive promotes absent)

• thermoModelMetBool – m x 1 boolean vector of thermodynamically consistent metabolites in the input model

plotThermoKernelWeights(metWeights, rxnWeights, thermoModelMetBool, thermoModelRxnBool)

plots weights on metabolites and reactions used by thermokernel -ve weight = incentive

0 weight =

+ve weight = disincentive

If thermoModelMetBool and thermoModelRxnBool are also provided, it also plots the weigths for the incentivised metabolites and reactions that were omitted from the output model

USAGE:

plotThermoKernelWeights (metWeights, rxnWeights, thermoModelMetBool, thermoModelRxnBool)

INPUTS:

• metWeights – m x 1 real-valued vector of weights on metabolites

• rxnWeights – n x 1 real-valued vector of weights on reactions

OPTIONAL INPUTS:

• thermoModelMetBool – m x 1 boolean vector of thermodynamically consistent metabolites in the input model

• thermoModelRxnBool – n x 1 boolean vector of thermodynamically consistent reactions in the input model

Ronan Fleming

thermoKernel(model, activeInactiveRxn, rxnWeights, presentAbsentMet, metWeights, param)

From a cobra model, extract a thermodynamically flux consistent submodel (thermoModel), of minimal size, optionally given: a set of active and inactive reactions (activeInactiveRxn), a set of penalties on activity/inactivity of reactions (rxnWeights), a set of present and absent metabolites (presentAbsentMet), and a set of penalties on presence/absence of metabolites (metWeights).

USAGE:

[thermoModel, thermoModelMetBool, thermoModelRxnBool] = thermoKernel (model, activeInactiveRxn, rxnWeights, presentAbsentMet, metWeights, param)

INPUT:

model – (the following fields are required - others can be supplied)

• .S - m x n Stoichiometric matrix

• .c - n x 1 Linear objective coefficients

• .lb - n x 1 Lower bounds

• .ub - n x 1 Upper bounds

OPTIONAL INPUTS:

• model – (optional fields) * .b - m x 1 change in concentration with time * .csense - m x 1 character array with entries in {L,E,G} * .osenseStr: Maximize (‘max’)/minimize (‘min’) (opt, default = ‘max’) linear part of the objective. * .C - k x n Left hand side of C*v <= d * .d - k x n Right hand side of C*v <= d * .dsense - k x 1 character array with entries in {L,E,G} * .beta - A scalar weight on minimisation of one-norm of internal fluxes. Default 1e-4.

  Larger values increase the incentive to find a flux vector to be thermodynamically feasibile in each iteration of optCardThermo and decrease the incentive to search the steady state solution space for a flux vector that results in certain reactions and metabolites to be active and present, respectively.

  • .mets - m x 1 metabolite identifiers

  • .rxns - n x 1 reaction identifiers

  • .SIntMetBool - m x 1 boolean, true for internal metabolites

  • .SIntRxnBool - n x 1 boolean, true for internal reactions

  • .SConsistentMetBool - m x 1 boolean, stoichiometrically consistent metabolites

  • .SConsistentRxnBool - n x 1 boolean, stoichiometrically consistent reactions

  • .fluxConsistentMetBool - m x 1 boolean, flux consistent metabolites

  • .fluxConsistentRxnBool - n x 1 boolean, flux consistent reactions

  • .metRemoveBool - m x 1 boolean, metabolites removed during extraction

  • .rxnRemoveBool - n x 1 boolean, reactions removed during extraction

  • .forcedIntRxnBool - n x 1 boolean, internal reactions forced to carry non-zero flux

  • .g0 - n x 1 reaction weights used internally (derived from rxnWeights)

  • .h0 - m x 1 metabolite weights used internally (derived from metWeights)

  • .lambda0 - internal cardinality-optimisation weight parameter

  • .lambda1 - internal cardinality-optimisation weight parameter

  • .delta0 - internal cardinality-optimisation weight parameter

  • .delta1 - internal cardinality-optimisation weight parameter

  • .alpha1 - internal cardinality-optimisation weight parameter

  • .activeRxn - n x 1 boolean, reactions required to be active

  • .inactiveRxn - n x 1 boolean, reactions required to be inactive

  • .presentMet - m x 1 boolean, metabolites required to be present

  • .absentMet - m x 1 boolean, metabolites required to be absent

• activeInactiveRxn – n x 1 with entries {1, -1, 0} depending on whether a reaction must be active, inactive, or unspecified respectively.

• rxnWeights –

  • n x 1 real valued penalties on zero norm of reaction flux, negative to promote a reaction to be active, positive

  to promote a reaction to be inactive and zero to be indifferent to activity or inactivity

• presentAbsentMet – m x 1 with entries {1, -1, 0} depending on whether a metabolite must be present, absent, or unspecified respectively.

• metWeights –

  • m x 1 real valued penalties on zero norm of metabolite “activity”, negative to promote a metabolite to be present, positive

  to promote a metabolite to be absent and zero to be indifferent to presence or absence

• param – Parameters structure: * .printLevel - greater than zero to recieve more output * .bigNum - definition of a large positive number (Default value = 1e6) * .nbMaxIteration - maximal number of outer iterations (Default value = 30) * .epsilon - smallest non-zero flux - (Default value = feasTol = 1e-6) * .theta - parameter of the approximation (Default value = 2)

  For a sufficiently large parameter , the Capped-L1 approximate problem and the original cardinality optimisation problem are have the same set of optimal solutions

  • .normalizeZeroNormWeights - {(0),1}, normalises zero norm weights

    rxnWeights = rxnWeights./sum(abs(rxnWeights)); metWeights = metWeights./sum(abs(metWeights));

  • .rxnWeightsConsistentWithMetWeights {(0),1} If true and metWeights are provided, make the corresponding reaction weights consistent

  • .metWeightsConsistentWithRxnWeights {(0),1} If true and rxnWeights are provided, make the corresponding metabolite weights consistent

  • .acceptRepairedFlux {(1),0} If true, a post processing step after each inner iteration minimises the absolute value of internal reaction flux,

    while (a) all exchange fluxes are kept constant, and (b) no internal flux is allowed to change direction or increase in size.

  • .relaxBounds {(0),1} If true, allow internal bounds forcing non-zero flux to be relaxed as minimising absolute value of internal

    fluxes is only guarunteed to return a thermodynamically feasible flux if such bounds can be relaxed.

  • .removeOrphanGenes - {(1),0}, removes orphan genes from thermoModel

  • .formulation - mathematical formulation of thermoKernel algorithm (Default is ‘pqzwrs’. Do not change unless expert user.)

  • .plotThermoKernelStats {(0),1} generates a figure with confusion matrices comparing anticipated vs actual metabolites and reactions in the extracted model

  • .plotThermoKernelWeights {(0),1} generates a figure displaying the weights given to actual and anticipated but omitted metabolites and reactions in the extracted model

  • .iterationMethod - method used to iterate reaction/metabolite selection (Default: ‘greedyAdd’)

  • .saveModelSFC - {(0),1} save the model at each stoichiometric/flux-consistency step

  • .nMax - maximal number of inner iterations (Default value = 40)

  • .findThermoConsistentFluxSubset - {(0),1} find the largest thermodynamically flux consistent subset before extraction