rotifer.db.methods.MappingCursor#

class rotifer.db.methods.MappingCursor[source]#

Bases: object

Mixin for cursors that translate identifiers through UniProt.

Every such query has the same shape, whichever direction it runs in: identifiers of one or more databases are matched, their UniProtKB accessions are found, and the identifiers those accessions carry in one or more other databases are returned. Asking for the cross-references of an accession, asking which accession an external identifier belongs to, and translating between two external databases are that one query with different ends pinned, so cursors mixing this class in implement it once.

The two ends are named by fetchall() and fetchone() rather than by the constructor, because they describe a question rather than a data source: one cursor can answer many of them.

Attributes:

columnslist of str: Column names of the mapping dataframe.

classmethod checksum(sequence)[source]#

The checksum UniProt knows a sequence by.

UniProt identifies a sequence by a CRC64 of its residues, and publishes those in idmapping.dat like any other identifier. Biopython computes the same value, prefixed, so the prefix is dropped.

Parameters:

sequencestr: The residues.

Returns:

str: Sixteen uppercase hexadecimal digits.

classmethod sequence_checksums(obj)[source]#

Read the sequences out of an object and check each one.

Parameters:

objBio.SeqRecord.SeqRecord, rotifer sequence, or iterable: One or more sequences, in any of the shapes rotifer passes them around in.

Returns:

dict: Checksum to the names the sequences carrying it were given. Several names can share one checksum, which is the point: the same sequence under two names is one sequence.

static is_sequence(obj)[source]#

Find whether an object carries sequences rather than names one.

Parameters:

objobject

Returns:

bool: True for a Biopython record and for rotifer’s own sequence object, which holds many at once.

static parse_databases(databases)[source]#

Normalize a source or target argument to a list.

Parameters:

databasesstr, iterable of str or None: One database name, several, or None for every database.

Returns:

list of str or None: None when no filter was asked for, which every backend reads as “any database”.

databases()[source]#

Name the databases this cursor can map to and from.

A backend that knows its own vocabulary lets a delegator ask it only for the databases it could answer for, and record the rest as unanswerable here rather than as absent everywhere. The distinction matters: a database missing from a backend is a gap in that copy of the data, while a database no backend supports is a gap in the answer.

Returns:

set of str or None: None when the cursor cannot enumerate them, which is read as “any”, so nothing is narrowed on its account.

empty()[source]#

Build an empty mapping dataframe.

Returns:

pandas.DataFrame: No rows, and the columns listed in columns.

fetchall(accessions, source=None, target=None, *args, **kwargs)[source]#

Translate every identifier, as a single dataframe.

Parameters:

accessionsstr or iterable of str: Identifiers to translate.
sourcestr or list of str, optional: Databases the queried identifiers belong to. None accepts any, and UNIPROTKB means they are UniProtKB accessions.
targetstr or list of str, optional: Databases to translate into. None returns every database, and UNIPROTKB returns the accession itself.

Returns:

pandas.DataFrame: The columns listed in columns. Empty, with those columns, when nothing is found.

getids(obj, *args, **kwargs)[source]#

Report which queried identifiers were translated.

Only the source column is read. It holds what the caller asked about, so what a delegator still has to look for elsewhere is exactly what is missing from it; the identifiers found are answers, not queries, and counting them would mark the wrong things as done.

Parameters:

objpandas.DataFrame, set, str, iterable or None: Mappings produced by the cursor, or a collection of identifiers, returned as a set.

Returns:

set of str

parse_ids(accessions, as_string=True)[source]#

Accept sequences wherever identifiers are accepted.

A sequence is not an identifier, but it has one: its checksum, which UniProt publishes like any other. Turning them into checksums here means every cursor and every access style takes sequences without knowing it, and the names they came under are remembered so a caller can find their way back from a result.

Parameters:

accessionsstr, iterable, sequence object or mixture: Identifiers, sequences, or both.
as_stringbool, default True: Passed through.

Returns:

set of str

supported(databases)[source]#

Narrow a list of databases to the ones this cursor can serve.

Parameters:

databaseslist of str or None: Databases asked for, or None for every database.

Returns:

list of str or None: None is passed through, meaning every database this cursor has.

unsupported(databases)[source]#

Pick the databases this cursor cannot answer for.

Parameters:

databaseslist of str or None: Databases asked for, or None for every database.

Returns:

list of str: Empty when the cursor supports them all, or cannot say.

CHECKSUM = 'CRC64'#: Database of sequence checksums in idmapping.dat. A sequence is looked up by its checksum, which is what makes an identical sequence findable whatever it has been called.

UNIPROTKB = 'UniProtKB-AC'#: Name standing for a UniProtKB accession where a database name is expected. It is not a row of the mapping table but its join key, so both ends accept it and mean the accession itself.

property checksums#

What the sequences given so far were called.

A result names a sequence by its checksum, since that is what the data holds. This says which of the sequences handed in carried it.

Returns:

pandas.DataFrame: Columns source and sequence, ready to be merged onto a result by its source column.

property columns#

Column names of the mapping dataframe.

Returns:

list of str