VCF Parser

granite library can be used directly to access and manipulate information in VCF format.

Import the library

from granite.lib import vcf_parser

Usage

The library implements the objects Vcf, Header and Variant.

Vcf

This is the main object and has methods to read and write VCF format.

Initialize the object

vcf_obj = vcf_parser.Vcf('inputfile.vcf')

This will automatically read the file header into a Header object.

Read and access variants

The method parse_variants() will read the file and return a generator to Variant objects that store variants information.

for vnt_obj in vcf_obj.parse_variants():
    ...

Write to file

The method write_header(fo) writes header definitions and columns to specified buffer (fo).

with open('outputfile.vcf', 'w') as fo:
    vcf_obj.write_header(fo)

It is possible to write only definitions or columns respectively with the methods write_definitions(fo) and write_columns(fo).

with open('outputfile.vcf', 'w') as fo:
    vcf_obj.write_definitions(fo)
    vcf_obj.write_columns(fo)

The method write_variant(fo, Variant_obj) writes information from Variant object to specified buffer (fo).

with open('outputfile.vcf', 'w') as fo:
    vcf_obj.write_variant(fo, vnt_obj)

Header

This is the object used to store information for the header in VCF format. Methods are available to extract and modify information in the header.

Attributes

definitions <str>

Stores the full header information minus the last line where columns are defined.

vcf_obj.header.definitions

columns <str>

Stores the last header line where columns are defined.

# Columns example
# #CHROM    POS    ID    REF    ALT    ...

vcf_obj.header.columns

IDs_genotypes <list>

Stores sample ID(s) available in the VCF as list. If multiple samples, the order from the VCF is maintained.

vcf_obj.header.IDs_genotypes

Add or remove definitions

The method add_tag_definition(tag_definition, tag_type=’INFO’) adds tag_definition to the header on top of the block specified by tag_type (e.g. FORMAT, INFO).

tag_definition = '##INFO=<ID=tag,Number=.,Type=.,Description="INFO tag definition example">'
vcf_obj.header.add_tag_definition(tag_definition)

The method remove_tag_definition(tag, tag_type=’INFO’) removes tag definition from the header block specified by tag_type (e.g. FORMAT, INFO).

tag = 'CSQ'
vcf_obj.header.remove_tag_definition(tag)

Extract information

The method get_tag_field_idx(tag, field, tag_type=’INFO’, sep=’|’) gets the index corresponding to value field in tag from definition, block specified by tag_type (e.g. FORMAT, INFO). sep is the fields separator used in the tag definition.

# Return the index corresponding to 'Consequence' field
# from CSQ definition (VEP) in the header INFO block
# ##INFO=<ID=CSQ,Number=.,Type=String,Description="Consequence annotations from Ensembl VEP. Format: Gene|Feature|Consequence|IMPACT|...">

tag, field = 'CSQ', 'Consequence'
idx <int> = vcf_obj.header.get_tag_field_idx(tag, field)

The method check_tag_definition(tag, tag_type=’INFO’, sep=’|’) checks if a tag is in the header and if it is standalone or a field of another leading tag. Returns the leading tag and the field corresponding index, if any, to access the tag. sep is the fields separator used in the tag definition.

# Return the leading tag and index corresponding to 'Consequence' field
# from CSQ definition (VEP) in the header INFO block
# ##INFO=<ID=CSQ,Number=.,Type=String,Description="Consequence annotations from Ensembl VEP. Format: Gene|Feature|Consequence|IMPACT|...">

tag = 'Consequence'
lead_tag <str>, idx <int> = vcf_obj.header.check_tag_definition(tag)

note: tag and field are case sensitive.

Variant

This is the object used to store information for variants in VCF format.

Attributes

CHROM <str>

Stores chromosome name (e.g. 1, chr1), as in the VCF file.

vnt_obj.CHROM

POS <int>

Stores variant position.

vnt_obj.POS

ID <str>

Stores variant ID(s), as in the VCF file.

vnt_obj.ID

REF <str>

Stores reference allele at position.

vnt_obj.REF

ALT <str>

Stores alternate allele(s) at position.

vnt_obj.ALT

QUAL <str>

Stores phred-scaled quality score for the assertion made in ALT.

vnt_obj.QUAL

FILTER <str>

Stores filter status.

vnt_obj.FILTER

INFO <str>

Additional information for the variant.

vnt_obj.INFO

FORMAT <str>

Stores specification for the genotype column(s) structure.

vnt_obj.FORMAT

IDs_genotypes <list>

Stores sample ID(s) available in the VCF as list. If multiple samples, the order from the VCF is maintained.

vnt_obj.IDs_genotypes

GENOTYPES <dict>

Stores a dictionary linking genotype(s) for the variant to corresponding sample ID(s).

# {ID_genotype: genotype, ...}
vnt_obj.GENOTYPES

Format variants

The method to_string() returns the variant representation in VCF format.

vnt_vcf <str> = vnt_obj.to_string()

The method repr() returns the variant representation in the form CHROM:POSREF>ALT.

vnt_repr <str> = vnt_obj.repr()

Manipulate genotype(s)

The method remove_tag_genotype(tag, sep=’:’) removes a tag from FORMAT and GENOTYPES. sep is the tags separator used in format definition and genotype(s).

tag = 'AD'
vnt_obj.remove_tag_genotype(tag)

The method complete_genotype(sep=’:’) fills in the trailing fields that are missing and by default dropped in GENOTYPES. sep is the tags separator used in format definition and genotype(s).

vnt_obj.complete_genotype()

The method empty_genotype(sep=’:’) returns an empty genotype based on the FORMAT structure. sep is the tags separator used in format definition and genotype(s).

empty <str> = vnt_obj.empty_genotype()

The method add_tag_format(tag, sep=’:’) adds a tag at the end of FORMAT structure. sep is the tags separator used in format definition and genotype(s).

tag = 'RSTR'
vnt_obj.add_tag_format(tag)

The method add_values_genotype(ID_genotype, values, sep=’:’) adds values at the end of the genotype specified by corresponding ID. sep is the tags separator used in format definition and genotype(s).

vnt_obj.add_values_genotype(ID_genotype, values)

The method get_genotype_value(ID_genotype, tag, complete_genotype=False, sep=’:’) returns value for tag from the genotype specified by corresponding ID. sep is the tags separator used in format definition and genotype(s).

If complete_genotype=True, it returns ‘.’ if tag is missing. If complete_genotype=False (default), it raises an exception for the missing tag.

tag_val <str> = vnt_obj.get_genotype_value(ID_genotype, tag)

Manipulate INFO

The method remove_tag_info(tag, sep=’;’) removes a tag or a flag from INFO. sep is the tags separator used in INFO.

vnt_obj.remove_tag_info(tag)

The method add_tag_info(tag_value, sep=’;’) adds a tag and its value or a flag at the end of INFO. sep is the tags separator used in INFO.

tag_value = 'tag=value'
vnt_obj.add_tag_info(tag_value)

tag_value = 'flag'
vnt_obj.add_tag_info(tag_value)

The method get_tag_value(tag, is_flag=False, sep=’;’) returns the value from tag in INFO. sep is the tags separator used in INFO.

If the tag is a flag, set is_flag=True; the function will return True or False instead.

tag_val <str> = vnt_obj.get_tag_value(tag)

tag_val <bool> = vnt_obj.get_tag_value(tag, is_flag=True)

note: tag and ID are case sensitive.

Custom error classes

MissingTag describes a missing tag or tag value.

MissingTagDefinition describes a missing tag definition.

TagDefinitionError describes a format error for a tag definition.

TagFormatError describes a format error for a tag.

MissingIdentifier describes a missing genotype identifier in the VCF file.

VcfFormatError describes an error in the VCF format.