Localization#

MATLAB functions in RAVEN/src/localization of the RAVEN toolbox.

Functions#

Function

Summary

assignCompartments

Assign reactions to compartments by a functionality-constrained MILP.

defaultCompartmentMap

Default map from compartment labels to model compartment ids.

getUniProtScores

Fetch curated subcellular locations from UniProt as a gene scoring structure.

parseScores

Parse predictor or database output into a gene scoring structure (GSS).

predictLocalization

Assign reactions to compartments using localization predictors.

Reference#

assignCompartments#

function [outModel, placement, addedTransports, exitFlag] = assignCompartments(model, GSS, reactionsToRelocate, varargin)

Assign reactions to compartments by a functionality-constrained MILP.

Deterministic alternative to predictLocalization: a single MILP places the requested reactions into compartments to agree with localization scores (GSS) WHILE keeping the model's objective (biomass) producible. Because functionality is a hard constraint, a reaction is placed against its own top score whenever the network needs it there (pathway coherence emerges from requiring flux, not from a heuristic). Mono-localization: each reaction is placed in exactly one compartment; a gene still spans compartments when it catalyses reactions placed in different ones.

The model is merged to a single compartment first (like predictLocalization); the MILP then re-distributes the relocatable reactions across the compartments named in GSS, adding passive transports (defaultCompartment <-> c) where needed.

Parameters

model : struct

a RAVEN model with an objective (model.c) and grRules. Multiple compartments are merged.

GSS : struct

gene scoring structure (genes, compartments, scores) as from parseScores. GSS.compartments are the target compartment labels and must include defaultCompartment.

reactionsToRelocate : cell

reaction ids to (re)place. Boundary reactions and the objective reaction are always pinned.

Name-Value Arguments

defaultCompartment : char

compartment that transports route through (usually cytosol); must be in GSS.compartments.

transportCost : double (default 0.5)

cost per added inter-compartment transport.

multiCompartmentPenalty : double (default 0.5)

cost per extra compartment a gene ends up in.

minGrowth : double (default [] = 10%% of the unconstrained optimum)

required objective flux.

transportable : cell (default [] = all)

metabolite ids (merged-model names) that may receive transports. Restricting it forces functionality-driven placement of reactions whose substrates are confined.

bigM : double (default 1000)

Big-M for flux gating.

verbose : logical (default true) :

Returns

outModel : struct

the compartmentalised model (objective still producible).

placement : struct

.rxns and .compartment (the assigned compartment id per relocated reaction).

addedTransports : struct

.mets and .compartment for the transports the MILP added.

exitFlag : double

1 = optimal, -1 = infeasible/failed.

See also

predictLocalization, parseScores, gapFillMILP

defaultCompartmentMap#

function map = defaultCompartmentMap()

Default map from compartment labels to model compartment ids.

Returns a containers.Map from lower-case compartment labels of predictors and databases (as used by DeepLoc, MULocDeep, COMPARTMENTS and UniProt) to compartment ids, for yeast and fungal models (for example yeast-GEM codes). The map is passed to parseScores or getUniProtScores as 'compartmentMap'.

The map holds three decisions:

  • Compartments present. A label absent from the map is dropped along with its score column, so the map lists only the compartment ids of the model. 'plastid' is absent because fungi have no plastid; a plant model adds it.

  • Labels that name the same compartment. Predictors differ in wording, so 'cytoplasm' and 'cytosol' both map to 'c', and 'mitochondrion', 'mitochondria' and 'mitochondrial' all map to 'm'. Merged columns are combined by their maximum.

  • Distinct compartments that are collapsed. 'lysosome' maps to 'v' because a yeast model has no lysosome and the vacuole is its functional equivalent. A model that separates the two needs a different mapping.

Changes to the mapping go into a copy of the map, which leaves this function unedited, for example:

map = defaultCompartmentMap;
map('cell wall') = 'ce';
GSS = parseScores(file, 'compartmentMap', map);

Returns

map : containers.Map

label (char, lower case) -> compartment id (char).

See also

parseScores, getUniProtScores, predictLocalization

getUniProtScores#

function GSS = getUniProtScores(organism, varargin)

Fetch curated subcellular locations from UniProt as a gene scoring structure.

Queries the UniProtKB REST API for the "Subcellular location" annotations of an organism and parses them into the GSS consumed by predictLocalization. No manual export is needed. UniProt locations are qualitative, so each annotated compartment gets score 1.0 and a protein with several annotated locations scores 1.0 in each of them. The function requires an internet connection.

Parameters

organism : double or char

a UniProt organism (taxonomy) id (for example 559292 for S. cerevisiae S288C).

Name-Value Arguments

idField : char

which identifier becomes the gene id: 'gene_oln' (ordered locus or ORF name, the default, which matches yeast-GEM), 'accession', or 'gene_primary'.

reviewed : logical

true to restrict the query to curated Swiss-Prot entries (default true).

compartmentMap : containers.Map

maps UniProt location terms to the compartment ids of the model (default defaultCompartmentMap). The keys are also the vocabulary searched for in the "Subcellular location [CC]" free text of UniProt, matched as whole words and case insensitively. The keys must be the noun forms used by UniProt ('endoplasmic reticulum', not 'ER'), and a term that is not a key is not searched. Several keys may share one compartment id, which merges them; since every hit scores 1.0, a protein annotated to any of the merged terms scores 1.0 in that compartment. One key cannot map to two compartment ids; parseScores describes how to duplicate a column of the returned GSS instead.

extraQuery : char

an additional UniProt query clause, combined with the query by AND (for example 'gene:CIT1').

Returns

GSS : struct

a gene scoring structure for predictLocalization.

Examples

GSS = getUniProtScores(559292);                       % all reviewed S. cerevisiae proteins
GSS = getUniProtScores(559292, 'idField', 'accession');
map = defaultCompartmentMap; map('cell wall') = 'ce';  % extend the vocabulary
GSS = getUniProtScores(559292, 'compartmentMap', map);

See also

parseScores, predictLocalization, defaultCompartmentMap

parseScores#

function GSS = parseScores(inputFile, varargin)

Parse predictor or database output into a gene scoring structure (GSS).

Reads the output of a subcellular localisation predictor or evidence database and builds the gene scoring structure consumed by predictLocalization. Scores are normalised so that the highest score of each gene is 1.0.

Parameters

inputFile : char

the file with the predictor or database output.

Name-Value Arguments

predictor : char

'deeploc' (DeepLoc 2 per-protein CSV, default), 'cello' (CELLO), 'mulocdeep' (MULocDeep wide table: gene id + one probability column per compartment), 'compartments' (a COMPARTMENTS jensenlab.org channel TSV), or 'uniprot' (a UniProtKB TSV export with a "Subcellular location [CC]" column).

compartmentMap : containers.Map

maps the compartment labels of the predictor or database to the compartment ids of the model. Keys are the labels as the predictor writes them, in lower case; values are the compartment ids in the GSS. Optional for every predictor except 'uniprot', where the map also supplies the location vocabulary and defaults to defaultCompartmentMap. See Compartment mapping below.

idColumn : char or double

column (name or 1-based index) holding the gene id for 'mulocdeep' and 'uniprot' (default: the first column). For yeast-GEM, the UniProt ordered-locus column holds the matching ids.

minConfidence : double

for 'compartments', drop annotations with confidence below this (default 0).

Returns

GSS : struct

a gene scoring structure for predictLocalization, with fields:

  • genes : cell, one entry per gene.

  • compartments : cell, one entry per compartment column.

  • scores : double, numel(genes)-by-numel(compartments), normalised so that the highest score per gene is 1.0.

Compartment mapping

Predictors use their own compartment vocabulary ("Endoplasmic reticulum", "Golgi apparatus", ...), which need not match the compartment ids of a model. compartmentMap is a containers.Map that translates the labels; the translation happens only there, so the returned GSS contains the ids of the map values. defaultCompartmentMap returns an example map for yeast and fungal models, which can be used as it is or as a template. Three rules apply:

  • A label that is not in the map is dropped, together with its whole score column. This excludes compartments that the model does not have (defaultCompartmentMap has no 'plastid' key, so plastid scores are dropped for a fungal model). Without a map, every label is kept unchanged.

  • Several labels may share one compartment id, which merges their columns. The merged score of a gene is the maximum over the merged labels, not their sum: a gene predicted 0.7 cytoplasm and 0.4 cytosol scores 0.7 for 'c'. Sharing an id merges synonyms and collapses compartments that the model does not separate (defaultCompartmentMap sends both 'vacuole' and 'lysosome' to 'v'). Column order follows the first appearance of each id.

  • One label cannot map to two compartment ids: a containers.Map holds one value per key. A split is made on the returned scores. Duplicating the column afterwards lets a gene predicted "golgi" compete for both 'g' and 'v':

    GSS = parseScores(file, 'compartmentMap', map);
g = strcmp(GSS.compartments, 'g');
GSS.compartments{end+1} = 'v';
GSS.scores(:,end+1) = GSS.scores(:,g);

    The two columns are then independent: predictLocalization assigns each gene to one compartment, so it picks whichever of 'g' and 'v' keeps the network better connected. Halving the copied column gives the evidence half the weight in the second compartment.

For 'uniprot', the keys are also the terms searched for in the "Subcellular location [CC]" free text, matched as whole words and case insensitively. The keys must be the noun forms used by UniProt. A term that is not a key is not searched.

Examples

GSS = parseScores(file, 'predictor', 'deeploc');
GSS = parseScores(file, 'predictor', 'deeploc', 'compartmentMap', defaultCompartmentMap);
GSS = parseScores(file, 'predictor', 'uniprot', 'idColumn', 'Gene Names (ordered locus)');

See also

predictLocalization, getUniProtScores, defaultCompartmentMap

predictLocalization#

function [outModel, geneLocalization, transportStruct, scores,...
	removedRxns] = predictLocalization(model, GSS,...
	defaultCompartment, varargin)

Assign reactions to compartments using localization predictors.

Assigns reactions to compartments so that the assignment agrees with the localization predictors and the network stays connected.

Parameters

model : struct

a model structure. If the model contains several compartments, they are merged.

GSS : struct

a gene scoring structure as from parseScores.

defaultCompartment : char

transport reactions are expressed as diffusion between the defaultCompartment and the others. The compartment is usually the cytosol. It must be one of GSS.compartments.

Name-Value Arguments

transportCost : double

the cost for including a transport reaction. A scalar applies the same cost to all metabolites; a vector must have the same dimension as model.mets. A negative cost favours transport of the metabolite (default 0.5).

maxTime : double

maximum optimisation time in minutes (default 15).

plotResults : logical

true to plot the results during the optimisation (default false).

Returns

outModel : struct

the resulting model structure.

geneLocalization : struct

structure with the genes and their resulting localisation.

transportStruct : struct

structure with the inferred transport reactions and the compartments between which they transport.

scores : struct

structure with the total score history, the score based on gene localisation and the score based on the included transport reactions.

removedRxns : cell

cell array with the ids of the reactions removed to obtain a connected input model.

Notes

The starting network must be connected when it is in one compartment. Unconnected reactions are removed and returned in removedRxns. If many reactions are removed, fillGaps can produce a more connected input model. The input model must not include exchange, demand or sink reactions; otherwise the function provides no results.

In the final model, every metabolite is produced in at least one reaction. Internal loops can still make the model non-functional. Transport reactions are included only as passive diffusion (A <=> B).

The score of a model is the sum of the scores of all genes in their assigned compartment minus the cost of all included transport reactions. A gene is assigned to one compartment, which limits the problem size. The problem is solved by simulated annealing.

Examples

[outModel, geneLocalization, transportStruct, scores, removedRxns] = ...
    predictLocalization(model, GSS, defaultCompartment, ...
        'transportCost', transportCost, 'maxTime', maxTime, ...
        'plotResults', plotResults);