spacr.uniprot

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

Regression’s gene annotation is not limited to the bundled Toxoplasma gondii table: a Plasmodium, Neospora or host-gene screen can be annotated from UniProt.

The setting is a text field:

• empty, or any spelling of Toxoplasma gondii – the bundled CSVs, with no network access. That path is the default and does not depend on this module;

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

• a single accession – that one entry.

ORGANISMS is a table rather than a call to UniProt’s own search, so that commonly imaged organisms resolve offline without a round trip. Hosts people culture cells from; every studied apicomplexan; the other parasites that come up beside them.

Network access is optional. 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 an error message.
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

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

Return whether the text resolved to a supported annotation kind.

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

(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.

spacr.uniprot.canonical(text) → str

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)

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, rather 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)

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, ...]

Organism names close to name, for an error message.

Parameters:

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

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

Every name that resolves, or those starting with group.

spacr.uniprot.resolve(text) → Resolution

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, so the user can correct a typo instead of silently getting no annotation.

Parameters:

text – whatever is in the annotation field.

Returns:

a Resolution.