Sammim

expa(model, varargin)

Computes the extreme pathways of a stoichiometric model according to the algorithm by Schilling, Letscher and Palsson:

Schilling, C. H., Letscher, D. & Palsson, B. O. Theory for the systemic definition of metabolic pathways and their use in interpreting metabolic function from a pathway-oriented perspective. Journal of theoretical biology 203, 229-48 (2000).

This algorithm is defined in appendix B of the citation above. Steps of the algorithm and relevant excerpts from the paper are quoted as comments throughout the code.

USAGE:

[model, fullmodel] = expa (model, varargin)

INPUTS:

model – Model in the format used with the COBRA Toolbox. Minimum required fields:

• .S - Stoichiometric coefficient matrix

• .lb - Lower bound for reactions

• .ub - Upper bound for reactions

• .rev - Reversibility flag for each reaction. Freely exchanged metabolites (from exchange reactions) are not determined to be so through their reversibility flag, but through non-zero upper and lower bounds. Inputs have a zero upper bound and outputs have a zero lower bound

• .c - Objective function

• .rxns - Reaction names

• .mets - Metabolite identifiers (used to count metabolites that lack an unconstrained exchange flux)

• .fluxtype - (assigned internally) x (exchange) or i (internal) flux type computed for each reaction

• .rules - (optional) reordered/pruned to match the decomposed reaction list, if present

• .rxnGeneMat - (optional) reordered/pruned to match the decomposed reaction list, if present

• .grRules - (optional) reordered/pruned to match the decomposed reaction list, if present

• .subSystems - (optional) reordered/pruned to match the decomposed reaction list, if present

• .confidenceScores - (optional) reordered/ pruned to match the decomposed reaction list, if present

• .rxnReferences - (optional) reordered/pruned to match the decomposed reaction list, if present

• .rxnECNumbers - (optional) reordered/pruned to match the decomposed reaction list, if present

• .rxnNotes - (optional) reordered/pruned to match the decomposed reaction list, if present

• .rxnNames - (optional) reordered/pruned to match the decomposed reaction list, if present

• .P - (added by this function) matrix of extreme pathways

OPTIONAL INPUTS:

varargin – varargin{1} (print) - If given and equal to 1, y, or Y, the function prints the progress of the algorithm

OUTPUTS:

• fullmodel – Decomposed model of the original model input. Reversible reactions get decomposed into two forward reactions. All fields mentioned above get adjusted, and a matrix P, corresponding to the extreme pathways, is added as a field

• model – The model output matches the original model input. This is a collapsed version of the fullmodel output, where the reversible reactions that had been decomposed are combined again. The extreme pathways (field P) are combined as absolute value

makeSAMMIJson(model)

Converts a COBRA model into the JSON string format used by the SAMMI front-end to render a metabolic map

Any additional field of model whose size matches .mets is included as a per-metabolite JSON annotation, and any field whose size matches .rxns is included as a per-reaction JSON annotation

USAGE:

jsonstr = makeSAMMIJson (model)

INPUT:

model – COBRA model structure with fields:

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

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

• .S - m x n stoichiometric matrix

OUTPUT:

jsonstr – Character array with the SAMMI JSON representation of model, of the form {“metabolites”:[…],”reactions”:[…]}

makeSAMMIdataString(tbl)

Converts a data table into the array-string format used by the SAMMI front-end to receive flux, concentration, or width data

USAGE:

tblstring = makeSAMMIdataString (tbl)

INPUT:

tbl – MATLAB table with fields:

• .Properties.VariableNames - condition names, one column of numeric data per condition

• .Properties.RowNames - reaction or metabolite identifiers, one per row

OUTPUT:

tblstring – Character array encoding tbl as the nested array string [[headers],[rowName,val1,val2,…],…] used by the SAMMI front-end

makeSAMMIparseVector(dat)

Converts a struct array describing SAMMI subgraphs into the array-string format used by the SAMMI front-end to filter the model into subgraphs

USAGE:

parsevec = makeSAMMIparseVector (dat)

INPUT:

dat – Struct array, one element per subgraph, with fields:

• .name - name of the subgraph

• .rxns - cell array of reaction identifiers included in the subgraph

• .flux - optional numeric vector, one value per reaction in .rxns, mapped as reaction color; if dat has a flux field, empty entries are filled with NaN

OUTPUT:

parsevec – Character array encoding dat as the nested array string [[name,[rxn,flux],…],…] used by the SAMMI front-end

openSammi(htmlName)

Visualize the given model, set of reactions, and/or data using SAMMI. Documentation at: https://sammim.readthedocs.io/en/latest/index.html

Citation: Schultz, A., & Akbani, R. (2019). SAMMI: A Semi-Automated

Tool for the Visualization of Metabolic Networks. Bioinformatics.

USAGE:

openSammi (htmlName)

OPTIONAL INPUT:

htmlName – Name of the html file previously written using the sammi function. If left blank, prints the names of all available models instead of opening one.

OUTPUT:

No MATLAB output, opens the visualization in a new browser tab.

sammi(model, parser, data, secondaries, options)

Visualize the given model, set of reactions, and/or data using SAMMI. Documentation at: https://sammim.readthedocs.io/en/latest/index.html

Citation: Schultz, A., & Akbani, R. (2019). SAMMI: A Semi-Automated Tool for the Visualization of Metabolic Networks. Bioinformatics.

USAGE:

sammi (model, parser, data, secondaries, options)

INPUTS:

model – COBRA model to be visualized. Fields used:

• .rxns - reaction identifiers

• .subSystems - subsystem assigned to each reaction; read when parser names a model field used to split the model into subgraphs

OPTIONAL INPUTS:

• parser – How the model is to be parsed. Default empty array. One of four forms:

  • Empty array - all reactions in the model are loaded in a single map. Not advisable for large maps.

  • Char array - either the path to a SAMMI map (JSON file downloaded from a previous instance of SAMMI), in which case the given map is used, or the name of a field in the model struct, in which case that field is used to parse the model into subgraphs.

  • Cell array - a cell array of reaction ID strings; only these reactions are included in a single SAMMI map.

  • Struct array of length n - the model is parsed into n subgraphs. Each element should contain two required fields plus one optional field:

    • .name - name of the subgraph

    • .rxns - reactions to be included in the subgraph

    • .flux - optional; data to be mapped as reaction color

• data – Data to be mapped onto the model. Struct of length n. Defaults to an empty array where no data is mapped. Each element should contain two fields:

  • .type - a cell array of two strings; the first is rxns, mets, or links, indicating which type of data is mapped, and the second is color or size, indicating how the data is mapped (links only supports size, since link color follows the associated reaction)

  • .data - a table object; VariableNames are translated into condition names, and RowNames should be reaction IDs for rxns/links data and metabolite IDs for mets data. NaN values are not mapped

• secondaries – Cell array of regular-expression strings. All metabolites, in all subgraphs, matching any of the regular expressions are shelved. Defaults to an empty array where no metabolites are shelved.

• options – Struct with the following fields:

  • .htmlName - name of the html file to be written and opened for the visualization. Defaults to index_load. Change this field to write to a different html file that will not be overwritten by the default option

  • .load - load the html file in a new tab upon writing the file. Defaults to true. If a new tab should not open, set this field to false and refresh a previously opened window; use the openSammi function to open a new window without re-running sammi

  • .jscode - string, defaults to an empty string. Additional JavaScript code to run after loading the map. Can be any code to modify the loaded map

OUTPUT:

No MATLAB output. Opens a browser window with the SAMMI visualization.

Examples

%1 Open model in single map sammi(model)

%2 Open model as multiple subgraphs divided by subSystems sammi(model,’subSystems’)

%3 Open model as multiple subgraphs divided by subSystems, load two %conditions with randomly generated data, and shelve hydrogen, water, %and O2 upon loading. rxntbl = array2table(randn(length(model.rxns),2),…

‘VariableNames’, {‘condition1’,’condition2’},… ‘RowNames’, model.rxns);

data(1).type = {‘rxns’ ‘color’}; data(1).data = rxntbl; data(2).type = {‘rxns’ ‘size’}; data(2).data = rxntbl; secondaries = {‘^h[.]$’,’^h20[.]$’,’^o2[.]$’}; sammi(model,’subSystems’,data,secondaries)