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 predictor/database compartment label -> model compartment id.

getUniProtScores

Fetch curated subcellular locations from UniProt -> gene scoring structure.

parseScores

Parse predictor / 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 predictor/database compartment label -> model compartment id.

Returns a containers.Map from lower-case predictor / database compartment labels (as used by DeepLoc, MULocDeep, COMPARTMENTS and UniProt) to compartment ids, tuned for yeast/fungal models (e.g. yeast-GEM codes). Pass it (or your own map) to parseScores / getUniProtScores as 'compartmentMap'.

The table below is also the worked example of how such a map is built, so read it as three deliberate decisions rather than a lookup list:

  • Which compartments exist. A label absent from the map is dropped along with its score column, so listing only the ids your model has is how unwanted compartments are excluded. 'plastid' is absent because fungi lack one; a plant model would add it.

  • Which labels are the same thing. Predictors disagree on wording, so 'cytoplasm' and 'cytosol' both map to 'c', and 'mitochondrion' / 'mitochondria' / 'mitochondrial' all map to 'm'. Merged columns are combined by maximum, not sum.

  • Which distinct compartments to collapse. 'lysosome' maps to 'v' not because it is a vacuole but because a yeast model has no lysosome and the vacuole is its functional equivalent. Change this if your model separates them.

Extend a copy rather than editing this function, e.g.

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 -> gene scoring structure.

Queries the UniProtKB REST API for an organism's "Subcellular location" annotations and parses them into the GSS consumed by predictLocalization (no manual export needed). UniProt's curated location is qualitative, so each annotated compartment gets score 1.0 (a multi-located protein lands in several). Requires an internet connection.

Parameters

organism : double or char

a UniProt organism / taxonomy id (e.g. 559292 for S. cerevisiae S288C).

Name-Value Arguments

idField : char

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

reviewed : logical

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

compartmentMap : containers.Map

UniProt location term -> your model's compartment id (default defaultCompartmentMap). Here the map is not only a renaming: its keys are also the vocabulary searched for in UniProt's "Subcellular location [CC]" free text, matched whole-word and case insensitively, so they must be UniProt's own noun forms ('endoplasmic reticulum', not 'ER') and a term that is not a key is never looked for. Several keys may share one compartment id, which merges them; since every hit scores 1.0, merging here means "annotated to any of these counts as this compartment". One key cannot be split across two compartment ids - see parseScores for why, and for the recipe to duplicate a column on the returned GSS instead.

extraQuery : char

an additional UniProt query clause, ANDed into the query (e.g. '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 / database output into a gene scoring structure (GSS).

Reads the output of a subcellular-localization predictor or evidence database and builds the gene scoring structure consumed by predictLocalization. Scores are normalized so the best score for each gene is 1.0.

Parameters

inputFile : char

the file with the predictor / 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

renames the predictor's / database's compartment labels to your model's compartment ids. Keys are the labels as the predictor writes them, lower case; values are the compartment ids you want in the GSS. See Compartment mapping below. Optional for every predictor except 'uniprot', where it also supplies the location vocabulary and defaults to defaultCompartmentMap.

idColumn : char or double

column (name or 1-based index) holding the gene id for 'mulocdeep' / 'uniprot'. Default: the first column. For yeast-GEM, use the UniProt ordered-locus column.

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), normalized so the best score per gene is 1.0.

Compartment mapping

Predictors emit their own compartment vocabulary ("Endoplasmic reticulum", "Golgi apparatus", ...), which rarely matches a model's compartment ids. compartmentMap is a containers.Map that translates them, and it is the only place that translation happens - the returned GSS already uses your ids. defaultCompartmentMap returns a worked example, tuned for yeast/fungal models; use it as-is, or as the template for your own. Three rules:

  • A label not in the map is dropped, together with its whole score column. This is how you exclude compartments your model does not have (defaultCompartmentMap has no 'plastid' key, so plastid scores never reach a fungal model). Passing no map at all keeps every label untouched.

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

  • One label cannot be split across two compartment ids: a containers.Map holds one value per key, and the GSS is what predictLocalization scores against, so a split has to be an explicit statement about the returned scores rather than a mapping rule. Duplicate the column afterwards, e.g. to let 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 exactly one compartment, so it picks whichever of 'g'/'v' keeps the network better connected. Halve the copied column instead of duplicating it if the evidence should count for less in the second compartment.

For 'uniprot' the keys do double duty: they are also the terms searched for in the "Subcellular location [CC]" free text, matched whole-word and case insensitively, so they must be UniProt's own noun forms. A term that is not a key is never looked for.

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.

Tries to assign reactions to compartments in a manner that is in agreement with localization predictors while at the same time maintaining connectivity.

Parameters

model : struct

a model structure. If the model contains several compartments they will be merged.

GSS : struct

a gene scoring structure as from parseScores.

defaultCompartment : char

transport reactions are expressed as diffusion between the defaultCompartment and the others. This is usually the cytosol. The default compartment must have a match in GSS.

Name-Value Arguments

transportCost : double

the cost for including a transport reaction. If this is a scalar then the same cost is used for all metabolites. It can also be a vector of costs with the same dimension as model.mets. Negative costs encourage transport of the metabolite (default 0.5).

maxTime : double

maximum optimization time in minutes (default 15).

plotResults : logical

true if the results should be plotted during the optimization (default false).

Returns

outModel : struct

the resulting model structure.

geneLocalization : struct

structure with the genes and their resulting localization.

transportStruct : struct

structure with the transport reactions that had to be inferred and between which compartments.

scores : struct

structure that contains the total score history together with the score based on gene localization and the score based on included transport reactions.

removedRxns : cell

cell array with the reaction ids that had to be removed to have a connected input model.

Notes

This function requires that the starting network is connected when it is in one compartment. Reactions that are unconnected are removed and saved in removedRxns. Try running fillGaps to have a more connected input model if there are many such reactions. The input model should also not include any exchange, demand or sink reactions, otherwise this function would not provide any results.

In the final model all metabolites are produced in at least one reaction. This does not guarantee a fully functional model since there can be internal loops. Transport reactions are only included as passive diffusion (A <=> B).

The score of a model is the sum of scores for all genes in their assigned compartment minus the cost of all transport reactions that had to be included. A gene can only be assigned to one compartment. This is a simplification to keep the problem size down. The problem is solved using simulated annealing.

Examples

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