Localization (Python)#

raven-toolbox objects in raven_toolbox.localization.

Functions#

Function	Summary
`annotate_proteome`	Annotate the transporters of a proteome from sequence with `hmmsearch` and `diamond`.
`annotate_transporters`	Parse a per-gene transporter-annotation table into `TransporterAnnotation` objects.
`apply_assignment`	Build the compartmentalised model from a proposal (deep copy; the original is unchanged).
`apply_localization`	Apply a `LocalizationProposal` to `model`: move reactions, add the
`assign_compartments`	Assign `reactions_to_relocate` to compartments and certify functionality with an FBA.
`AssignmentProposal`	Outcome of `assign_compartments`.
`combine_scores`	Merge several `LocalizationScores` into a consensus by weighted sum.
`confidence_bin`	Calibration bin of a raw confidence, with the bins of the benchmark's corroboration rates.
`curation_priority`	Rank reaction placements and added transports by how likely each needs manual curation.
`default_metabolite_chebi`	ChEBI identifiers from a metabolite's annotation, normalised to `CHEBI:NNNN`.
`default_substrate_of`	Coarse substrate class(es) for a model metabolite, from a name-keyword heuristic.
`evidence_aware_transport_cost`	Per-metabolite transport cost from transporter evidence, for the `transport_cost` argument.
`fetch_protein_sequences`	Fetch `{gene_id: protein_sequence}` from the UniProtKB REST API for an organism.
`fetch_uniprot_localization`	Query the UniProtKB REST API for the subcellular locations of an organism and return
`GrowthCondition`	An extra medium that the placement must also support, checked when certifying functionality.
`load_compartments`	Parse a COMPARTMENTS (jensenlab.org) channel file into a normalised
`load_deeploc`	Parse DeepLoc 2 CSV output into a normalised `LocalizationScores`.
`load_mulocdeep`	Parse MULocDeep output into a normalised `LocalizationScores`.
`load_tc_substrates`	Load `tcdb_substrates.tsv` as `{TC-ID: frozenset(ChEBI)}`.
`load_uniprot`	Parse a UniProtKB export into a normalised `LocalizationScores`.
`LocalizationProposal`	What `predict_localization` proposes, before applying it.
`LocalizationResult`	Outcome of `predict_localization` (when `apply=True`).
`LocalizationScores`	Per-gene compartment scores. `df` is indexed by `gene_id` with one column per
`predict_localization`	Place a caller-specified set of reactions in compartments with a MILP.
`prepare_deeploc_input`	Write a FASTA of protein sequences for `genes` as input for DeepLoc 2.1.
`PreparedFasta`	Outcome of `prepare_deeploc_input`.
`relocate_reactions`	Place reactions in curator-chosen compartments and repair the model around the decision.
`RelocationResult`	Outcome of `relocate_reactions`: the repaired proposal and a log of every change.
`ReviewReport`	Ranked curation suggestions from `triage_localization` (one row per flagged item).
`SubstrateOntology`	The ChEBI graph and the TCDB substrate table, with a graded metabolite-to-substrate match.
`TransporterAnnotation`	Per-gene transporter evidence from any source (Pfam with `hmmsearch`, TCDB with
`triage_localization`	Rank the localisation calls in `proposal` for manual curation, without a solver.
`write_fasta`	Write `{id: sequence}` to FASTA and return the file path(s).

Reference#

annotate_proteome#

Annotate the transporters of a proteome from sequence with hmmsearch and diamond.

Searches the proteome FASTA (headers are gene ids, as written by prepare_deeploc_input) against the transporter Pfam HMM database (hmmsearch --cut_ga) and the TCDB DIAMOND database (diamond blastp); both databases are downloaded from toolbox-assets when not supplied. Pfam families and TCDB TC-families map to coarse substrate classes through raven_toolbox.localization.transporter_tables, and the TCDB TC-IDs of each gene map to their curated substrate ChEBIs (substrates: a path to tcdb_substrates.tsv, or False to skip that lookup). Returns gene -> TransporterAnnotation, with mechanism set to None. Genes without a transporter hit are absent, so the compartment-only match (no substrate_of, no ontology) counts only genes with a hit.

Parameters

proteome : str or Path: Protein FASTA file whose headers are gene ids.
hmm_db : str or Path or None: Transporter Pfam HMM database for hmmsearch (default None, downloaded from toolbox-assets).
tcdb_db : str or Path or None: TCDB DIAMOND database (default None, downloaded from toolbox-assets).
substrates : str or Path or bool or None: Path to tcdb_substrates.tsv, which maps TCDB TC-IDs to curated substrate ChEBIs. None or True (default None) loads the file downloaded from toolbox-assets. False skips the lookup.
threads : int: Number of threads for hmmsearch and diamond (default 1).

annotate_transporters#

annotate_transporters(table: pd.DataFrame, *, gene_col: str='gene', confidence_col: str='confidence', families_col: str | None='families', substrate_col: str | None='substrate_classes', mechanism_col: str | None='mechanism', sep: str=';')

Parse a per-gene transporter-annotation table into TransporterAnnotation objects.

The table can come from any tool (eggNOG-mapper, InterProScan, a web service). annotate_proteome runs the bundled hmmsearch and diamond back-ends instead. The list columns (families, substrate_classes) may hold lists or sep-joined strings. A gene that appears on several rows keeps its highest confidence and the union of the families and of the substrate classes.

Parameters

table : pandas.DataFrame: One row per gene and annotation. The column gene_col is required; a missing confidence_col column gives confidence 0.
gene_col : str: Column with the gene ids (default "gene").
confidence_col : str: Column with the annotation confidence (default "confidence"). An empty string or None counts as 0; a missing pandas value (NaN) is carried as NaN.
families_col : str or None: Column with the transporter families (default "families"), as a list or a string joined by sep. None ignores families.
substrate_col : str or None: Column with the coarse substrate classes (default "substrate_classes"), in the same form as families_col. None ignores substrate classes.
mechanism_col : str or None: Column with the transport mechanism (default "mechanism"), for example "uniport", "symport" or "antiport". A missing value gives None. None ignores the mechanism.
sep : str: Separator of the joined strings in families_col and substrate_col (default ";").

apply_assignment#

apply_assignment(model: cobra.Model, proposal: AssignmentProposal, *, default_compartment: str='c', base_metabolite: Callable[[cobra.Metabolite], str] | None=None, universal: cobra.Model | None=None)

Build the compartmentalised model from a proposal (deep copy; the original is unchanged).

The same base_metabolite and universal as in assign_compartments give the same compartment-agnostic keying (existing per-compartment metabolites are reused and not duplicated) and add the chosen gap-fill reactions. Raises ValueError when two metabolites in one compartment of model have the same key.

Parameters

model : cobra.Model: The model the proposal was computed for. It is copied; the original is unchanged.
proposal : AssignmentProposal: Placements, added transports and added gap-fill reactions to apply.
default_compartment : str: Hub compartment of the star-topology transports in proposal.added_transports (default "c").
base_metabolite : callable or None: Maps a metabolite to its compartment-agnostic key. The default key is the base id that raven_toolbox.manipulation.merge_compartments stored on a merged metabolite, otherwise the id without the suffix of the metabolite's own compartment.
universal : cobra.Model or None: Reaction database that contains the ids in proposal.added_reactions. When None, no gap-fill reactions are added.

apply_localization#

apply_localization(model: cobra.Model, proposal: LocalizationProposal, *, default_compartment: str='c')

Apply a LocalizationProposal to model: move reactions, add the

inter-compartment transports of the proposal, and return (model_copy, added).

The returned model is a deep copy of the input (the original is unchanged). Moved reactions get their metabolites' compartment suffix swapped (for example A_c → A_m); new compartment-specific metabolite copies are added as needed. Each added transport is a passive diffusion M[default] ⇌ M[c] (RAVEN convention), named tr_<met>_<c>.

Parameters

model : cobra.Model: The model the proposal was computed for. It is copied; the original is unchanged.
proposal : LocalizationProposal: The reactions to move and the transports to add.
default_compartment : str: Compartment from which each added transport starts (default "c").

assign_compartments#

assign_compartments(model: cobra.Model, scores: LocalizationScores, reactions_to_relocate: Iterable[str], *, default_compartment: str='c', transport_cost: float | Mapping[str, float]=0.5, multi_compartment_penalty: float=0.5, transportable: Iterable[str] | None=None, base_metabolite: Callable[[cobra.Metabolite], str] | None=None, universal: cobra.Model | None=None, biomass_reaction: str | None=None, min_growth: float | None=None, growth_conditions: Iterable[GrowthCondition] | None=None, max_rounds: int=8, time_limit: float | None=None, prune_transports: bool=True, minimize_transports: bool=False, multi_localize: bool=False, multi_localize_threshold: float=0.7, multi_localize_eps: float=1e-06, multi_localize_loopless: bool=True)

Assign reactions_to_relocate to compartments and certify functionality with an FBA.

A flux-free score MILP decides the placement. A repair step adds transports (and gap-fill reactions when universal is given), and the result is certified by an FBA on the applied model. When no tightening is available or the round budget ends, the best proposal is returned uncertified (see the module docstring and the compartment-assignment redesign <https://github.com/CompMetEng/raven-gecko-parity/blob/develop/docs/localization/localization_redesign.md>_ on raven-gecko-parity).

Parameters

model : cobra.Model

The draft model. It is not modified. Raises ValueError when two metabolites in one compartment have the same base_metabolite key, and when min_growth is None and the model does not grow.

scores : LocalizationScores

Gene x compartment localisation scores. A reaction whose genes all have no row in the scores is listed in unplaced_reactions of the result.

reactions_to_relocate : iterable of str

Ids of the reactions that the placement may move. Boundary reactions, the biomass reaction and reactions whose metabolites do not lie in exactly one compartment (existing multi-compartment transports) are skipped. All other reactions keep their compartment.

default_compartment : str

Hub compartment of the star-topology transports, and the compartment that receives gene-free and score-tied reactions (default "c"). Raises ValueError when it is neither a compartment of model nor of scores.

transport_cost : float or mapping of str to float

Accepted and not used (default 0.5): the placement master is flux-free and score-only, and minimize_transports prunes transports by flux (pFBA), not by cost.

multi_compartment_penalty : float

Weight (default 0.5) subtracted in the primary placement pass for each gene-compartment assignment. A higher value places a gene in fewer compartments. A value of 0 applies no penalty.

transportable : iterable of str or None

Base ids of the metabolites eligible for a cross-compartment transport. None (default) allows every metabolite touched by a relocatable reaction. A narrower set forbids transports for the other metabolites, and the reactions that share them are co-located by the confinement repair.

base_metabolite : callable or None

Maps a metabolite to its compartment-agnostic key (default None). The default key is the base id that raven_toolbox.manipulation.merge_compartments stored on a merged metabolite, otherwise the id without the suffix of the metabolite's own compartment.

universal : cobra.Model or None

Reaction database for gap-fill (default None). When the primary medium falls short of the growth floor, the repair adds reactions from this model. When None, no gap-fill is done. The metabolite ids of universal have to match those of model.

biomass_reaction : str or None

Id of the reaction whose flux is the growth measure (default None). When None, the reaction with the largest objective coefficient is used. Raises ValueError when the model has no objective.

min_growth : float or None

Biomass flux that the materialised model has to reach on the primary medium (default None). When None, the floor is 10 % of the maximum flux of biomass_reaction in model. Raises ValueError when biomass_reaction cannot carry flux in model.

growth_conditions : iterable of GrowthCondition or None

Extra media on which the materialised model has to reach the floor of the condition (default None, the primary medium only). The growth of each condition is reported in growths of the result.

max_rounds : int

Maximum number of placement rounds (confinement repair and growth-failure feedback; default 8). When every metabolite is transportable, the confinement repair adds no rounds and the common genome-scale case certifies in one round.

time_limit : float or None

Solver time limit in seconds for each placement MILP pass, truncated to an integer (default None, no limit). A solution found at the limit is used.

prune_transports : bool

If True (default), drop transports that are blocked in every certification medium.

minimize_transports : bool

If True, prune the transport and gap-fill set after certifying to the reactions that carry flux in a parsimonious FBA solution (_minimize_transports; yeast-GEM: ~1260 -> ~280 transports). The pruned set is certified again against every medium, and the un-minimised set is kept if the pruning removed a transport that a growth condition needs. Default False; the option adds one pFBA and one certification.

multi_localize : bool

If True, add multi-compartment placements after certifying (_enrich_multilocalization): for each reaction, a second compartment is proposed if its gene has a DeepLoc score >= multi_localize_threshold there, all candidates are materialised, and one loopless FVA keeps those that can carry a flux of at least multi_localize_eps in a biomass-supporting solution. The placement master stays mono-localised, and the FVA removes duplicates that carry no flux. Default False; the option adds one FVA.

The gate (DeepLoc score above the threshold and flux in the FVA) removes duplicates that carry no flux, and does not test whether the enzyme is dual-localised. Many reactions can carry some flux in a second compartment without being dual, so many reactions are multi-placed (in the yeast-GEM run, about 700 of 2300 reactions at the default threshold). The gate recovers the DeepLoc-visible dual enzymes (for example HTS1, VAS1, GLR1) and misses enzymes that are dual by post-translational retro-translocation (FUM1, ACO1), whose second compartment carries no DeepLoc signal. A candidate source based on function (a metabolite required in the second compartment) is not implemented. The result is a lower bound on multi-localisation, not a precise dual-localisation call.

multi_localize_threshold : float

DeepLoc score that a gene needs in a second compartment for that placement to be proposed (default 0.7). A higher value gives fewer duplicates with higher confidence and misses duals (yeast-GEM: 0.9 drops HTS1, VAS1 and GLR1; 0.7 keeps them).

multi_localize_eps : float

Flux magnitude that a proposed duplicate must reach in the FVA to be kept (default 1e-6).

multi_localize_loopless : bool

If True (default), use loopless FVA, so a duplicate that is active only in a futile cycle is not kept. False gives a faster check that permits cycles.

Returns

AssignmentProposal: certified is set if and only if the materialised model reached the growth floor on every medium, and growths gives the biomass flux per medium ("__primary__" and each condition name). status is "certified" or "uncertified" (or a solver status if the master failed).

AssignmentProposal#

Outcome of assign_compartments.

Attributes

placements:: reaction_id -> [compartments] the reaction is assigned to (one or more).
gene_compartments:: gene_id -> [compartments].
added_transports:: (base_metabolite_id, compartment) pairs that need a transport between the compartment and default_compartment.
added_reactions:: ids of gap-fill reactions taken from the universal model to make the compartmentalised network functional.
unplaced_reactions:: relocate-set reactions that have genes, none of which has a score (the placement master places them without gene evidence).
objective:: objective value of the placement. assign_compartments leaves it at the default 0.0.
min_growth:: the growth floor enforced.
status:: solver status ("optimal", "infeasible", ...), "certified" or "uncertified". The last two state whether an FBA on the materialised model confirmed the functionality of the placement.
certified:: True if and only if apply_assignment followed by FBA reaches the growth floor on every medium.
growths:: set by assign_compartments: the materialised biomass flux per medium ("__primary__" and each GrowthCondition name), which shows how far an uncertified placement fell short.

combine_scores#

combine_scores(sources: list[LocalizationScores], *, weights: list[float] | None=None)

Merge several LocalizationScores into a consensus by weighted sum.

Genes and compartments are the union across sources; absent entries count as 0. Scores are summed per (gene, compartment) (optionally weighted) and the result is per-gene normalised (best -> 1.0), so a compartment supported by several sources scores higher than a compartment supported by one source. The consensus combines complementary evidence (for example DeepLoc, curated UniProt and COMPARTMENTS); two curated sources agree on ~90% of the genes in yeast-GEM. Raises ValueError when sources is empty or weights and sources differ in length.

Parameters

sources : list of LocalizationScores: The score tables to merge.
weights : list of float or None: One weight per source (default None, a weight of 1.0 for every source).

confidence_bin#

confidence_bin(p: float)

Calibration bin of a raw confidence, with the bins of the benchmark's corroboration rates.

curation_priority#

curation_priority(model: cobra.Model, proposal: AssignmentProposal, scores: LocalizationScores, *, base_metabolite: Callable[[cobra.Metabolite], str] | None=None, default_compartment: str='c', universal: cobra.Model | None=None, currency_metabolites: Iterable[str] | None=None, check_essential: bool=True, essential_candidate_threshold: float=0.2, min_growth: float | None=None, include_curated: bool=False)

Rank reaction placements and added transports by how likely each needs manual curation.

Returns a pandas.DataFrame sorted by priority (descending), one row per (reaction, compartment) placement and per flagged added transport, with columns target (id), type ("placement", "gapfill" or "transport"), compartment, priority (0-1), flags (the names of the signals that fired, strongest first), action (a text that names the check for the strongest signal, for example to re-place the reaction in the neighbouring compartment), n_affected and affected. A dual-localised reaction yields one row per compartment.

n_affected and affected give the one-hop coupling of each row: the other placed reactions that curating this one touches, because they share a non-currency metabolite with it at the same compartment (for a placement) or depend on the transported species at either end of the bridge (for a transport). n_affected is the full count; affected lists up to 12 ids, the ones also flagged in this table first, followed by +N for the remainder. The coupling is not transitive: each coupled reaction has its own coupled reactions.

Parameters

model : cobra.Model: The draft model that was placed. Raises ValueError when two metabolites in one compartment have the same base_metabolite key.
proposal : AssignmentProposal: The proposal whose placements, gap-fill reactions and added transports are scored.
scores : LocalizationScores: Gene x compartment localisation scores that were used for the placement.
base_metabolite : callable or None: Maps a metabolite to its compartment-agnostic key. The same as in assign_compartments (default None, the default key of that function).
default_compartment : str: Hub compartment of the transports (default "c"). It is the compartment reported for a gap-fill reaction whose metabolites in universal do not lie in a single compartment, and the second end of the bridge in the coupling of a transport.
universal : cobra.Model or None: The same as in assign_compartments (default None). It gives the compartment and the metabolites of a gap-fill reaction, and the model that the essentiality check materialises.
currency_metabolites : iterable of str or None: Ids or names of organism-specific pools that count as freely available (default None). They extend the built-in currency and cofactor set (ATP, NAD(P)H, H+, H2O, CoA, Pi, ...) that is excluded from the topology signals.
check_essential : bool: If True (default), run a single-reaction-deletion essentiality check (an FBA per candidate) on the already-flagged placements (base priority >= essential_candidate_threshold). The score of a placement is multiplied by 1.6 when removing it drops the growth of the materialised model to below 1 % of its growth. Essentiality is measured against the achievable growth of the applied model, not the heuristic growth floor of the assignment. The check is skipped if the floor is 0 or if the materialised model does not exceed that floor (a comparison with the floor would then flag every candidate). False skips this signal, the only one that needs FBA.
essential_candidate_threshold : float: Minimum base priority (before the essentiality factor) that a placement needs to be checked for essentiality (default 0.2).
min_growth : float or None: Floor used for the comparison in the essentiality check (default None, the min_growth of proposal).
include_curated : bool: If False (default), a reaction whose localization confidence is marked curated (via raven_toolbox.confidence.mark_curated, for example after a curator settled its placement) is dropped from the result, so a settled reaction does not reappear. True scores it anyway.

default_metabolite_chebi#

default_metabolite_chebi(metabolite: cobra.Metabolite)

ChEBI identifiers from a metabolite's annotation, normalised to CHEBI:NNNN.

This is the model-side input to the ChEBI substrate match and can be passed as metabolite_chebi to evidence_aware_transport_cost. A metabolite without a chebi annotation returns the empty set and is matched by coarse class only.

Parameters

metabolite : cobra.Metabolite: The metabolite whose chebi annotation (one identifier or a collection) is read.

default_substrate_of#

default_substrate_of(metabolite: cobra.Metabolite)

Coarse substrate class(es) for a model metabolite, from a name-keyword heuristic.

The function matches the name of the metabolite against curated keyword lists, without further dependencies, and returns classes of transporter_tables.COARSE_CLASSES: (S)-malate gives carboxylate, D-glucose gives sugar and NADPH gives nucleotide and cofactor_vitamin. It can be passed as substrate_of to evidence_aware_transport_cost. Classes are not derived from the ChEBI or KEGG annotation of the metabolite. A metabolite that matches no keyword returns the empty set and receives no support from the coarse class match.

Parameters

metabolite : cobra.Metabolite: The metabolite whose name (the id when the name is empty) is matched against the keywords.

evidence_aware_transport_cost#

evidence_aware_transport_cost(model: cobra.Model, annotation: Mapping[str, TransporterAnnotation], gene_compartments: Mapping[str, Iterable[str]], *, substrate_of: Callable[[cobra.Metabolite], Iterable[str]] | None=None, ontology: SubstrateOntology | None=None, metabolite_chebi: Callable[[cobra.Metabolite], Iterable[str]] | None=None, sibling_weight: float=0.0, base_cost: float=0.5, base_metabolite: Callable[[cobra.Metabolite], str] | None=None)

Per-metabolite transport cost from transporter evidence, for the transport_cost argument.

For each (compartment-agnostic) metabolite m::

evidence(m) = max over transporter genes g of  g.confidence * substrate_match(g, m),
              restricted to genes localised to a compartment where m occurs (membrane gate).
cost(m)     = base_cost * (1 - evidence(m))

substrate_match is 1.0 for a coarse substrate-class overlap and, when an ontology is given, a graded value from 0 to 1 from the ChEBI roll-up (metabolite ChEBI to the curated substrate ChEBI of the gene), which also gives evidence for metabolites that the coarse classifier misses. With neither substrate_of nor ontology, the match is by compartment only (every carrier at the right membrane counts). A gene without compartments in gene_compartments is not restricted by the membrane gate.

Parameters

model:: the model to cost; every compartment-independent metabolite base in it has an entry in the result.
annotation:: gene -> transporter evidence, as returned by annotate_transporters or annotate_proteome.
gene_compartments:: gene -> predicted compartment ids (the DeepLoc compartment calls). A carrier at compartment X supports transports across the boundary of X.
substrate_of:: metabolite -> its coarse substrate class(es) (for example default_substrate_of); a class overlap with the gene gives a substrate match of 1.0.
ontology:: a .substrate_ontology.SubstrateOntology that enables the graded ChEBI-substrate match for pairs without a coarse class overlap.
metabolite_chebi:: metabolite -> its ChEBI id(s) for the ChEBI match (default: default_metabolite_chebi, which reads the chebi annotation).
sibling_weight:: if > 0, a metabolite that is a chemical relative of a curated substrate (it shares a near ChEBI ancestor and is not below the substrate) also receives evidence, at this fraction of a direct hit. The credit increases recall and lowers specificity (0 disables it; default 0).
base_cost:: the flat cost of an unsupported transport; a metabolite that no gene supports receives this cost.
base_metabolite:: metabolite -> the compartment-independent key to group it under (default: the id without a trailing _<compartment>).

Returns

dict[str, float]: every metabolite base -> cost (unsupported metabolites map to base_cost).

fetch_protein_sequences#

fetch_protein_sequences(organism: int | str, *, genes: Iterable[str] | None=None, id_field: str='gene_oln', reviewed: bool=True, extra_query: str | None=None, min_length: int=1, timeout: float=120.0)

Fetch {gene_id: protein_sequence} from the UniProtKB REST API for an organism.

A UniProt entry listing several ids for the field maps each of them to its sequence. The query is the same as in fetch_uniprot_localization. Raises ValueError when id_field is not one of the accepted values.

Parameters

organism : int or str: UniProt organism or taxon id (for example 559292 for S. cerevisiae S288C).
genes : iterable of str or None: Restricts the result to those gene ids (other entries are fetched and dropped). None (default) returns every entry.
id_field : str: Identifier used as key (default "gene_oln"): "gene_oln" (ordered locus, the ORF name like YNR001C; matches yeast-GEM gene ids), "accession" or "gene_primary".
reviewed : bool: If True (default), keep only curated Swiss-Prot entries.
extra_query : str or None: UniProt query string that is ANDed into the query (default None).
min_length : int: Drops sequences shorter than it (default 1; DeepLoc 2.1 needs >= 10 aa).
timeout : float: Timeout of the HTTP request in seconds (default 120.0).

fetch_uniprot_localization#

fetch_uniprot_localization(organism: int | str, *, compartment_map: Mapping[str, str]=DEFAULT_COMPARTMENT_MAP, id_field: str='gene_oln', reviewed: bool=True, extra_query: str | None=None, timeout: float=120.0)

Query the UniProtKB REST API for the subcellular locations of an organism and return

normalised LocalizationScores.

Parsing is as in load_uniprot. Raises ValueError when id_field is not one of the accepted values.

Parameters

organism : int or str: UniProt organism or taxon id (for example 559292 for S. cerevisiae S288C).
compartment_map : mapping of str to str: Maps the location labels to model compartment ids, as in load_uniprot (default DEFAULT_COMPARTMENT_MAP).
id_field : str: Identifier used as gene id (default "gene_oln"): "gene_oln" (ordered locus, the ORF name like YNR001C; matches yeast-GEM), "accession" or "gene_primary".
reviewed : bool: If True (default), restrict the query to curated Swiss-Prot entries.
extra_query : str or None: UniProt query string that is ANDed into the query (default None).
timeout : float: Timeout of the HTTP request in seconds (default 120.0).

GrowthCondition#

An extra medium that the placement must also support, checked when certifying functionality.

assign_compartments materialises the placement and confirms that it reaches min_growth by an FBA on the primary medium and on each GrowthCondition medium. A transport or placement therefore has to serve every condition that needs it, which keeps alternative-carbon-source pathways (respiration, β-oxidation, the glyoxylate cycle, ...) connected to the rest of the network.

Parameters

name:: Short label for the condition, used in the per-condition growth report. Unique per condition.
medium:: exchange_reaction_id -> max uptake (>= 0). Exchanges not listed are closed for uptake, so medium fully specifies the environment (carbon source and supplements).
min_growth:: Biomass floor this condition must reach on the materialised model.

load_compartments#

load_compartments(path: str | Path, *, compartment_map: Mapping[str, str] | None=None, min_confidence: float=0.0)

Parse a COMPARTMENTS (jensenlab.org) channel file into a normalised

LocalizationScores.

Reads the tidy *_<channel>_full.tsv layout (no header): column 1 = protein or gene id, column 4 = GO compartment term name, last column = confidence score. Rows are aggregated per (gene, compartment) by the maximum confidence; min_confidence drops weak annotations (the integrated and text-mining channels score 0 to 5).

The per-organism files (for example yeast_compartment_integrated_full.tsv) are available from https://download.jensenlab.org/, also when the COMPARTMENTS Downloads web page is unavailable. Raises ValueError when the file has fewer than 5 columns.

Parameters

path : str or Path: COMPARTMENTS channel file.
compartment_map : mapping of str to str or None: Renames the GO compartment term names to model compartment ids (default None, which keeps the term names). A term absent from the map is dropped (see the module docstring).
min_confidence : float: Drops annotations whose confidence score is below it (default 0.0).

load_deeploc#

load_deeploc(path: str | Path, *, compartment_map: Mapping[str, str] | None=None, min_confidence: float=0.0, membrane_split: Mapping[str, str] | None=None, membrane_threshold: float=0.5, keep_raw_confidence: bool=False, normalise: bool=True)

Parse DeepLoc 2 CSV output into a normalised LocalizationScores.

DeepLoc 2's per-protein CSV has Protein_ID, Localizations, Signals then one probability column per compartment. The first column is the gene id; non-numeric metadata columns (Localizations, Signals) are dropped. The measurements behind membrane_split and normalise are in the DeepLoc yeast-GEM benchmark <https://github.com/CompMetEng/raven-gecko-parity/blob/develop/docs/localization/deeploc_yeast_benchmark.md>_ and the DeepLoc normalisation benchmark <https://github.com/CompMetEng/raven-gecko-parity/blob/develop/docs/localization/deeploc_normalisation_benchmark.md>_ on raven-gecko-parity.

Parameters

path : str or Path: DeepLoc 2 CSV file.
compartment_map : mapping of str to str or None: Renames the predictor labels to model compartment ids (default None, which keeps the labels). A label absent from the map is dropped with its column (see the module docstring).
min_confidence : float: Drops genes whose top compartment probability (before per-gene normalisation) is below it (default 0.0, which keeps every gene). In the yeast-GEM benchmark of the confidence study, the share of calls that other evidence corroborates rises with the raw probability.
membrane_split : mapping of str to str or None: For example {"m": "mm"} (default None, no split). It moves the probability of an organelle to its membrane sub-compartment when the protein is membrane-associated (1 - P(Soluble) >= membrane_threshold, using DeepLoc's Soluble column); otherwise it stays in the lumen. Keys and values are the compartment ids of the model (after compartment_map). A key that is not a compartment of the table is skipped. Raises ValueError when the file has no Soluble column. The evidence supports only the mitochondrial split (m/mm; matrix versus membrane AUC ~0.93). DeepLoc does not separate the ER lumen from the membrane, so a split of er has no support.
membrane_threshold : float: Value of 1 - P(Soluble) from which a protein counts as membrane-associated (default 0.5). Used only with membrane_split.
keep_raw_confidence : bool: If True, attach the per-gene pre-normalisation top probability to LocalizationScores.raw_confidence (default False; normalisation otherwise sets every top to 1.0). triage_localization uses it for its low-confidence signal.
normalise : bool: If True (default), rescale the best compartment of every gene to 1.0. This follows the RAVEN parseScores convention and keeps the scales of several sources comparable. False keeps DeepLoc's raw probabilities. The raw probabilities are calibrated (a 0.97 call is more reliable than a 0.40 one), so a downstream assignment can weight confident genes more heavily.

load_mulocdeep#

load_mulocdeep(path: str | Path, *, compartment_map: Mapping[str, str] | None=None, id_column: str | None=None, sep: str | None=None, min_confidence: float=0.0)

Parse MULocDeep output into a normalised LocalizationScores.

Expects a wide table: a protein or gene id column plus one numeric probability column per major subcellular compartment (MULocDeep predicts 10).

Parameters

path : str or Path: MULocDeep output table.
compartment_map : mapping of str to str or None: Renames the predictor labels to model compartment ids (default None, which keeps the labels). A label absent from the map is dropped with its column (see the module docstring).
id_column : str or None: Name of the id column (default None, the first column).
sep : str or None: Field delimiter (default None, auto-detected).
min_confidence : float: Works as in load_deeploc (default 0.0).

load_tc_substrates#

load_tc_substrates(path: str | Path | None=None)

Load tcdb_substrates.tsv as {TC-ID: frozenset(ChEBI)}.

The file is downloaded if path is None.

load_uniprot#

load_uniprot(path: str | Path, *, compartment_map: Mapping[str, str]=DEFAULT_COMPARTMENT_MAP, id_column: str | None=None, location_column: str | None=None, sep: str='\t')

Parse a UniProtKB export into a normalised LocalizationScores.

UniProt's curated Subcellular location [CC] annotation is qualitative (a set of compartments, not probabilities), so each annotated compartment gets score 1.0 (a multi-location protein gets 1.0 in several compartments). The annotation text is scanned for the labels in compartment_map (which is therefore also the vocabulary), and the labels are mapped to the compartment ids of the model. Labels match as whole words (cytoplasm does not match Cytoplasmic vesicle). Evidence {ECO:…} braces are removed, the text is split into one block per [Isoform …]: and the Note=… free text is cut within each block, so incidental mentions there are ignored and the locations of a later isoform are kept.

The columns are the distinct codes of compartment_map in the order they first occur when the map keys are sorted, whether or not a gene has a hit in them, as in RAVEN. Genes without a hit are absent. When a gene occurs in several rows, the first row is kept, the genes are sorted and a UserWarning is issued.

Export from https://rest.uniprot.org with fields=accession,gene_oln,cc_subcellular_location (TSV). Raises ValueError when compartment_map is empty and when no location column is found.

Parameters

path : str or Path: UniProtKB export.
compartment_map : mapping of str to str: Maps the location labels to model compartment ids, and is the vocabulary that the annotation text is scanned for (default DEFAULT_COMPARTMENT_MAP).
id_column : str or None: Column with the gene ids (default None, the first column, the accession in this export). For yeast-GEM, the ordered-locus column (Gene Names (ordered locus), the ORF id like YNR001C) matches the gene ids.
location_column : str or None: Column with the subcellular location annotation (default None, the first column whose name contains subcellular, ignoring case).
sep : str: Field delimiter of the file (default " ").

LocalizationProposal#

What predict_localization proposes, before applying it.

All DataFrames have one row per item. With apply=False, the proposal previews the changes; apply_localization applies it.

LocalizationResult#

Outcome of predict_localization (when apply=True).

LocalizationScores#

Per-gene compartment scores. df is indexed by gene_id with one column per

compartment id; values are floats (higher = stronger evidence for that compartment).

raven_toolbox.localization.predict_localization counts a NaN entry as score 0, leaves a gene absent from df out of its gene coupling, and lists a reaction that has genes, none of them in df, in unplaced_reactions. A reaction without a GPR is placed freely and is not listed.

raw_confidence (optional) is a per-gene Series of the pre-normalisation top probability of the predictor. The loaders normalise every gene's best compartment to 1.0, which discards the confidence of the call. load_deeploc populates raw_confidence with keep_raw_confidence=True, so downstream consumers (notably raven_toolbox.localization.triage_localization) can tell a 0.97 call from a 0.40 one.

predict_localization#

predict_localization(model: cobra.Model, scores: LocalizationScores, reactions_to_relocate: Iterable[str], *, default_compartment: str='c', transport_cost: float | Mapping[str, float]=0.5, multi_compartment_penalty: float=0.5, apply: bool=True, mip_gap: float | None=None, time_limit: float | None=None)

Place a caller-specified set of reactions in compartments with a MILP.

Returns a LocalizationProposal (when apply=False) or a LocalizationResult (when apply=True).

Multi-compartment gene scoring (default): a gene contributes its predictor score in each compartment it is assigned to. The highest-scoring compartment is free, and each additional compartment costs multi_compartment_penalty. A secondary compartment is picked when its score (lower than the primary) exceeds the penalty; there is no hard cutoff. A large multi_compartment_penalty gives mono-localised genes.

Parameters

model : cobra.Model: The model to place reactions in. With apply=True the result holds a copy and the original is unchanged. Raises ValueError when default_compartment is neither a compartment of model nor of scores.
scores : LocalizationScores: Gene x compartment localisation scores. A reaction whose genes all have no row in the scores is listed in unplaced_reactions and is not moved.
reactions_to_relocate : iterable of str: The reaction ids to (re-)place. All other reactions stay where they are. Boundary reactions and existing multi-compartment transports in this set are filtered out without a message (they are always pinned). An empty set, or a set without non-boundary reactions, gives an empty proposal (a LocalizationResult holding a copy of the model when apply=True).
default_compartment : str: Hub compartment of the added transports (default "c"). Each transport connects the metabolite in this compartment to the metabolite in the target compartment.
transport_cost : float or mapping of str to float: A scalar (same cost per added transport) or a mapping {metabolite_id_base: cost} (default 0.5). The base id has the compartment suffix removed, for example "glc__D" matches "glc__D_c" and "glc__D_e"; a full metabolite id is also looked up. A metabolite missing from the mapping costs 0.5. Negative costs favour adding the transport.
multi_compartment_penalty : float: Cost (default 0.5) of each additional compartment of a gene (see above). A value of 0 applies no penalty.
apply : bool: If True (default), apply the proposal with apply_localization and return a LocalizationResult. If False, return the LocalizationProposal and leave the model unchanged.
mip_gap : float or None: Relative MIP gap at which the solver stops (default None, the solver default). It is set through the Gurobi parameter MIPGap and ignored by other solvers.
time_limit : float or None: Maximum solve time of the MILP in seconds, truncated to an integer (None = no limit). With no limit, a model with more than about 5,000 gene-associated reactions, or with ambiguous scores, can make the solve run for a long time; time_limit=900 stops it after 15 min with the incumbent solution. MATLAB RAVEN's predictLocalization has a default maxTime of 15 min (900 s), but it solves this problem with simulated annealing, so its maxTime is not a solver cutoff with an optimality guarantee.

prepare_deeploc_input#

prepare_deeploc_input(genes: Iterable[str] | cobra.Model, organism: int | str, path: str | Path, *, max_records_per_file: int | None=500, min_length: int=10, **fetch_kwargs)

Write a FASTA of protein sequences for genes as input for DeepLoc 2.1.

Sequences are fetched from UniProtKB (see fetch_protein_sequences). Returns a PreparedFasta with the file path(s) and the genes that had no sequence (with the default reviewed=True, no reviewed sequence). The CSV that DeepLoc 2.1 writes for these files is read with load_deeploc; its Protein_ID column holds these gene ids.

Parameters

genes : iterable of str or cobra.Model: Gene ids, or a cobra model (its .genes ids are used). For yeast-GEM those are the ORF names that match id_field="gene_oln".
organism : int or str: UniProt organism or taxon id, as in fetch_protein_sequences.
path : str or Path: Output FASTA file. When the output is split, the chunk number is added to the stem.
max_records_per_file : int or None: The FASTA is split into files of this many records (default 500, the DeepLoc 2.1 web-server limit). None writes one file, for the standalone tool, which has no limit.
min_length : int: Drops sequences below this length (default 10, the DeepLoc minimum of 10 aa).
**fetch_kwargs : dict: Forwarded to fetch_protein_sequences, for example reviewed, id_field, extra_query and timeout.

PreparedFasta#

Outcome of prepare_deeploc_input.

relocate_reactions#

relocate_reactions(model: cobra.Model, proposal: AssignmentProposal, decisions: dict[str, str], *, base_metabolite: Callable[[cobra.Metabolite], str] | None=None, default_compartment: str='c', biomass_reaction: str | None=None, min_growth: float | None=None, universal: cobra.Model | None=None, move_gene_siblings: bool=True, prune_orphan_transports: bool=True)

Place reactions in curator-chosen compartments and repair the model around the decision.

Returns a RelocationResult with the repaired proposal and a log of every secondary change (gene-linked co-moves, transports added and removed, and the growth certificate). The transport repair only changes species of the moved reactions.

Parameters

model : cobra.Model: The draft model that proposal was computed for. Raises ValueError when two metabolites in one compartment have the same base_metabolite key.
proposal : AssignmentProposal: The current assignment, as returned by assign_compartments. It is not modified.
decisions : dict of str to str: Maps reaction ids to the compartment the curator wants them in. A reaction that is not in model, a boundary reaction, and a reaction that is already only in the requested compartment are skipped (the first two with a warning in the result).
base_metabolite : callable or None: Maps a metabolite to its compartment-agnostic key. The same as in assign_compartments (default None, the default key of that function).
default_compartment : str: Hub compartment of the transports (default "c"). No transport is added when a reaction moves into this compartment, and none is removed when a reaction leaves it.
biomass_reaction : str or None: Id of the reaction used as objective when growth is measured (default None). When None or not in the materialised model, the objective of model is used.
min_growth : float or None: Growth floor for the certificate (default None, the min_growth of proposal).
universal : cobra.Model or None: The same as in assign_compartments (default None). It supplies the gap-fill reactions of proposal when the model is materialised.
move_gene_siblings : bool: If True (default), move every other reaction whose genes all belong to moved reactions and all point to the same moved-to compartment ("one enzyme, one compartment"), and report them. A reaction is left in place when one of its genes does not belong to a moved reaction, when its genes point to different compartments, or when its placement has more than one compartment.
prune_orphan_transports : bool: If True (default), remove a transport of species b at the old compartment of a moved reaction when no other reaction uses b there.

RelocationResult#

Outcome of relocate_reactions: the repaired proposal and a log of every change.

moved maps every relocated reaction id to (from_compartment, to_compartment) (the curator's pins and any gene-linked co-moves); from_compartment joins several compartments with +. co_moved lists the reactions moved as a gene-consistency consequence. transports_added and transports_removed are (metabolite_base, compartment) tuples. growth_before and growth_after are the objective value of the materialised model before and after; certified is True when growth_after is above 1e-9 and reaches min_growth (within 1e-9).

ReviewReport#

Ranked curation suggestions from triage_localization (one row per flagged item).

SubstrateOntology#

The ChEBI graph and the TCDB substrate table, with a graded metabolite-to-substrate match.

Build an instance with load (downloads and caches both artefacts) and pass it to .transport_evidence.evidence_aware_transport_cost. Reachability closures are memoised, so scoring a whole model reuses the roll-up of each metabolite ChEBI.

TransporterAnnotation#

Per-gene transporter evidence from any source (Pfam with hmmsearch, TCDB with

diamond, orthology or a hand-curated table). confidence is a strength from 0 to 1; substrate_classes are coarse shared classes (for example "amino_acid", "sugar", "carboxylate") that match a transporter to the metabolites it plausibly carries; substrate_chebi are the specific curated substrate ChEBIs (from TCDB) for the ChEBI-ontology match.

triage_localization#

triage_localization(proposal: object, scores: LocalizationScores, *, model: cobra.Model | None=None, sources: Mapping[str, LocalizationScores] | None=None, raw_confidence: pd.Series | None=None, compartment_trust: Mapping[str, float] | None=None, confidence_threshold: float=0.7, margin_threshold: float=0.15, entropy_threshold: float=0.7, weights: Mapping[str, float] | None=None, top_n: int | None=None)

Rank the localisation calls in proposal for manual curation, without a solver.

Returns a ReviewReport ranked by uncertainty.

Parameters

proposal : object: A localisation or assignment proposal with the attributes gene_compartments (gene -> [compartments]) and unplaced_reactions; both LocalizationProposal and raven_toolbox.localization.assign.AssignmentProposal provide them.
scores : LocalizationScores: The table that the proposal is based on.
model : cobra.Model or None: Adds the ids of the reactions that each gene gates to the reactions column (default None, an empty list).
sources : mapping of str to LocalizationScores or None: The per-source tables before fusion, for example {"DeepLoc": ..., "UniProt": ...} (default None). It enables the source-conflict signal, which is not available after combine_scores.
raw_confidence : pandas.Series or None: Gene -> top probability of the predictor (default None). It enables the low-confidence signal. If it is omitted, it is read from scores.raw_confidence (set by load_deeploc(keep_raw_confidence=True)), and if that is also absent, the confidence signal is skipped.
compartment_trust : mapping of str to float or None: Per-compartment accuracy of the predictor (default None, which uses DEEPLOC_COMPARTMENT_TRUST). A compartment absent from the mapping counts as 1.0.
confidence_threshold : float: Raw confidence below which the low-confidence signal fires (default 0.7; see the module docstring).
margin_threshold : float: Difference between the two highest scores below which the borderline signal fires (default 0.15).
entropy_threshold : float: Normalised score entropy above which the diffuse signal fires (default 0.7).
weights : mapping of str to float or None: Weight of each signal in the blended uncertainty score (default None). The default weights are confidence 0.35, disagreement 0.25, margin 0.20, weak_compartment 0.10 and entropy 0.10. A key that is absent from a given mapping has weight 0.1.
top_n : int or None: Limits the number of returned rows (default None, all rows).

write_fasta#

write_fasta(sequences: Mapping[str, str], path: str | Path, *, max_records_per_file: int | None=None, wrap: int=60)

Write {id: sequence} to FASTA and return the file path(s).

Headers are the dict keys verbatim (no leading >). FASTA truncates a header at the first space and many tools identify results by that token, so ids must not contain whitespace; a ValueError is raised otherwise.

Parameters

sequences : mapping of str to str: Maps each FASTA header to its sequence. An empty sequence gives the header line only.
path : str or Path: Output file. With chunking, the chunk number is added to the stem (see max_records_per_file).
max_records_per_file : int or None: With a value set (for example 500 for the DeepLoc 2.1 web server) and more records than that, records are split across <stem>_001<suffix>, <stem>_002<suffix>, ... and every path is returned. Otherwise (default None) a single file is written at path.
wrap : int: Residues per line (default 60; <= 0 gives one line per sequence).