rotifer.db.uniprot.BaseUniProtDelegatorCursor#

class rotifer.db.uniprot.BaseUniProtDelegatorCursor(*args, **kwargs)[source]#

Bases: MappingCursor, SequentialDelegatorCursor

Shared behaviour of the UniProt delegator cursors.

This class is not meant to be used directly. It exists so that every cursor in this package returns one dataframe, whichever backend answered: the generic delegator collects one result per backend and per batch, and this class concatenates them.

See also

rotifer.db.delegator.SequentialDelegatorCursor: the delegation logic

classmethod resolve_sqlitedb(sqlitedb)[source]#

Work out which SQLite3 file was asked for, if any.

Parameters:

sqlitedbbool, str or None: True for the default file, a path for one of your own, and None or False for no SQLite3 backend at all.

Returns:

str or None: The path, whose directory is created if it is missing so that a new file can be written there.

__getitem__(accessions, *args, **kwargs)[source]#

Fetch identifier mappings, dictionary style.

Equivalent to fetchall(), so that dictionary style access caches its results like the other two access styles.

Parameters:

accessionsstr or iterable of str: Database identifiers.

Returns:

pandas.DataFrame: The rows found by every backend consulted, concatenated. Identifiers no backend could resolve are registered in missing.

backend_arguments(name, arguments)[source]#

Give the SQLite3 backend the file rather than the mirror.

path means the root of a mirror to every other backend here and the name of a database file to this one, which is exactly the disagreement this hook exists for.

Parameters:

namestr: Which backend is being built.
argumentsdict: The shared attributes.

Returns:

dict

check_databases(databases, end)[source]#

Refuse a database name no backend knows.

A misspelled database is a mistake, not an absence, and the two must not look alike: asking for Refseq where the data says RefSeq matched nothing anywhere and returned an empty frame, which is exactly what a correctly spelled database with no mappings returns.

Only names the backends have actually enumerated are checked. Where none of them can say what they hold there is nothing to check against, and the query goes ahead.

Parameters:

databaseslist of str or None: Databases asked for at one end of the mapping.
endstr: Which end, source or target, for the message.

Raises:

ValueError: If any name is unknown to every backend that can enumerate.

Examples

>>> from rotifer.db import uniprot
>>> uniprot.MappingCursor().fetchall(['P00750'],
...                                  target=['Refseq'])
Traceback (most recent call last):
ValueError: unknown target database: 'Refseq' (did you mean 'RefSeq'?)

create(replace=False)[source]#

Create the ClickHouse database and table.

Parameters:

replacebool, default False: If True, drop an existing table before creating it. Every row it holds is lost.

Returns:

bool: Whether the table exists after the call.

Raises:

ValueError: If the ClickHouse backend is not among this delegator’s readers or writers.

Examples

>>> from rotifer.db import uniprot
>>> ic = uniprot.MappingCursor(dbname='rotifer')
>>> ic.create()

databases()[source]#

Name every database this delegator’s backends can map.

The backends hold different vocabularies – the table has the identifiers derived from a sequence, the web service has the annotation databases a curator recorded – so what the delegator can answer for is the union of theirs, not any one of them.

A backend that cannot enumerate its own vocabulary, as the mirror cannot without reading 90 GB, contributes nothing to the list. It is not thereby excluded from being asked: the list says what is known to be reachable, not what is allowed.

Returns:

set of str or None: None when no backend could name its databases, which is read as “any” and narrows nothing.

Examples

>>> from rotifer.db import uniprot
>>> sorted(uniprot.MappingCursor().databases())[:3]
['ABCD', 'AGR', 'AbasyAtlas']

databases_by_backend()[source]#

Say which backend can map which databases.

Useful for telling a database no backend has from one only the slow backend has, which the union alone cannot distinguish.

Returns:

dict: Backend name to its vocabulary, or to None where it could not name one.

fetchone(accessions, *args, **kwargs)[source]#

Iterate over identifier mappings, trying each backend in turn.

Backends listed in readers are consulted in order and each one receives only the identifiers its predecessors could not resolve. Rows are handed to the backends listed in writers, which is how cache stores what a query just retrieved.

Parameters:

accessionsstr or iterable of str: Database identifiers.

Yields:

pandas.DataFrame: One block of rows, as produced by the backend that found them.

load(source=None, release=None, method='auto', **kwargs)[source]#

Load a whole release from the mirror into ClickHouse.

The table is created when it does not exist yet, then every row of the mirror’s idmapping.dat is inserted. This is the one call that turns an empty database into one worth querying.

Parameters:

sourcestr or cursor, optional: Where to read the mappings from. Defaults to this delegator’s own mirror backend, so that the path given at construction is used.
releasestr, optional: Value stored in the release column of every row loaded. Defaults to the delegator’s release.
methodstr, default ‘auto’: How to send the data. See rotifer.db.uniprot.clickhouse.BaseMappingCursor.load().
**kwargs: Passed on to the ClickHouse backend’s load.

Returns:

int: Number of rows in the table after the load.

Raises:

ValueError: If the ClickHouse backend, or a source to read from, is missing.

Examples

Point a cursor at a mirror and an empty database, then fill it:

>>> from rotifer.db import uniprot
>>> ic = uniprot.MappingCursor(
...     local_database_path="/scratch/global/databases/uniprot",
...     dbname="rotifer", release="2026_01")
>>> ic.load()
2647104040

unsupported(databases)[source]#

Pick the databases no backend can answer for.

A backend that cannot enumerate its vocabulary might hold any of them, so while one is present nothing can be called unsupported: the union names what is known to be reachable, which is not the same as a limit.

Parameters:

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

Returns:

list of str

property store#

The backend cursor that stores data.

Returns:

object or None: The ClickHouse cursor, or None when it is not among this delegator’s backends.