rotifer.db.uniprot.webapi.idmapping.MappingCursor#

class rotifer.db.uniprot.webapi.idmapping.MappingCursor(*args, **kwargs)[source]#

Bases: MappingCursor, BaseUniProtWebCursor

Translate identifiers through UniProt’s entry cross-references.

A UniProtKB entry lists every database it is cross-referenced to, so one request answers a mapping in either direction: the entries are fetched, and the cross-references they carry are read off. That is what lets this backend answer an open ended query, which UniProt’s asynchronous mapping service cannot: the service translates between one pair of databases per job, and there are ninety-odd of them.

It is also the faster route. Fetching entries is a plain paged GET, while a mapping job must be submitted, polled and only then read, which costs seconds before any work is done.

What it carries is not what idmapping.dat carries. Entries cross-reference the databases a curator recorded – Pfam, GO, InterPro, AlphaFoldDB among them – while the flat file also holds identifiers derived from the sequence, such as UniRef clusters, UniParc and CRC64 checksums, which are not cross-references and do not appear here. Neither source contains the other, which is why a delegator asks both.

Parameters:

**kwargs: Extra UniProt query parameters.

Attributes:

columnslist of str: Column names of the mapping dataframe.

See also

rotifer.db.uniprot.clickhouse.MappingCursor: the same query, from an indexed copy
rotifer.db.uniprot.mirror.MappingCursor: the same query, from the flat file

Examples

Every cross-reference of an accession, which needs no database named:

>>> from rotifer.db.uniprot import webapi
>>> mc = webapi.MappingCursor()
>>> mc.fetchall(['Q6GZX4'], source=mc.UNIPROTKB)

Which accession an external identifier belongs to, without saying which database it comes from:

>>> mc.fetchall(['YP_031579.1'], target=mc.UNIPROTKB)

Between two databases:

>>> mc.fetchall(['AAT09660.1'], source=['EMBL'],
...             target=['RefSeq','Pfam'])

databases()[source]#

Name the databases UniProt cross-references entries to.

UniProt publishes the list, so it is asked rather than guessed, and remembered for the life of the cursor. The names are the ones entries themselves report, which is what makes them comparable with the databases the local backends hold.

Returns:

set of str or None: None when the list cannot be fetched, so that a network failure narrows nothing.

fetcher(accession, source=None, target=None, *args, **kwargs)[source]#

Fetch the entries that can answer the query.

Identifiers that are UniProtKB accessions are taken from the batch endpoint; everything else is looked up through the cross-reference index, which finds an entry from an identifier without being told which database it belongs to.

Parameters:

accessioniterable of str: Identifiers to translate.
source, targetstr or list of str, optional: The two ends of the mapping. Either may be omitted.

Returns:

list of dict: The entries found.

fields()[source]#

Map each database to the result field that returns it.

Asking for named fields instead of whole entries is worth the lookup: a batch of five entries is 3 KiB with the fields named and 147 KiB without. UniProt labels each field with the database it carries, so the correspondence is read from the API rather than guessed from the spelling, which would be wrong for a sixth of them.

Returns:

dict: Database name to field name. Empty when the list cannot be fetched, which simply means whole entries are requested.

parser(stream, accession, source=None, target=None, *args, **kwargs)[source]#

Read the mappings off the entries fetched.

Each entry carries the accession and the cross-references it has. The identifiers asked about are matched against both, so an entry found through one of its cross-references reports that cross-reference as the source rather than the accession.

Parameters:

streamlist of dict: Entries returned by fetcher().
accessioniterable of str: Identifiers that were requested.
source, targetstr or list of str, optional: The two ends of the mapping.

Returns:

pandas.DataFrame: The columns listed in columns.

page_size = 100#: Entries per page of a reverse lookup.