# Getting started with vcfheader

The fast variant call format (VCF) file header intelligence and audit.

## TLDR

The main workflow is to parse a VCF header and write a standalone HTML report.

    input <- parse_vcf_header("file.vcf")

    vcfheader(
      input,
      file = "file_report.html"
    )

## Example report preview

A preview of the bundled example HTML report is shown below.

The report includes file metadata, contig summaries, INFO and FORMAT field definitions, and other header entries in a portable HTML layout.

## Overview

The `vcfheader` package reads and interprets Variant Call Format (VCF) header metadata without loading full variant records. It is designed for fast inspection, validation, and reporting of header structure in both small and large VCF files.

This vignette shows how to:

- read bundled example VCF headers
- parse the header into a structured `vcf_hdr` object
- inspect key metadata and inferred annotations
- generate an HTML report
- open a bundled example HTML report
- preview the report layout with a screenshot

## Bundled example files

The package examples use small VCF files shipped with the package, so the vignette works offline and is suitable for package checking.

    simple_vcf <- system.file("extdata", "simple.vcf", package = "vcfheader")
    sv_vcf <- system.file("extdata", "sv44.vcf", package = "vcfheader")

    basename(simple_vcf)
    #> [1] "simple.vcf"
    basename(sv_vcf)
    #> [1] "sv44.vcf"

## Read raw header lines

Use `read_vcf_header()` when you want only the original header lines.

    hdr_lines <- read_vcf_header(simple_vcf)
    head(hdr_lines, 5)
    #> [1] "##fileformat=VCFv4.3"
    #> [2] "##fileDate=20090805"
    #> [3] "##source=myImputationProgramV3.1"
    #> [4] "##reference=file:///seq/references/1000GenomesPilot-NCBI36.fasta"
    #> [5] "##contig=<ID=20,length=62435964,assembly=B36,md5=f126cdf8a6e0c7f379d618ff66beb2da,species=\"Homo sapiens\",taxonomy=x>"

## Parse a VCF header

Use `parse_vcf_header()` to create a structured object containing file metadata, contigs, INFO and FORMAT definitions, sample names, warnings, and errors.

    hdr <- parse_vcf_header(simple_vcf)
    hdr
    #> <vcf_hdr>
    #>   fileformat: VCFv4.3
    #>   samples: 3
    #>   contigs: 1
    #>   INFO: 6  FORMAT: 4  FILTER: 2  ALT: 0

## Inspect parsed content

The parsed object is a list-like S3 object with standard components.

    names(hdr)
    #>  [1] "file"        "samples"     "contigs"     "info"        "format"
    #>  [6] "filter"      "alt"         "sample_meta" "pedigree"    "other_kv"
    #> [11] "raw"         "warnings"    "errors"

File-level metadata:

    file_meta <- hdr$file
    file_meta$input_path <- basename(file_meta$input_path)
    file_meta
    #> $input_path
    #> [1] "simple.vcf"
    #>
    #> $fileformat
    #> [1] "VCFv4.3"
    #>
    #> $fileDate
    #> [1] "20090805"
    #>
    #> $source
    #> [1] "myImputationProgramV3.1"
    #>
    #> $reference
    #> [1] "file:///seq/references/1000GenomesPilot-NCBI36.fasta"
    #>
    #> $phasing
    #> [1] "partial"

Sample names:

    hdr$samples
    #> [1] "NA00001" "NA00002" "NA00003"

INFO definitions:

    hdr$info[, c("ID", "Number", "Type", "Description")]
    #>   ID Number    Type                 Description
    #> 1 NS      1 Integer Number of Samples With Data
    #> 2 DP      1 Integer                 Total Depth
    #> 3 AF      A   Float            Allele Frequency
    #> 4 AA      1  String            Ancestral Allele
    #> 5 DB      0    Flag dbSNP membership, build 129
    #> 6 H2      0    Flag          HapMap2 membership

FORMAT definitions:

    hdr$format[, c("ID", "Number", "Type", "Description")]
    #>   ID Number    Type       Description
    #> 1 GT      1  String          Genotype
    #> 2 GQ      1 Integer  Genotype Quality
    #> 3 DP      1 Integer        Read Depth
    #> 4 HQ      2 Integer Haplotype Quality

Validation output:

    hdr$warnings
    #> character(0)
    hdr$errors
    #> character(0)

## Inference from the header

The parser can add lightweight inferred annotations. For example, some common annotation systems can be guessed from reserved INFO tags.

    hdr$file$caller_guess
    #> NULL

## Structural variant example

The structural-variant example includes symbolic ALT definitions and structural INFO fields.

    sv_hdr <- parse_vcf_header(sv_vcf)
    sv_hdr
    #> <vcf_hdr>
    #>   fileformat: VCFv4.4
    #>   samples: 1
    #>   contigs: 1
    #>   INFO: 9  FORMAT: 1  FILTER: 0  ALT: 6

Contigs:

    sv_hdr$contigs[, intersect(c("ID", "length", "assembly", "md5"), names(sv_hdr$contigs)), drop = FALSE]
    #>     ID  length assembly  md5
    #> 1 chrA 1000000     <NA> <NA>

ALT definitions:

    sv_hdr$alt[, c("ID", "Description")]
    #>           ID                 Description
    #> 1        INV                   Inversion
    #> 2        INS                   Insertion
    #> 3        DUP                 Duplication
    #> 4 DUP:TANDEM          Tandem Duplication
    #> 5        DEL                    Deletion
    #> 6        CNV Copy number variable region

INFO fields:

    sv_hdr$info[, c("ID", "Number", "Type", "Description")]
    #>          ID Number    Type
    #> 1    MATEID      A  String
    #> 2       END      1 Integer
    #> 3     CIPOS      . Integer
    #> 4     SVLEN      A Integer
    #> 5     CILEN      . Integer
    #> 6     EVENT      A  String
    #> 7 EVENTTYPE      A  String
    #> 8   SVCLAIM      A  String
    #> 9 IMPRECISE      0    Flag
    #>                                                                                                           Description
    #> 1                                                                                                 ID of mate breakend
    #> 2                                                        End position of the longest variant described in this record
    #> 3                                                     Confidence interval around POS for symbolic structural variants
    #> 4                                                                                        Length of structural variant
    #> 5                                                                             Confidence interval for the SVLEN field
    #> 6                                                                                              ID of associated event
    #> 7                                                                                            Type of associated event
    #> 8 Claim made by the structural variant call. Valid values are D, J, DJ for abundance, adjacency and both respectively
    #> 9                                                                                      Imprecise structural variation

## Generate an HTML report

`vcfheader()` writes a standalone HTML report. This is the main use case.

    hdr <- parse_vcf_header("file.vcf")

    out_file <- "file_report.html"

    vcfheader(
      hdr,
      file = out_file
    )

    file.exists(out_file)
    #> [1] TRUE
    basename(out_file)
    #> [1] "file_report.html"

You can also let `vcfheader()` derive the output path from the original input file path.

    vcfheader(hdr)

## Bundled example HTML report

The package also ships a prebuilt example report generated from the bundled `simple.vcf` file.

    example_report <- system.file(
      "extdata",
      "simple_vcfheader.html",
      package = "vcfheader"
    )

    basename(example_report)
    #> [1] "simple_vcfheader.html"
    file.exists(example_report)
    #> [1] TRUE

This file can be opened directly in a browser after installation.

## Summary

`vcfheader` provides a quick way to inspect VCF header metadata, validate structure, extract structured definitions, and produce a portable HTML summary for review or reporting.

For research use only.

VCFheader is a free and open-source tool provided by Switzerland Omics. Use of the software and generated reports is permitted, including in commercial settings, under the MIT License. Attribution to Switzerland Omics and VCFheader should be retained where reasonably practicable. Further information: https://switzerlandomics.ch. Switzerland Omics® is a registered trade mark. VCF specification references in this report relate to samtools and the broader HTS specifications ecosystem and are distributed under the MIT/Expat License by Genome Research Ltd. Source: https://github.com/samtools/samtools. Further reading on HTS and file format specifications: https://www.htslib.org/doc/#file-formats.