Rescale

liftCouplingConstraints(model, BIG, printLevel, equalities)[source]

Reformulates badly-scaled coupling constraints C*v <=> d by lifting them to a better scaled problem in a higher dimension by introducing dummy variables.

Assumes C does not contain very small entries and transforms constraints containing very large entries (entries larger than BIG).

Reformulation techniques are described in detail in: Sun, Y., Fleming, R. M., Thiele, I., & Saunders, M. A. (2013). Robust flux balance analysis of multiscale biochemical reaction networks. BMC Bioinformatics, 14(1). https://doi.org/10.1186/1471-2105-14-240 See also tutorial here: https://opencobra.github.io/cobratoolbox/stable/tutorials/tutorial_numCharactWBM.html

USAGE:

model = liftCouplingConstraints (model, BIG, printLevel, equalities)

INPUTS:

model – COBRA model structure with coupling constraints, with fields used:

  • .S - m x n stoichiometric matrix (used only for a consistency check)

  • .rxns - n x 1 cell array of reaction identifiers

  • .C - k x n coupling constraint matrix, left hand side of C*v {<=,=,>=} d

  • .d - k x 1 right hand side of the coupling constraints

  • .dsense - k x 1 char array of coupling constraint senses in {L,E,G}

  • .ctrs - k x 1 cell array of coupling constraint IDs

  • .D - k x evars matrix coupling additional variables to the coupling constraints (if present)

  • .E - m x evars matrix of additional, non-metabolic variables (if present)

  • .evars - evars x 1 cell array of IDs of additional variables (if present)

  • .evarlb - evars x 1 lower bounds of additional variables (if present)

  • .evarub - evars x 1 upper bounds of additional variables (if present)

  • .evarc - evars x 1 objective coefficients of additional variables (if present)

  • .evarNames - evars x 1 cell array of names of additional variables (if present)

  • .modelID - identifier of the model, used to derive the lifted model ID

  • .subSystems - n x 1 subsystem assignment(s) for each reaction

OPTIONAL INPUTS:

  • BIG – value considered a large coefficient. BIG should be set between 1000 and 10000 on double precision machines (default = 1000)

  • printLevel – 1 or 0 enables/disables printing respectively (default = 1)

  • equalities – true means also deals with original constraints containing equalities (default false - only deals with original constraints that are inequalities)

OUTPUTS:

model – the input model with badly-scaled coupling constraints lifted, with fields:

  • .C - updated k’ x n coupling constraint matrix after lifting

  • .D - updated matrix coupling additional variables to the coupling constraints

  • .E - updated matrix of additional, non-metabolic variables

  • .d - updated right hand side of the coupling constraints

  • .dsense - updated senses of the coupling constraints

  • .ctrs - updated IDs of the coupling constraints

  • .evars - updated IDs of additional variables (original plus any created by lifting)

  • .evarlb - updated lower bounds of additional variables

  • .evarub - updated upper bounds of additional variables

  • .evarc - updated objective coefficients of additional variables

  • .evarNames - updated names of additional variables

  • .modelID - model identifier suffixed with _liftedCouplingConstraints

  • .C_old, .d_old, .ctrs_old, .dsense_old, .D_old, .E_old, .evarlb_old, .evarub_old, .evarc_old, .evars_old, .evarNames_old - working copies of the pre-lift constraint data, saved then removed before the function returns

  • .evarc_preLift, .evarlb_preLift, .evarub_preLift, .evarNames_preLift, .evars_preLift - additional variable data carried over from row-splitting, prior to variables created by lifting

liftModel(model, BIG, printLevel, fileName, directory)[source]

Lifts a COBRA model with badly-scaled stoichiometric and coupling constraints of the form: \(max c*v\) subject to: \(Sv = 0, x, Cv <= 0\) Converts it into a COBRA LPproblem structure, which can be used with solveCobraLP. Fluxes for the reactions should stay the same i.e. sol.full(1:nRxns) should yield an optimal flux vector.

USAGE:

LPproblem = liftModel (model, BIG, printLevel, fileName, directory)

INPUTS:

model – COBRA LPproblem Structure containing the original LP to be solved. The format of this struct is described in the documentation for solveCobraLP.m

OPTIONAL INPUTS:

  • BIG – A parameter the controls the largest entries that appear in the reformulated problem (default = 1000).

  • printLevel – printLevel = 1 enables printing of problem statistics (default); printLevel = 0 silent

  • fileName – name of th file to load

  • directory – file directory (if model is empty, you can load it using fileName and directory)

OUTPUTS:

LPproblem – COBRA Structure contain the reformulated LP to be solved.

liftRows(C, cupcon, BIG, logbig, printLevel, ctrs_cuprow, rxns)[source]

Helper for liftCouplingConstraints. Implements the lifting

USAGE:

[Clifted, newcon, ctrs_cuprow, ctrs_new, evars, ndum, cupcon, nEvars] = liftRows (C, cupcon, BIG, logbig, printLevel, ctrs_cuprow, rxns)

INPUTS:

  • C – k x n double, subset of coupling constraints (2-variable rows to be lifted)

  • cupcon – k x 1 char, senses for rows in C (L/G/E)

  • BIG – double, threshold for “large” coefficients; triggers lifting

  • logbig – double, log(BIG)

  • printLevel – double, 0 or 1; if 1 prints extra information

  • ctrs_cuprow – k x 1 cell array of char, IDs of the selected constraints, corresponds to rows in C

  • rxns – nRxns x 1 cell array of char, model reaction IDs

OUTPUTS:

  • Clifted – k’ x n’ double, lifted constraint matrix

  • newcon – ndum x 1 char, senses of added dummy constraints

  • ctrs_cuprow – k’ x 1 cell array of char, updated IDs for original coupling constraints

  • ctrs_new – ndum x 1 cell array of char, IDs for dummy constraints

  • evars – nEvars x 1 cell array of char, IDs of new dummy variables

  • ndum – double, total number of dummy constraint rows added

  • cupcon – k’ x 1 char, senses for rows in Clifted (L/G/E)

  • nEvars – double, total number of dummy variables

reformulate(LPproblem, BIG, printLevel)[source]

Reformulates badly-scaled FBA program Transforms LPproblems with badly-scaled stoichiometric and coupling constraints of the form: \(max c*x\) subject to: math:Ax <= b

Eliminates the need for scaling and hence prevents infeasibilities after unscaling. After using PREFBA to transform a badly-scaled FBA program, please turn off scaling and reduce the aggressiveness of presolve.

Rransforms a badly-scaled LPproblem contained in the struct FBA and returns the transformed program in the structure FBA. reformulate assumes S and C do not contain very small entries and transforms constraints containing very large entries (entries larger than BIG). BIG should be set between 1000 and 10000 on double precision machines. printLevel = 1 or 0 enables/diables printing respectively.

Reformulation techniques are described in detail in: Y. Sun, R. M.T. Fleming, M. A. Saunders, I. Thiele, An Algorithm for Flux Balance Analysis of Multi-scale Biochemical Networks, submitted.

USAGE:

[LPproblem] = reformulate (LPproblem, BIG, printLevel)

INPUTS:

  • LPproblem – Structure contain the original LP to be solved. The format of this struct is described in the documentation for solveCobraLP.m. Fields used:

    • .A - m x n linear constraint matrix

    • .b - m x 1 right hand side vector for A*x {L,E,G} b

    • .c - n x 1 linear objective coefficient vector

    • .lb - n x 1 lower bound vector

    • .ub - n x 1 upper bound vector

    • .csense - m x 1 character array of constraint senses

    • .modelID - (optional) identifier of the model

  • BIG – A parameter the controls the largest entries that appear in the reformulated problem.

  • printLevel – 1 enables printing of problem statistics; 0 = silent

OUTPUTS:

LPproblem – Structure contain the reformulated LP to be solved, with fields .A, .b, .c, .lb, .ub, .csense updated to the reformulated problem and .modelID prefixed with ‘L_’.

splitRow(A, ri, evars, evarlb, evarub, evarc, b, dsense, ctrs)[source]

Takes row ri of the constraint matrix A (e.g. -1e6*v1 -v2 + v3 < 0), identifies the coefficient with largest absolute value, and replaces the row by:

  1. a constraint containing only that largest coefficient and a new variable z (e.g. -1e6*v1 + z < 0)

  2. an equality constraint defining z as a combination of the remaining variables (e.g. z +v2 - v3 = 0)

USAGE:

[A, evars, evarlb, evarub, evarc, b, dsense, ctrs] = splitRow (A, ri, evars, evarlb, evarub, evarc, b, dsense, ctrs)

INPUTS:

  • A – k x n constraint matrix

  • ri – index of the row of A to split

  • evars – cell array of existing extra variable IDs

  • evarlb – lower bounds of extra variables

  • evarub – upper bounds of extra variables

  • evarc – objective coefficients of extra variables

  • b – right-hand side vector of constraints

  • dsense – constraint senses (L,E,G)

  • ctrs – cell array of constraint IDs

OUTPUTS:

  • A – updated constraint matrix with one extra column and one extra row

  • evars – updated extra variable IDs including the new z variable

  • evarlb – updated lower bounds (new z has -Inf)

  • evarub – updated upper bounds (new z has Inf)

  • evarc – updated objective coefficients (new z has 0)

  • b – updated RHS including 0 for the z-definition equality

  • dsense – updated senses including ‘E’ for the z-definition equality

  • ctrs – updated constraint IDs with a _splitN suffix for the new row