Skip to content

VCF annotation

Annotate VCFs with VRS identifiers and attributes.

The main processing path is::

annotate(...)
+ for each record: _get_vrs_data(...)
  + for each allele: _get_vrs_object(...)
    + AlleleTranslator.from_gnomad(...)
    + on_vrs_object(...)             # return an allele or None
+ on_vrs_object_collection(...)       # when collection is enabled

For example, keep only alleles with literal states::

from pathlib import Path
from ga4gh.vrs.extras.annotator.vcf import VcfAnnotator
from ga4gh.vrs.models import Allele, LiteralSequenceExpression


class LiteralStateAnnotator(VcfAnnotator):
    def on_vrs_object(
        self, vcf_coords: str, vrs_allele: Allele, **kwargs: object
    ) -> Allele | None:
        if isinstance(vrs_allele.state, LiteralSequenceExpression):
            return vrs_allele
        return None


# data_proxy must serve the input VCF's reference assembly.
LiteralStateAnnotator(data_proxy).annotate(
    Path("input.vcf"), output_ndjson_path=Path("literal-alleles.ndjson")
)

A pickle or NDJSON output enables VcfAnnotator's collection hook. Returning None excludes the allele from collection. If writing a VCF, its record remains with missing annotation values. Per-record errors are logged and written to VRS_Error.

VcfAnnotatorError

Bases: Exception

Custom exceptions for VCF Annotator tool

VcfAnnotatorArgsError

Bases: VcfAnnotatorError

Raise for improper args passed to VCF annotator

FieldName

Bases: str, Enum

Define VCF field names for VRS annotations

AbstractVcfAnnotator

AbstractVcfAnnotator(
    data_proxy: _DataProxy, **kwargs: object
)

Bases: ABC

Abstract class for VCF annotation with VRS.

Child classes must implement all abstract methods, though some may be less relevant and can just be stubbed out (for example, if the desired side effect for each VRS object is something like a REST request, there may be no need for extra cleanup in on_vrs_object_collection).

Critically, implementations that intend to do something with all VRS objects at once following ingestion (e.g. writing a PKL dump) need to set the class variable collect_alleles to True.

Initialize the VCFAnnotator class.

Parameters:

Name Type Description Default
data_proxy _DataProxy

GA4GH sequence dataproxy instance.

required
kwargs object

Additional options passed to the implementation.

{}

should_collect_alleles

should_collect_alleles(**kwargs: object) -> bool

Determine whether allele aggregation is necessary.

This method is called to initialize (or not) an initial allele collection for downstream use. By default, it returns the corresponding class variable, but implementing classes can choose to amend this based on provided annotation arguments.

Parameters:

Name Type Description Default
kwargs object

Additional options passed to the implementation.

{}

Returns:

Type Description
bool

True if alleles should be collected

raise_for_output_args abstractmethod

raise_for_output_args(
    output_vcf_path: Path | Literal["-"] | None,
    **kwargs: object,
) -> None

Raise an exception if no output appears to be configured or declared.

Child classes should implement this to ensure that any other outputs are checked on top of an annotated VCF output.

Parameters:

Name Type Description Default
output_vcf_path Path | Literal['-'] | None

Optional annotated VCF output path.

required
kwargs object

Additional options passed to the implementation.

{}

Raises:

Type Description
VcfAnnotatorError

if no output args are shown

annotate

annotate(
    input_vcf_path: Path | Literal["-"],
    output_vcf_path: Path | Literal["-"] | None = None,
    vrs_attributes: bool = False,
    assembly: str = "GRCh38",
    compute_for_ref: bool = True,
    require_validation: bool = True,
    **kwargs: object,
) -> None

Given a VCF, produce an output VCF annotated with VRS allele IDs, and/or additional storage outputs as implemented in a specific child class.

Parameters:

Name Type Description Default
input_vcf_path Path | Literal['-']

Location of input VCF (or "-" to read from stdin)

required
output_vcf_path Path | Literal['-'] | None

The path for the output VCF file (or "-" to write to stdout)

None
vrs_attributes bool

If True, include VRS_Start, VRS_End, VRS_State properties in the VCF INFO field. If False will not include these properties. Only used if output_vcf_path is defined.

False
assembly str

The assembly used in input_vcf_path data

'GRCh38'
compute_for_ref bool

If true, compute VRS IDs for the reference allele

True
require_validation bool

If True, validation checks (i.e., REF value matches expected REF at given location) must pass in order to return a VRS object for a record. False permits reference mismatches, which are logged as warnings; location bounds are still validated. Per-record errors are logged and written to VRS_Error when VCF output is enabled.

True
kwargs object

Additional options passed to the implementation.

{}

Raises:

Type Description
VcfAnnotatorError

if no output formats are selected

on_vrs_object abstractmethod

on_vrs_object(
    vcf_coords: str, vrs_allele: Allele, **kwargs: object
) -> Allele | None

Perform side-effects (eg additional annotation or storage) or additional filtering on VRS alleles as they are constructed during VCF annotation.

Implementations return the retained allele or None to discard it. The abstract method itself performs no processing.

Parameters:

Name Type Description Default
vcf_coords str

CHR-POS-REF-ALT from VCF for this allele

required
vrs_allele Allele

allele translated from coords

required
kwargs object

Additional options passed to the implementation.

{}

Returns:

Type Description
Allele | None

Final allele, or None to filter it from collection.

on_vrs_object_collection abstractmethod

on_vrs_object_collection(
    vrs_alleles_collection: list[Allele] | None,
    **kwargs: object,
) -> None

Perform clean-up operations (eg file writing) on VRS objects collected during VCF ingestion.

Reimplement in a child class to add custom logic. Otherwise, this method does nothing.

Parameters:

Name Type Description Default
vrs_alleles_collection list[Allele] | None

VRS alleles constructed from ingested VCF

required
kwargs object

Additional options passed to the implementation.

{}

VcfAnnotator

VcfAnnotator(data_proxy: _DataProxy, **kwargs: object)

Bases: AbstractVcfAnnotator

Annotate VCFs with VRS allele IDs.

Uses pysam to ingest a VCF and produce a copy annotated with VRS IDs (and, optionally, normalized allele attributes). Alleles are translated using the VRS-Python translator class.

should_collect_alleles

should_collect_alleles(**kwargs: object) -> bool

Inhibit allele collection parameter if no means of output are given.

Parameters:

Name Type Description Default
kwargs object

Optional output_pkl_path and output_ndjson_path destinations.

{}

Returns:

Type Description
bool

True if at least one output path is truthy

annotate

annotate(
    input_vcf_path: Path | Literal["-"],
    output_vcf_path: Path | Literal["-"] | None = None,
    vrs_attributes: bool = False,
    assembly: str = "GRCh38",
    compute_for_ref: bool = True,
    require_validation: bool = True,
    **kwargs: object,
) -> None

Given a VCF, produce an output VCF annotated with VRS allele IDs, and/or a PKL or NDJSON dump of the corresponding VRS objects.

Parameters:

Name Type Description Default
input_vcf_path Path | Literal['-']

Location of input VCF

required
output_vcf_path Path | Literal['-'] | None

The path for the output VCF file

None
vrs_attributes bool

If True, include VRS_Start, VRS_End, VRS_State properties in the VCF INFO field. If False will not include these properties. Only used if output_vcf_path is defined.

False
assembly str

The assembly used in input_vcf_path data

'GRCh38'
compute_for_ref bool

If true, compute VRS IDs for the reference allele

True
require_validation bool

If True, validation checks (i.e., REF value matches expected REF at given location) must pass in order to return a VRS object for a record. False permits reference mismatches, which are logged as warnings; location bounds are still validated. Per-record errors are logged and written to VRS_Error when VCF output is enabled.

True
kwargs object

Optional output_pkl_path and output_ndjson_path destinations.

{}

Raises:

Type Description
VcfAnnotatorError

if no output formats are selected

raise_for_output_args

raise_for_output_args(
    output_vcf_path: Path | Literal["-"] | None,
    **kwargs: object,
) -> None

Raise an exception if no output (VCF, PKL, NDJSON) appears to be configured or declared.

Parameters:

Name Type Description Default
output_vcf_path Path | Literal['-'] | None

VCF output path arg passed to annotate()

required
kwargs object

Optional output_pkl_path and output_ndjson_path destinations.

{}

Raises:

Type Description
VcfAnnotatorArgsError

if no output args are given

on_vrs_object

on_vrs_object(
    vcf_coords: str, vrs_allele: Allele, **kwargs: object
) -> Allele | None

Perform side-effects (eg additional annotation or storage) or additional filtering on VRS alleles as they are constructed during VCF annotation.

For this basic implementation, no additional operations are performed.

Parameters:

Name Type Description Default
vcf_coords str

CHR-POS-REF-ALT from VCF for this allele

required
vrs_allele Allele

allele translated from coords

required
kwargs object

Optional output_pkl_path and output_ndjson_path destinations.

{}

Returns:

Type Description
Allele | None

Final allele, or None to filter it from collection.

on_vrs_object_collection

on_vrs_object_collection(
    vrs_alleles_collection: list[Allele] | None,
    **kwargs: object,
) -> None

Perform clean-up operations (eg file writing) on VRS objects collected during VCF ingestion.

Parameters:

Name Type Description Default
vrs_alleles_collection list[Allele] | None

VRS alleles constructed from ingested VCF

required
kwargs object

Optional output_pkl_path and output_ndjson_path destinations.

{}

dump_alleles_to_pkl

dump_alleles_to_pkl(
    alleles: list[Allele], output_pkl_path: Path
) -> None

Create pkl file of dictionary mapping VRS IDs to ingested alleles.

Parameters:

Name Type Description Default
alleles list[Allele]

all alleles constructed + annotated during VCF ingestion

required
output_pkl_path Path

location to save PKL file to

required

dump_alleles_to_ndjson

dump_alleles_to_ndjson(
    allele_collection: list[Allele],
    output_ndjson_path: Path,
) -> None

Create NDJSON dump of all alleles ingested from VCF

Parameters:

Name Type Description Default
output_ndjson_path Path

location to save NDJSON file to

required
allele_collection list[Allele]

Alleles to write.

required