anyvar.storage.base

Provide PostgreSQL-based storage implementation.

class anyvar.storage.base.AlleleSearchPage(items, next_cursor)

Return object for implementing keyset pagination in allele search

Used in accordance with GA4GH pagination guidelines – https://github.com/ga4gh/TASC/blob/main/recommendations/API%20pagination%20guide.md#token-based-pagination

__init__(items, next_cursor)

items: list[Allele]

next_cursor: str | None

exception anyvar.storage.base.DataIntegrityError

Raise for attempts to delete objects depended upon by other objects

exception anyvar.storage.base.IncompleteVrsObjectError

Raise if provided VRS object is missing fully-materialized properties required for storage

exception anyvar.storage.base.InvalidSearchParamsError

Raise if search params violate specified logical constraints

exception anyvar.storage.base.MissingVariationReferenceError

Raise for attempts to insert an extension or mapping that references a non-existent variation

class anyvar.storage.base.Storage(*args, **kwargs)

Abstract base class for interacting with storage backends.

abstractmethod __init__(*args, **kwargs)

Initialize the storage backend.

abstractmethod add_ca_catvar(ca)

Add a Canonical Allele Categorical Variant

This method is not responsible for validating that the provided catvar meets data requirements to be considered a Canonical Allele instance; passing an object without prior validation may raise unexpected errors

Parameters:

ca (CanonicalAllele) – canonical allele catvar

Return type:

None

abstractmethod add_extension(extension)

Adds an extension to the database.

Adding the same extension repeatedly creates redundant records.

Parameters:

extension (Extension) – The extension to add

Raises:

MissingVariationReferenceError – if no object corresponding to the extension’s object ID is present in DB

Return type:

None

abstractmethod add_mapping(mapping)

Add a mapping between two objects.

If the mapping instance already exists, do nothing.

Parameters:

mapping (VariationMapping) – mapping object

Raises:

MissingVariationReferenceError – if source or destination IDs aren’t present in DB

Return type:

None

abstractmethod add_objects(objects)

Add multiple VRS objects to storage.

If an object ID conflicts with an existing object, skip it.

This method assumes that for VRS objects (e.g. Allele, SequenceLocation, SequenceReference) the .id property is present and uses the correct GA4GH identifier for that object. It also assumes that contained objects are similarly properly identified and materialized in full, not just as an IRI reference. An error is raised if these assumptions are violated, rolling back the entire transaction.

Parameters:

objects (Iterable[Allele | SequenceLocation | SequenceReference]) – VRS objects to add to storage

Raises:

IncompleteVrsObjectError – if object is missing required properties or if required properties aren’t fully dereferenced

Return type:

None

abstractmethod add_psq_catvar(psq)

Add a Protein Sequence Consequence Categorical Variant

This method is not responsible for validating that the provided catvar meets data requirements to be considered a Protein Sequence Consequence instance; passing an object without prior validation may raise unexpected errors

Parameters:

psq (ProteinSequenceConsequence) – protein sequence consequence catvar

Return type:

None

abstractmethod close()

Close the storage backend.

Return type:

None

abstractmethod delete_extensions(object_id, name=None, value=None)

Delete extension(s) for an object

Supports gradual specificity – either delete all extensions, or delete all extensions under a given key/name, or delete all extensions with a given name AND value.

Parameters:

• object_id (str) – The object ID

• name (str | None) – Optional extension key/name to delete

• value (Optional[TypeAliasType]) – Optional extension value to delete. Ignored if name is not provided

Return type:

int

Returns:

Number of deleted rows

abstractmethod delete_mapping(mapping)

Delete a mapping between two objects.

• If no such mapping exists in the DB, does nothing.

• Deletes do not cascade.

Parameters:

mapping (VariationMapping) – mapping object

Raises:

DataIntegrityError – if attempting to delete an object which is depended upon by another object

Return type:

None

abstractmethod delete_objects(object_type, object_ids)

Delete all objects of a specific type from storage.

• If no object matching a given ID is found, it’s ignored.

• Deletes do not cascade.

Parameters:

• object_type (type[Allele | SequenceLocation | SequenceReference]) – type of objects to delete

• object_ids (Iterable[str]) – IDs of objects to delete

Raises:

DataIntegrityError – if attempting to delete an object which is depended upon by another object

Return type:

None

abstractmethod get_ca_catvar(ca_id)

Fetch a Canonical Allele categorical variant by ID

Performs exact match – case sensitive

Parameters:

ca_id (str) – requested object ID

Return type:

CanonicalAllele | None

Returns:

matching canonical allele, if found

abstractmethod get_catvars_by_allele_ids(allele_ids)

Return categorical variants connected to the given alleles.

Retrieves every registered CanonicalAllele and ProteinSequenceConsequence whose defining allele is either one of the given alleles or is transitively connected to one through variation mappings. Mappings are traversed in both directions, regardless of their stored source and destination orientation.

If no matching categorical variants exist, an empty list is returned.

Parameters:

allele_ids (list[str]) – VRS identifiers of alleles.

Return type:

list[CanonicalAllele | ProteinSequenceConsequence]

Returns:

Connected canonical allele and protein sequence consequence categorical variants.

abstractmethod get_extensions(object_id, extension_name=None)

Get all extensions for the specified object, optionally filtered by type.

Parameters:

• object_id (str) – The ID of the object to retrieve extensions for

• extension_type – The type of extension to retrieve (defaults to None to retrieve all extensions for the object)

Return type:

list[Extension]

Returns:

A list of extensions

abstractmethod get_mappings(object_id, as_source, mapping_type=None)

Return an iterable of mappings

Optionally provide a type to filter results.

Parameters:

• object_id (str) – ID of object to get mappings for

• as_source (bool) – If True, object_id is treated as the source. If False, object_id is treated as the destination.

• mapping_type (VariationMappingType | None) – The type of mapping to retrieve (defaults to None to retrieve all mappings for the source ID)

Return type:

Iterable[VariationMapping]

Returns:

iterable collection of mapping descriptors (empty if no matching mappings exist)

abstractmethod get_objects(object_type, object_ids)

Retrieve multiple VRS objects from storage by their IDs.

If no object matches a given ID, that ID is skipped

Parameters:

• object_type (type[Allele | SequenceLocation | SequenceReference]) – type of object to get

• object_ids (Iterable[str]) – IDs of objects to fetch

Return type:

Iterable[Allele | SequenceLocation | SequenceReference]

Returns:

iterable collection of VRS objects matching given IDs

abstractmethod get_psq_catvar(psq_id)

Fetch a Protein Sequence Consequence categorical variant by ID

Performs exact match – case sensitive

Parameters:

psq_id (str) – requested object ID

Return type:

ProteinSequenceConsequence | None

Returns:

matching canonical allele, if found

abstractmethod search_alleles(refget_accession, start, stop, page_size=1000, cursor=None)

Find all Alleles that are located within the specified interval.

The interval is the closed range [start, stop] on the sequence identified by the RefGet SequenceReference accession (SQ.*). Both start and stop are inclusive and represent inter-residue positions.

Uses keyset pagination, meaning that altering the page size while looping through successive cursors will effectively nullify the search loop.

Currently, any variation which overlaps the queried region is returned.

Todo (see Issue #338): * define alternate match modes (partial/full overlap/contained/etc) * define behavior for LSE indels and for alternative types of state (RLEs)

Raises an error if * start or end are negative * end > start

Parameters:

• refget_accession (str) – refget accession (e.g. “SQ.IW78mgV5Cqf6M24hy52hPjyyo5tCCd86”)

• start (int) – Inclusive, inter-residue start position of the interval

• stop (int) – Inclusive, inter-residue end position of the interval

• page_size (int) – Max # of results to return

• cursor (str | None) – Opaque key indicating start location for query in pagination

Return type:

AlleleSearchPage

Returns:

Results page including variants and a cursor for next result page, if available

Raises:

InvalidSearchParamsError – if above search param requirements are violated

abstractmethod wait_for_writes()

Wait for all background writes to complete.

NOTE: This is a no-op for synchronous storage backends.

Return type:

None

abstractmethod wipe_db()

Wipe all data from the storage backend.

Return type:

None

exception anyvar.storage.base.StorageError

Base AnyVar storage error.