spacr.uniprot

Resolve an organism or an accession against UniProt, and cache what comes back.

Regression’s gene annotation used to be a BOOLEAN. Toxoplasma=True joined a bundled table of Toxoplasma gondii annotations onto the coefficients; False left them as bare accessions. So the one thing the module knew about biology was welded to one parasite, and a Plasmodium screen, a Neospora screen or a host-gene screen got nothing at all.

The setting is a FIELD instead:

  • empty, or any spelling of Toxoplasma gondii – exactly what it did before, from the bundled CSVs, with no network at all. That path is the default and it must never depend on this module;

  • an organism name or a taxon id – that organism’s reviewed proteome from UniProt;

  • a single accession – that one entry.

WHAT MUST RESOLVE, and why ORGANISMS is a table rather than a call to UniProt’s own search: the organisms a user of this software actually images should resolve without a round trip, and offline. Hosts people culture cells from; every studied apicomplexan; the other parasites that come up beside them.

NOTHING HERE IS REQUIRED TO OPEN THE MODULE. Every network call is behind a cache, every failure is a warning that names the near-misses UniProt offered, and an unresolvable name leaves the results unannotated rather than stopping a run that has already done its fitting.

Classes

Resolution

What a piece of text in the annotation field turned out to mean.

Functions

annotation_for(text, *[, cache_dir, genes])

(frame, note) for whatever is in the annotation field.

canonical(→ str)

The lookup form of an organism name: lower case, single spaces.

fetch(resolution, *[, cache_dir, reviewed, limit])

Everything UniProt has for resolution, as a DataFrame.

fetch_genes(resolution, genes, *[, cache_dir])

The entries for named genes in resolution's organism.

near_misses(→ Tuple[str, ...])

Organism names close to name, for a message that helps.

organisms_for(→ Tuple[str, ...])

Every name that resolves, or those starting with group.

resolve(→ Resolution)

What text names, without touching the network.

Module Contents

class spacr.uniprot.Resolution[source]

What a piece of text in the annotation field turned out to mean.

Parameters:

  • kind – 'bundled', 'accession', 'organism' or 'unknown'.

  • text – what the user typed, stripped.

  • taxon – the NCBI taxonomy id, for an organism.

  • accession – the accession, for a single entry.

  • near – names close to what was typed, for an unknown one.

__bool__() → bool[source]

Return whether the text resolved to a supported annotation kind.

spacr.uniprot.annotation_for(text, *, cache_dir=None, genes=None)[source]

(frame, note) for whatever is in the annotation field.

Parameters:

text – bundled name, accession, taxon, or organism to resolve.

The one call a pipeline needs. It never raises: an unreachable UniProt, an unknown organism and an empty proteome all come back as (None, note) so the run carries on with unannotated results, which is what the field is for.

spacr.uniprot.canonical(text) → str[source]

The lookup form of an organism name: lower case, single spaces.

Parameters:

text – organism-name text to normalize for lookup.

spacr.uniprot.fetch(resolution: Resolution, *, cache_dir=None, reviewed: bool = True, limit: int = 20000)[source]

Everything UniProt has for resolution, as a DataFrame.

Parameters:

  • resolution – from resolve(). bundled and unknown return None – neither is a UniProt question.

  • cache_dir – where the answer is kept so a rerun is offline.

  • reviewed – Swiss-Prot only. For an organism with no reviewed entries at all the caller gets an empty frame and a warning, which is truer than silently including unreviewed predictions.

  • limit – stop after this many rows.

Returns:

a DataFrame, or None when there is nothing to ask.

spacr.uniprot.fetch_genes(resolution: Resolution, genes, *, cache_dir=None)[source]

The entries for named genes in resolution’s organism.

Parameters:

  • resolution – resolved annotation target. Only an organism resolution supplies the taxonomy identifier needed for this query; other kinds return None without a request.

  • genes – gene names or accessions from the table being annotated.

Returns:

a DataFrame, or None when the query could not be made.

spacr.uniprot.near_misses(name, limit: int = 5) → Tuple[str, ...][source]

Organism names close to name, for a message that helps.

Parameters:

name – normalized or free-form organism name to approximate.

spacr.uniprot.organisms_for(group: str = '') → Tuple[str, ...][source]

Every name that resolves, or those starting with group.

spacr.uniprot.resolve(text) → Resolution[source]

What text names, without touching the network.

Order matters. The bundled names win, because that path must work with no network and must not be changed by anything here. An accession is recognised by shape. Everything else is looked up as an organism, and a name that is not in the table comes back unknown WITH the near misses, because “did you mean” is the whole difference between a typo the user can fix and a silent absence of annotation.

Parameters:

text – whatever is in the annotation field.

Returns:

a Resolution.