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
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
|
|
raise_for_output_args
abstractmethod
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 |
False
|
assembly
|
str
|
The assembly used in |
'GRCh38'
|
compute_for_ref
|
bool
|
If true, compute VRS IDs for the reference allele |
True
|
require_validation
|
bool
|
If |
True
|
kwargs
|
object
|
Additional options passed to the implementation. |
{}
|
Raises:
| Type | Description |
|---|---|
VcfAnnotatorError
|
if no output formats are selected |
on_vrs_object
abstractmethod
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
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
|
|
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 |
False
|
assembly
|
str
|
The assembly used in |
'GRCh38'
|
compute_for_ref
|
bool
|
If true, compute VRS IDs for the reference allele |
True
|
require_validation
|
bool
|
If |
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 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 |
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
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 |