Fr

bilinearDecomposition(S)

Converts a stoichiometric matrix into a bilinear form.

USAGE:

[A, B, C] = bilinearDecomposition (S)

INPUT:

S – m x n stoichiometric matrix

OUTPUTS:

• A – m x (m + k) matrix selecting rows such that \(S = A B C\)

• B – (m + k) x (n + k) bilinear stoichiometric matrix

• C – (n + k) x n matrix adding columns to form net reaction stoichiometry such that \(S = A B C\)

An example “bilinearisation” of the reaction

\[\begin{split}~&~ A + B + C \leftrightarrow D + E\\\end{split}\]

is

\[\begin{split}~&~ A + B \leftrightarrow P \\ ~&~ P + C \leftrightarrow Q \\ ~&~ Q \leftrightarrow D + E\end{split}\]

where P and Q are faux molecular species.

checkFullRowRankFRK

Check the row rank of the [F, R] half-stoichiometric matrix of a loop toy model augmented with kinetic-parameter blocks If and Ir: build the augmented matrix, test its stoichiometric consistency, report the row rank deficiency of [F R; If Ir], and inspect A*A’ symbolically for a left-nullspace vector.

checkRankFR(model, printLevel)

Calculates the rank of [F R] and [F; R], when restricted to certain rows and columns

USAGE:

[rankFR, rankFRV, rankFRvanilla, rankFRVvanilla, model] = checkRankFR (model, printLevel)

INPUTS:

• model –

  COBRA model structure with fields:

  • .S - m x n stoichiometric matrix

  • .lb - n x 1 lower flux bounds (used when rescaling or restricting to reconstruction bounds)

  • .ub - n x 1 upper flux bounds (used when rescaling or restricting to reconstruction bounds)

  • .b - m x 1 accumulation/depletion vector (used in geometric-mean scaling)

  • .c - n x 1 linear objective coefficients (used in geometric-mean scaling)

  The following boolean fields are used if already present, otherwise they are computed:

  • .SIntRxnBool - n x 1 boolean of internal (non-exchange) reactions

  • .SIntMetBool - m x 1 boolean of metabolites in internal reactions

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

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

• printLevel – verbose level

OUTPUTS:

• rankFR – rank of [F R], when using only FRrows

• rankFRV – rank of [F; R], when using only FRVcols

• rankFRvanilla – rank of [F R], when using all rows

• rankFRVvanilla – rank of [F; R], when using all cols

• model – input model returned with the following added or updated fields:

  • .SIntRxnBool_findSExRxnInd - n x 1 boolean of internal reactions from findSExRxnInd, before mass/consistency refinement

  • .balancedRxnBool - n x 1 boolean of elementally balanced reactions

  • .balancedMetBool - m x 1 boolean of elementally balanced metabolites

  • .Elements - cell array of chemical elements detected by checkMassChargeBalance

  • .missingFormulaeBool - m x 1 boolean of metabolites lacking a chemical formula

  • .FRnonZeroRowBool1 - m x 1 boolean of nonzero rows of [F R] over the first consistent reaction subset

  • .FRnonZeroColBool1 - n x 1 boolean of nonzero cols of [F; R] over the first consistent metabolite subset

  • .FRuniqueRowBool - m x 1 boolean of rows of [F R] unique up to scalar multiplication

  • .FRuniqueColBool - n x 1 boolean of cols of [F; R] unique up to scalar multiplication

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

  • .fluxConsistentMetBool - m x 1 boolean of metabolites in flux consistent reactions

  • .V - n x k flux matrix with \(S V = 0\); \(1^T |V| > 1\) for flux consistent reactions

  • .P - m x k exchange contribution of the stoichiometrically and flux consistent part

  • .FRnonZeroRowBool - m x 1 boolean of nonzero rows of [F R] over the final reaction subset

  • .FRnonZeroColBool - n x 1 boolean of nonzero cols of [F; R] over the final metabolite subset

  • .largestConnectedRowsFRBool - m x 1 boolean of rows in the largest connected component of [F R]

  • .largestConnectedColsFRVBool - n x 1 boolean of cols in the largest connected component of [F; R]

  • .FRrows - m x 1 boolean of rows of [F R] used in the restricted rank calculation

  • .FRVcols - n x 1 boolean of cols of [F; R] used in the restricted rank calculation

  • .mC - mass vector from the stoichiometric consistency check of (R - F)

  • .Frb - forward half-stoichiometric matrix of the bilinear form of the restricted [F R]

  • .Rrb - reverse half-stoichiometric matrix of the bilinear form of the restricted [F R]

  • .rankBilinearFrRr - rank of the bilinear [F R]

  • .FRdrows - m x 1 boolean of dependent rows of [F R]

  • .FRirows - m x 1 boolean of independent rows of [F R]

  • .FRq - column permutation from the rank factorisation of [F R]

  • .FRp - row permutation from the rank factorisation of [F R]

  • .Fr - forward half-stoichiometric matrix restricted to FRrows and FRVcols

  • .Rr - reverse half-stoichiometric matrix restricted to FRrows and FRVcols

  • .FRVdcols - n x 1 boolean of dependent cols of [F; R]

  • .FRVicols - n x 1 boolean of independent cols of [F; R]

  • .FRVq - column permutation from the rank factorisation of [F; R]

  • .FRVp - row permutation from the rank factorisation of [F; R]

  • .Fc - forward half-stoichiometric matrix restricted to FRrows and FRVcols

  • .Rc - reverse half-stoichiometric matrix restricted to FRrows and FRVcols

  • .FRrowRankDeficiency - row rank deficiency of [F R]

  • .FRW - matrix expressing dependent rows of [F R] as combinations of independent rows

  • .FRwrows - m x 1 boolean of independent rows that dependent rows depend on

  • .FRcolRankDeficiency - column rank deficiency of [F; R]

  • .FRVW - matrix expressing dependent cols of [F; R] as combinations of independent cols

  • .FRVwcols - n x 1 boolean of independent cols that dependent cols depend on

combinatorialDependentRows(A)

Find two combinatorially dependent subsets of rows of a binary [F, R] matrix

Solves a binary feasibility problem (via CVX) for two nonempty, disjoint subsets of the rows of A that share the same column support; feasibility of the problem means the two subsets are combinatorially dependent.

USAGE:

[x, y] = combinatorialDependentRows (A)

INPUTS:

A – binarized [F R] matrix with entries in {0, 1}; each row indexes a (half-)reaction whose column support is compared

OUTPUTS:

• x – m x 1 binary indicator vector selecting the first subset of rows

• y – m x 1 binary indicator vector selecting the second subset of rows

connectedFR(F, R)

Computes the connected sets of rows of [F, R] and the largest connected set of columns of [F; R] using gamic

USAGE:

[connectedRowsFRBool, connectedColsFRVBool] = connectedFR (F, R)

INPUTS:

• F – m x n

• R – m x n

OUTPUTS:

• connectedRowsFRBool – m x z boolean vector indicating z sets of connected rows

• connectedColsFRVBool – n x z boolean vector indicating z sets of connected cols

extractFRfromResults

Extract the forward and reverse half-stoichiometric matrices [F, R] from a stored FR-analysis results structure, restricted to the rows that make [F R] full row rank (model.FRrows) for the model selected by index i.

for i=1:12, depending on which model wanted

largestConnectedFR(F, R, printLevel)

Computes the largest connected set of rows of [F, R] and the largest connected set of columns of [F; R] using gamic

USAGE:

[connectedRowsFRBool, connectedColsFRVBool] = largestConnectedFR (F, R, printLevel)

INPUTS:

• F – m x n

• R – m x n

• printLevel – verbose level

OUTPUTS:

• connectedRowsFRBool – m x 1 boolean vector indicating largests set of connected rows

• connectedColsFRVBool – n x 1 boolean vector indicating largests set of connected cols

makeFRresultsTable(FRresults, resultsDirectory, resultsFileName, modelMetaData, tableFilename)

Makes a table of FR results

USAGE:

[FRresultsTable, FRresults] = makeFRresultsTable (FRresults, resultsDirectory, resultsFileName, modelMetaData, tableFilename)

INPUT:

FRresults – output of checkRankFRdriver

OPTIONAL INPUTS:

• resultsDirectory – directory where output of checkRankFRdriver has been saved

• resultsFileName – filename where output of checkRankFRdriver has been saved

• modelMetaData – Cell array, where each row is metadata for one model with five columns: species, version, fileName, PMID, doi. See function modelMetaData = modelCitations()

• tableFilename – If provided, a the table of results is written out to a csv file, with specified filename

OUTPUTS:

• FRresultsTable – table displaying the results of checkRankFRdriver

• FRresults – output of checkRankFRdriver

plotFRresults(FRresults, nRows, nCols, resultsDirectory, resultsFileName, schematicFlag, modelMetaData)

Plots FR results in the same order as the FRresultsTable using FRresults structure or by loading the FRresults structure

USAGE:

plotFRresults (FRresults, nRows, nCols, resultsDirectory, resultsFileName, schematicFlag, modelMetaData)

INPUTS:

• FRresults – output of checkRankFRdriver

• nRows – number of rows in the subplot

• nCols – number of rows in the subplot (\(nRows*nCols \geq length(FRresults)\))

OPTIONAL INPUTS:

• resultsDirectory – directory where output of checkRankFRdriver has been saved

• resultsFileName – filename where output of checkRankFRdriver has been saved

• schematicFlag – default = 1

• modelMetaData – metadata of model

printFRdependencies(model, filePathName)

Reports on the dependencies between rows of [F, R], either to the command line (default) or to a specified text file

USAGE:

printFRdependencies (model, filePathName)

INPUT:

model – model output from checkRankFR, with fields:

• .S - m x n stoichiometric matrix

• .mets - m x 1 cell array of metabolite identifiers

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

• .FRVcols - n x 1 boolean of cols of [F; R] used in the rank calculation

• .FRdrows - m x 1 boolean of dependent rows of [F R]

• .FRwrows - m x 1 boolean of independent rows that dependent rows depend on

• .FRW - matrix expressing dependent rows of [F R] as combinations of independent rows

OPTIONAL INPUT:

filePathName – full file name for printing dependencies to file

rowRankSufficientFR

Illustrate row-rank sufficiency of the [F, R] half-stoichiometric matrix on small toy examples: build forward and reverse matrices F and R from a chosen stoichiometric matrix and report the rank (and left-nullspace) of [F R].

testBP

Test bipartiteness of the sizeable connected components of the [F, R] incidence graph: decompose a stoichiometric matrix B into forward and reverse matrices F and R, form the graph of FR, and check each component.

testBilinearDecomposition

Test bilinearDecomposition on a selection of small and loaded stoichiometric matrices S: build S from the chosen test case, factorise it as S = A*B*C, and report the row and column sizes of S and of the returned factors A, B and C.

testCombinatorialDependentRows

Test combinatorialDependentRows on a small binary [F, R] matrix A, printing the two combinatorially dependent subsets of rows returned in x and y.

testFRconnectedness

script to test the connectedness of an [F R]