Data proxies
provides an abstract class for all data access required for VRS, and a concrete implementation based on seqrepo.
See https://vr-spec.readthedocs.io/en/1.1/impl-guide/required_data.html
DataProxyValidationError
Bases: Exception
Class for validation errors during data proxy methods
SeqRepoDataProxy
Bases: _SeqRepoDataProxyBase
DataProxy based on a local instance of SeqRepo
Initialize DataProxy instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sr
|
SeqRepo
|
SeqRepo instance |
required |
SeqRepoRESTDataProxy
Bases: _SeqRepoDataProxyBase
DataProxy based on a REST instance of SeqRepo, as provided by seqrepo-rest-services
Initialize REST-based dataproxy instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_url
|
str
|
root URL to server |
required |
disable_healthcheck
|
bool
|
Whether healthcheck should be disabled |
False
|
Raises:
| Type | Description |
|---|---|
requests.RequestException
|
If the enabled health check fails. |
SequenceProxy
SequenceProxy(dp: _DataProxy, alias: str)
Bases: Sequence[str]
Fetch sequence characters and contiguous slices through a data proxy.
Slice steps and reversed iteration are unsupported. Coordinates are passed to the backend without Python-style negative-index normalization.
Initialize the sequence proxy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dp
|
_DataProxy
|
Sequence data proxy. |
required |
alias
|
str
|
Sequence accession or alias. |
required |
__str__
Fetch the complete sequence.
Returns:
| Type | Description |
|---|---|
str
|
Complete sequence. |
__reversed__
Reject reversed iteration.
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
Reversed iteration is unsupported. |
__getitem__
Return sequence for key (slice), fetching if necessary
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
int | slice
|
Integer position or contiguous slice. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Sequence at the requested position or slice. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the slice specifies any step, including 1. |
validate_start_le_end
Reject an interval whose start is after its end, since vrs-python treats every sequence as linear.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
identifier
|
str
|
Sequence identifier to resolve. |
required |
start
|
int | None
|
Zero-based inclusive start, or None for the sequence start. |
required |
end
|
int | None
|
Zero-based exclusive end, or None for the sequence end. |
required |
Raises:
| Type | Description |
|---|---|
DataProxyValidationError
|
If both are defined and |
create_dataproxy
create_dataproxy(
uri: str | None = None,
disable_healthcheck: bool = False,
) -> _DataProxy
Create a dataproxy from uri or GA4GH_VRS_DATAPROXY_URI
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
uri
|
str | None
|
Dataproxy URI, or None to read GA4GH_VRS_DATAPROXY_URI. No default server is assumed. Currently accepted URI schemes:
|
None
|
disable_healthcheck
|
bool
|
Whether healthcheck should be disabled in REST dataproxy |
False
|
Returns:
| Type | Description |
|---|---|
_DataProxy
|
Data proxy for the requested provider. |
Raises:
| Type | Description |
|---|---|
ValueError
|
if no URI is configured or the URI does not match recognized schemes, e.g. is missing provider
prefix ( |
Data proxy interface
The data proxy interface defines sequence retrieval, alias translation, and validation.
Bases: ABC
abstract class / interface for VRS data needs
The proxy MUST support the use of GA4GH sequence identifers (i.e., ga4gh:SQ...) as
keys, and return these identifiers among the aliases for a sequence. These
identifiers may be supported natively by the data source or synthesized by the proxy
from the data source or synthesized.
get_sequence
abstractmethod
Return the specified sequence or subsequence
start and end are optional
If the given sequence does not exist, KeyError is raised. If start is after end, DataProxyValidationError may be raised.
For example:
>>> dp.get_sequence("NM_000551.3", 0, 10)
'CCTCGCCTCC'
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
identifier
|
str
|
Sequence identifier to resolve. |
required |
start
|
int | None
|
Zero-based inclusive start, or None for the sequence start. |
None
|
end
|
int | None
|
Zero-based exclusive end, or None for the sequence end. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
Requested sequence or subsequence. |
Raises:
| Type | Description |
|---|---|
KeyError
|
If the sequence identifier is not found. |
DataProxyValidationError
|
If start exceeds end. |
get_metadata
abstractmethod
For a given identifier, return a structure (dict) containing sequence length, aliases, and other optional info
If the given sequence does not exist, KeyError is raised.
For example:
>>> dp.get_metadata("NM_000551.3")
{'added': '2016-08-24T05:03:11Z',
'aliases': ['MD5:215137b1973c1a5afcf86be7d999574a',
'RefSeq:NM_000551.3',
'SEGUID:T12L0p2X5E8DbnL0+SwI4Wc1S6g',
'SHA1:4f5d8bd29d97e44f036e72f4f92c08e167354ba8',
'ga4gh:SQ.v_QTc1p-MUYdgrRv4LMT6ByXIOsdw3C_',
'gi:319655736'],
'alphabet': 'ACGT',
'length': 4560}
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
identifier
|
str
|
Sequence identifier to resolve. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Sequence metadata, including length and aliases. |
Raises:
| Type | Description |
|---|---|
KeyError
|
If the sequence identifier is not found. |
extract_sequence_type
staticmethod
Infer the HGVS sequence type from a recognized accession prefix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
alias
|
str
|
Sequence accession or alias. |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
HGVS sequence type, or None for an unknown prefix. |
translate_sequence_identifier
cached
Translate given identifier to a list of identifiers in the specified namespace.
identifier must be a string namespace is case-sensitive
On success, returns a list of matching identifiers. Raises KeyError if given identifier isn't found.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
identifier
|
str
|
Sequence identifier to resolve. |
required |
namespace
|
str | None
|
Optional namespace used to filter sequence aliases. |
None
|
Returns:
| Type | Description |
|---|---|
list[str]
|
Distinct matching sequence aliases. |
Raises:
| Type | Description |
|---|---|
KeyError
|
If the sequence identifier is not found. |
derive_refget_accession
Derive the refget accession from a public accession identifier
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ac
|
str | None
|
public accession in simple or curie form from which to derive the refget accession |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
Refget accession, or None for a missing input or unresolved alias. |
validate_ref_seq
validate_ref_seq(
sequence_id: str,
start_pos: int,
end_pos: int,
ref: str,
require_validation: bool = True,
) -> None
Validate the expected reference sequence against the data proxy.
Reference mismatches are logged as warnings. With require_validation=True, they also raise DataProxyValidationError. Invalid location bounds always raise.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sequence_id
|
str
|
Sequence ID to use |
required |
start_pos
|
int
|
Start pos (inter-residue) on the sequence_id |
required |
end_pos
|
int
|
End pos (inter-residue) on the sequence_id |
required |
ref
|
str
|
The expected reference sequence on the sequence_id given the start_pos and end_pos |
required |
require_validation
|
bool
|
If |
True
|
Raises:
| Type | Description |
|---|---|
DataProxyValidationError
|
If expected reference sequence does not match
the actual reference sequence and |
validate_location_bounds
validate_location_bounds(
sequence_id: str,
start_pos: int | Range | None,
end_pos: int | Range | None,
) -> None
Ensure that start_pos and end_pos are representable on sequence_id.
Each defined coordinate must be within [0, len(sequence)] (inter-residue).
Undefined (None) endpoints are skipped, and for a Range every defined
member is checked.
start_pos must also not be after end_pos, comparing a Range by its
lowest possible start and highest possible end.
There is no require_validation option: an out-of-bounds location has no
meaning, so the error is always raised, including from validate_ref_seq.
Sequence backends may silently truncate out-of-range fetches, so this check must
be made before relying on fetched sequence.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sequence_id
|
str
|
Sequence ID to use |
required |
start_pos
|
int | Range | None
|
Start pos (inter-residue) on the sequence_id |
required |
end_pos
|
int | Range | None
|
End pos (inter-residue) on the sequence_id |
required |
Raises:
| Type | Description |
|---|---|
DataProxyValidationError
|
If a defined coordinate is out of bounds, or
|
KeyError
|
If |