GA4GH Variation Representation Specification (VRS) Python

2.3.1 verified Sat May 09 auth: no python

GA4GH Variation Representation Specification (VRS) reference implementation in Python. Provides data models, validation, and conversion tools for representing genetic variation in a standardized manner. Current stable version is 2.3.1 (Python >=3.10). Pre-releases track VRS 2.1.0 snapshots. Released semi-regularly with bug fixes and feature updates.

pip install ga4gh-vrs

Common errors

error ModuleNotFoundError: No module named 'ga4gh.vrs' ↓

cause Package not installed or installed with wrong name (e.g., 'vrs' instead of 'ga4gh-vrs').

fix

Run 'pip install ga4gh-vrs' and ensure you have Python >=3.10.

error ImportError: cannot import name 'Allele' from 'ga4gh.vrs' ↓

cause The Allele class is no longer directly in ga4gh.vrs; it moved to ga4gh.vrs.models.

fix

Use 'from ga4gh.vrs.models import Allele'.

error AttributeError: 'Allele' object has no attribute 'to_dict' ↓

cause Using pydantic v2 model methods incorrectly. The .dict() method is deprecated.

fix

Use .model_dump() instead of .dict(), and .model_dump_json() instead of .json().

error ga4gh.vrs.dataproxy.DataProxyException: Could not connect to SeqRepo ↓

cause The data proxy health check failed because SeqRepo service is not running or unreachable.

fix

Set disable_healthcheck=True in create_dataproxy() to skip the connection test.

Warnings

breaking Version 2.0 introduced new models (pydantic v2). Existing code using v1.x models will break. Allele, Variation, etc. must be imported from ga4gh.vrs.models. ↓

fix Update imports and migrate to pydantic v2 model_dump()/model_dump_json() instead of dict()/json().

deprecated Beacon translation function is deprecated since v2.2.0 and may be removed. ↓

fix Avoid using beacon-related translation utilities; use direct VRS models instead.

breaking In v2.3.0, the health check is removed from VCF annotator and create_dataproxy now has a disable_healthcheck keyword argument. Calling create_dataproxy without it may raise errors if the underlying service is unavailable. ↓

fix Pass disable_healthcheck=True to create_dataproxy if you don't need health checks.

gotcha The HGVS dependency changed from <1.5 to >=1.5.5,<2.0 in v2.3.0. Pinning to older hgvs breaks installation. Ensure you install with compatible version. ↓

fix Use 'pip install ga4gh-vrs' which automatically resolves the correct HGVS version.

Imports

Allele
```
from ga4gh.vrs.models import Allele
```
Primary model class for representing an allele.
VrsObject
```
from ga4gh.vrs.models import VrsObject
```
Base class for all VRS objects.
copy_to_toplevel
```
from ga4gh.vrs.extras import copy_to_toplevel
```
Utility function to copy VRS objects to top-level.
DataProxy
wrong
```
from ga4gh.vrs.dataproxy import DataProxy
```
correct
```
from ga4gh.vrs.dataproxy import create_dataproxy
```
Use create_dataproxy factory function instead of importing DataProxy directly.

Quickstart

Build a simple VRS Allele using SequenceLocation and LiteralSequenceExpression, using a SeqRepo data proxy.

from ga4gh.vrs.models import Allele
from ga4gh.vrs.dataproxy import create_dataproxy

# Create a data proxy with optional health check (set disable_healthcheck=True to skip)
dp = create_dataproxy('seqrepo', disable_healthcheck=True)

# Build an Allele object
allele = Allele(
    location={
        "type": "SequenceLocation",
        "sequence_id": "ga4gh:SQ.IIB53T8CNeJJdUqGN9Kj2b",
        "interval": {"type": "SimpleInterval", "start": 0, "end": 10}
    },
    state={
        "type": "LiteralSequenceExpression",
        "sequence": "ACGTGCATGT"
    }
)
print(allele.model_dump_json(indent=2))