VCF Info Annotator

The VCF Info Annotator adds data from a tab-delimited (TSV) file to a VCF’s INFO column. It supports annotating one or more INFO fields in a single run, and can handle any VCF-spec data type.

Usage

usage: vcf-info-annotator [-h] -m COLUMN_MAPPINGS [-o OUTPUT_VCF] [-w]
                          [--clear-existing]
                          input_vcf values_file

A tool that will add data from a tab-delimited file to a user-specified field
in the VCF INFO column.

positional arguments:
  input_vcf             A VCF file
  values_file           A TSV file with a header row. The first two columns
                        must be chromosome and position. One or more
                        additional columns can be mapped to VCF INFO fields
                        via --column-mappings.

options:
  -h, --help            show this help message and exit
  -m, --column-mappings COLUMN_MAPPINGS
                        Comma-separated list of mappings from TSV columns to
                        VCF INFO fields. Required fields:
                        source_col:info_field:type:description. Optional
                        fields: :source and :version appended after
                        description. Example 1:
                        "dbsnp_freq:FREQ:Float:Population Frequency in
                        dbSNP"Example 2: "class:CVCLASS:String:ClinVar
                        Classification:ClinVar database:2.1"
  -o, --output-vcf OUTPUT_VCF
                        Path to write the output VCF file. If not provided,
                        the output VCF file will be written next to the input
                        VCF file with a .info.vcf file ending.
  -w, --overwrite       By default, this tool will raise an exception if a
                        mapped field already exists in the VCF. This flag
                        allows existing fields to be overwritten.
  --clear-existing      When overwriting, remove preexisting values for mapped
                        INFO fields from every record, as opposed to just
                        overwriting those that are present in the TSV.
                        Requires --overwrite.

Details

Input TSV format

The TSV file must have a header row. The first two columns must be chromosome and position (one-based coordinates, used to match rows to VCF records). Any additional columns can be mapped to VCF INFO fields by name.

Example TSV with two data columns:

chrom   pos         freq    classification
chr1    168192360   0.042   benign
chr1    230456789   0.187   pathogenic

Gzip-compressed TSV files (.tsv.gz) are also accepted.

Defining column mappings

Use the -m / --column-mappings flag to specify how TSV columns map to VCF INFO fields. Each mapping is a colon-delimited string with four required fields and two optional fields:

source_col:info_field:type:description[:source[:version]]

  • source_col — the column name in the TSV header

  • info_field — the ID to use for the INFO field in the VCF

  • type — the VCF data type: Integer, Float, Flag, Character, or String

  • description — free-text description written to the INFO header line

  • source (optional) — the source database or tool name

  • version (optional) — the source version (requires source to be set)

To annotate multiple INFO fields in one run, separate mappings with a comma:

-m "col1:FIELD1:type:description,col2:FIELD2:type:description"

Overwriting existing fields

By default, the tool raises an error if the VCF already contains an INFO field with the same ID as a mapped field. Use --overwrite (-w) to allow writing to existing fields.

--clear-existing extends this behavior: when set, the existing value is removed from every record before annotation, so records that have no matching TSV entry will have no value for that field rather than retaining the old one. --clear-existing requires --overwrite.

Output

By default the output VCF is written to a .info.vcf file next to your input VCF. Use --output-vcf to specify a different path.

Examples

Download the example data used below:

curl -LO https://vatools.readthedocs.io/en/latest/_static/vatools-examples.tar.gz
tar xzf vatools-examples.tar.gz
cd vatools-examples

1. Annotate a single Integer field

vcf-info-annotator sample.vcf sample.info_single.tsv \
  -m "value:SCORE:Integer:Variant score" \
  -o sample.info.vcf

Adds SCORE=2 to the 22:18644673 record.

2. Annotate two fields in one run

vcf-info-annotator sample.vcf sample.info_multi.tsv \
  -m "mapping_quality:MQ0:Integer:Mapping quality score,clinvar_classification:CVCLASS:String:ClinVar classification" \
  -o sample.info.vcf

Adds MQ0=30;CVCLASS=Pathogenic to the same record.

3. Include source and version in the INFO header

vcf-info-annotator sample.vcf sample.info_multi.tsv \
  -m "mapping_quality:MQ0:Integer:Mapping quality score:BWA-mem:0.3.2" \
  -o sample.info.vcf

Adds Source=ClinVar database,Version=2.1 to the MQ0 header line.

4. Overwrite an existing field, clearing it from records not in the TSV

vcf-info-annotator sample.info.vcf sample.info_multi.tsv \
  -m "mapping_quality:MQ0:Integer:Mapping quality score" \
  -w --clear-existing -o sample.info.overwritten.vcf

Re-runs against the already-annotated output from example 2, which requires -w/--overwrite. Adding --clear-existing means any record not in the TSV would lose its existing MQ0 value rather than keep it (not visible here with only 1 record in the file).