Skip to content

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

SeqRepoDataProxy(sr: SeqRepo)

Bases: _SeqRepoDataProxyBase

DataProxy based on a local instance of SeqRepo

Initialize DataProxy instance.

Parameters:

Name Type Description Default
sr SeqRepo

SeqRepo instance

required

SeqRepoRESTDataProxy

SeqRepoRESTDataProxy(
    base_url: str, disable_healthcheck: bool = False
)

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__

__str__() -> str

Fetch the complete sequence.

Returns:

Type Description
str

Complete sequence.

__len__

__len__() -> int

Return the sequence length.

Returns:

Type Description
int

Sequence length.

__reversed__

__reversed__() -> NoReturn

Reject reversed iteration.

Raises:

Type Description
NotImplementedError

Reversed iteration is unsupported.

__getitem__

__getitem__(key: int | slice) -> str

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

validate_start_le_end(
    identifier: str, start: int | None, end: int | None
) -> None

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 start > end

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:

  • seqrepo+file:///path/to/seqrepo/root
  • seqrepo+:../relative/path/to/seqrepo/root
  • seqrepo+http://localhost:5000/seqrepo
  • seqrepo+https://somewhere:5000/seqrepo
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 ("seqrepo+")

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

get_sequence(
    identifier: str,
    start: int | None = None,
    end: int | None = None,
) -> str

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

get_metadata(identifier: str) -> dict

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

extract_sequence_type(alias: str) -> str | None

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_sequence_identifier(
    identifier: str, namespace: str | None = None
) -> list[str]

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_refget_accession(ac: str | None) -> str | None

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 and if validation checks fail, a DataProxyValidationError will be raised. Error message will always be logged.

True

Raises:

Type Description
DataProxyValidationError

If expected reference sequence does not match the actual reference sequence and require_validation is True. Raised regardless of require_validation if the location is invalid (see validate_location_bounds).

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 start_pos is after end_pos

KeyError

If sequence_id is not found