GA4GH Cat-VRS

0.7.2 verified Sat May 09 auth: no python

GA4GH Categorical Variation Representation (Cat-VRS) reference implementation. Current version 0.7.2 (stable), with 0.8.0-alpha1 available. The library provides Python models and utilities for representing categorical (e.g., clinical significance) variants aligned with VRS. Release cadence is irregular, with several milestone releases in 2025-2026.

pip install ga4gh-cat-vrs

Common errors

error ImportError: cannot import name 'CategoricalVariant' from 'cat_vrs' ↓

cause Incorrect import path: the package is ga4gh.cat_vrs, not cat_vrs.

fix

Use: from ga4gh.cat_vrs.models import CategoricalVariant

error pydantic_core._pydantic_core.ValidationError: 1 validation error for CategoricalVariant type unexpected value; permitted: 'CategoricalVariant' ↓

cause The 'type' field must be exactly 'CategoricalVariant' (string). The default might be missing in older versions.

fix

Explicitly set type='CategoricalVariant' when constructing CategoricalVariant.

error AttributeError: 'CategoricalVariant' object has no attribute 'copy' ↓

cause Pydantic V2 removed the copy() method. In ga4gh-cat-vrs >=0.6.0, use model_copy().

fix

Replace .copy() with .model_copy() (Pydantic V2 pattern).

Warnings

breaking In v0.5.0, recipe classes no longer inherit from CategoricalVariant. Code that relied on inheritance may break when upgrading from v0.4.x. ↓

fix Update to v0.6.0+ where the inheritance was restored, or adjust code to not use recipe classes as CategoricalVariant subclasses.

breaking v0.7.0 updated to Cat-VRS models 1.0.0 with breaking changes to model structure. Pydantic V2 is required. ↓

fix Ensure your code uses Pydantic V2 patterns. Use model_copy() instead of copy() and model_dump() instead of dict().

breaking v0.8.0-alpha moves to Cat-VRS 1.1.0-snapshot and may change model fields. The pre-release uses ga4gh.vrs ~=2.4.0a1. ↓

fix Pin to stable 0.7.x if you need production stability. Test your code against the alpha before upgrading.

deprecated The 'copy' method from Pydantic V1 is deprecated in favor of 'model_copy' in v0.6.0+. ↓

fix Replace instance.copy() with instance.model_copy() and supply arguments as keyword args.

Install

pip install ga4gh-cat-vrs==0.8.0a1

Imports

CategoricalVariant

wrong

from cat_vrs.models import CategoricalVariant

correct

from ga4gh.cat_vrs.models import CategoricalVariant

Package name uses underscores and 'ga4gh' prefix

ClinicalInterpretation
```
from ga4gh.cat_vrs.models import ClinicalInterpretation
```
Some recipes classes do not inherit from CategoricalVariant in v0.5.0+

Quickstart

Instantiate a CategoricalVariant with an Allele and a ClinicalInterpretation member.

from ga4gh.cat_vrs.models import CategoricalVariant, ClinicalInterpretation
from ga4gh.vrs.models import Allele

# Create a categorical variant with a simple allele
allele = Allele(
    location="ga4gh:VSLoc:someLocation",
    state="ga4gh:VSEXP:someExpression"
)
cv = CategoricalVariant(
    allele=allele,
    context="ga4gh:VS:someContext",
    type="CategoricalVariant",
    member=[ClinicalInterpretation(label="pathogenic", id="clinvar:12345")]
)
print(cv.model_dump())