vcflib(1)

📦
version 1.0.12 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🦋 vcflib(1) 🦋

okay bestie, welcome to the vcflib index page. This is the manual for vcflib — like, the whole vibe. We're folding the manual name in right here so you know it's vcflib(1) and the title is vcflib (index). Let's go. 💅

🌸 NAME 🌸

vcflib index

✨ DESCRIPTION ✨

vcflib contains tools and libraries for dealing with the Variant Call Format (VCF), which is a flat-file, tab-delimited textual format intended to describe reference-indexed variations between individuals.

VCF provides a common interchange format for the description of variation in individuals and populations of samples, and has become the de-facto standard reporting format for a wide array of genomic variant detectors. periodt. 🧬✨

vcflib provides methods to manipulate and interpret sequence variation as it can be described by VCF. It is both:

  • an API for parsing and operating on records of genomic variation as it can be described by the VCF format,
  • and a collection of command-line utilities for executing complex manipulations on VCF files.

The API itself provides a quick and extremely permissive method to read and write VCF files. Extensions and applications of the library provided in the included utilities (*.cpp) comprise the vast bulk of the library’s utility for most users. iykyk 💖

🧁 filter 🧁

Here's the filter crew, bestie:

  • vcffilter — VCF filter the specified vcf file using the set of filters. slay.
  • vcfuniq — List unique genotypes. Similar to GNU uniq, but aimed at VCF records. vcfuniq removes records which have the same position, ref, and alt as the previous record on a sorted VCF file. Note that it does not adjust/combine genotypes in the output, but simply takes the first record. See also vcfcreatemulti for combining records. important caveat alert! 🚨
  • vcfuniqalleles — List unique alleles. For each record, remove any duplicate alternate alleles that may have resulted from merging separate VCF files.

📊 metrics 📊

The metrics girlies:

  • vcfcheck — Validate integrity and identity of the VCF by verifying that the VCF record’s REF matches a given reference file.
  • vcfdistance — Adds a tag to each variant record which indicates the distance to the nearest variant. (defaults to BasesToClosestVariant if no custom tag name is given.
  • vcfentropy — Annotate VCF records with the Shannon entropy of flanking sequence. Annotates the output VCF file with, for each record, EntropyLeft, EntropyRight, EntropyCenter, which are the entropies of the sequence of the given window size to the left, right, and center of the record. Also adds EntropyRef and EntropyAlt for each alt. so many entropy tags, we love to see it.
  • vcfhetcount — Calculate the heterozygosity rate: count the number of alternate alleles in heterozygous genotypes in all records in the vcf file.
  • vcfhethomratio — Generates the het/hom ratio for each individual in the file.

🧬 phenotype 🧬

  • permuteGPAT++ — permuteGPAT++ is a method for adding empirical p-values to a GPAT++ score.

🧬 genotype 🧬

  • abba-baba — abba-baba calculates the tree pattern for four individuals. This tool assumes reference is ancestral and ignores non abba-baba sites. The output is a boolean value: 1 = true, 0 = false for abba and baba. The tree argument should be specified from the most basal taxa to the most derived. basal to derived, no cap.
  • hapLrt — HapLRT is a likelihood ratio test for haplotype lengths. The lengths are modeled with an exponential distribution. The sign denotes if the target has longer haplotypes (1) or the background (-1). math but make it fashion.
  • normalize-iHS — normalizes iHS or XP-EHH scores. normalize it, bestie.

✨ transformation ✨

okay so these are the lil glow-up artists 💅 every one of them takes your data and transforms it into something else, and honestly? iconic behavior.

  • dumpContigsFromHeader — dumps the contigs straight outta the header. that's the whole job, and it does it flawlessly 🎀
  • smoother — a method for window smoothing, and it handles many of the GPAT++ formats 🦋
  • vcf2dag — modifies your VCF so you can actually build a directed acyclic graph (DAG) out of it ✨
  • vcf2fasta — generates sample_seq:N.fa for each sample, reference sequence, and chromosomal copy N in [0,1... ploidy]. every single sequence inside the fasta file is named with the same pattern used for the file name, which means you can combine them later. teamwork fr 🫶
  • vcf2tsv — converts VCF to per-allele or per-genotype tab-delimited format, using a null string to replace the empty values in the table. specify -g and you get one line per sample with genotype information. when there's more than one alt allele you'll get multiple rows, one for each allele, and the INFO will match the A index 💜
  • vcfaddinfo — adds INFO fields from the second file that aren't already present in the first VCF file. filling in the gaps, we love to see it 🌸
  • vcfafpath — displays genotype paths
  • vcfallelicprimitives — > WARNING: this tool is considered legacy and is only retained for older workflows. it will emit a warning! 😭 and even though it can use the WFA, bestie… you should use vcfwave instead. periodt.
  • vcfannotate — intersects the records in the VCF file with targets provided in a BED file. the intersections are done on the reference sequences in the VCF file. if no VCF filename is specified on the command line (that's the last argument), the VCF gets read from stdin 🍓
  • vcfannotategenotypes — examines genotype correspondence. it annotates the genotypes in the first file with the genotypes in the second, adding the genotype as another flag to each sample field in the first file. annotation-tag is the name of the sample flag that gets added to store the annotation. it also adds a has_variant flag for sites where the second file has a variant ✨
  • vcfbreakmulti — if multiple alleles are specified in a single record, it breaks that record into multiple lines, preserving all the allele-specific INFO fields. no info left behind 💖
  • vcfcat — concatenates VCF files 🐱
  • vcfclassify — creates a new VCF where each variant is tagged by allele class: snp, ts/tv, indel, mnp
  • vcfcleancomplex — removes reference-matching sequence from complex alleles and adjusts the records to reflect the positional change 🧚
  • vcfcombine — combines VCF files positionally, combining samples when sites and alleles are identical. any number of VCF files may be combined. when records in multiple files match, the INFO field and other columns are taken from one of the files which are combined. alleles must have identical ordering to be combined into one record — if they don't, multiple records will be emitted. rules are rules 💀
  • vcfcommonsamples — generates each record in the first file, removing the samples that aren't present in the second 🌈
  • vcfcreatemulti — goes through a sorted VCF and, when overlapping alleles are represented across multiple records, merges them into a single multi-ALT record. see the documentation for more information 👑
  • vcfecho — echoes VCF to stdout (simple demo)
  • vcfevenregions — generates a list of regions, e.g. chr20:10..30, using the variant density information provided in the VCF file, to make sure the regions have even numbers of variants. this can be used to reduce the variance in runtime when dividing variant detection or genotyping by genomic coordinates. highkey a time-saver 🔥
  • vcffixup — generates a VCF stream where AC and NS have been generated for each record using sample genotypes
  • vcfflatten — removes multi-allelic sites by picking the most common alternate. requires allele frequency specification AF and use of G and A to specify the fields which vary according to the Allele or Genotype. the VCF file may be specified on the command line or piped as stdin 🎀
  • vcfgeno2alleles — modifies the genotypes field to provide the literal alleles rather than indexes
  • vcfgeno2haplo — converts genotype-based phased alleles within –window-size into haplotype alleles. it will break haplotype construction when it encounters non-phased genotypes on input 😭
  • vcfgenosamplenames — gets you the sample names 💅
  • vcfglbound — adjusts GLs so that the maximum GL is 0, by dividing all the GLs for each sample by the max
  • vcfglxgt — sets genotypes using the maximum genotype likelihood for each sample
  • vcfindex — adds an index number to the INFO field (id=position)
  • vcfinfo2qual — sets QUAL from the info field tag keyed by [key]. the VCF file may be omitted and read from stdin. if the field contains multiple values, the average of the field is used 🧮
  • vcfinfosummarize — takes annotations given in the per-sample fields and adds the mean, median, min, or max to the site-level INFO
  • vcfintersect — VCF set analysis 🔍
  • vcfkeepgeno — okay so bestie, this one slims down your file by removing FORMAT fields not listed on the command line from sample specifications in the output. It's giving minimalism 💅
  • vcfkeepinfo — To decrease file size, remove INFO fields not listed on the command line. Less is more, queen ✨
  • vcfkeepsamples — outputs each record in the vcf file, removing samples not listed on the command line. Bye felicia 👋
  • vcfld — Compute LD. That's it. Short and iconic 💖
  • vcfleftalign — Left-align indels and complex variants in the input using a pairwise ref/alt alignment followed by a heuristic, iterative left realignment process that shifts indel representations to their absolute leftmost (5’) extent. It's literally shifting them to the far left, no cap 🧚
  • vcflength — Add length info field. Simple, but effective 💅
  • vcfnullgenofields — Makes the FORMAT for each variant line the same (uses all the FORMAT fields described in the header). Fills out per-sample fields to match FORMAT. Expands GT values of `.' with number of alleles based on ploidy (eg: `./.' for dipolid). It's giving uniformity ✨
  • vcfnumalt — outputs a VCF stream where NUMALT has been generated for each record using sample genotypes. Slay 💅
  • vcfoverlay — Overlay records in the input vcf files with order as precedence. First one wins, bestie 👑
  • vcfprimers — For each VCF record, extract the flanking sequences, and write them to stdout as FASTA records suitable for alignment. Get those primers, queen 🧬
  • vcfqual2info — Puts QUAL into an info field tag keyed by [key]. So you can keep that quality somewhere useful 💖
  • vcfremap — For each alternate allele, attempt to realign against the reference with lowered gap open penalty. If realignment is possible, adjust the cigar and reference/alternate alleles. Observe how different alignment parameters, including context and entropy-dependent ones, influence variant classification and interpretation. It's a whole vibe check for your variants 🔥
  • vcfremoveaberrantgenotypes — strips samples which are homozygous but have observations implying heterozygosity. Remove samples for which the reported genotype (GT) and observation counts disagree (AO, RO). Not today, aberrant genotypes 💀
  • vcfremovesamples — outputs each record in the vcf file, removing samples listed on the command line. Bye bestie, you're not invited to the party 🙈
  • vcfsample2info — Take annotations given in the per-sample fields and add the mean, median, min, or max to the site-level INFO. Summary stats, but make it fashion ✨
  • vcfsamplediff — Establish putative somatic variants using reported differences between germline and somatic samples. Tags each record where the listed sample genotypes differ with . The first sample is assumed to be germline, the second somatic. Each record is tagged with ={germline,somatic,loh} to specify the type of variant given the genotype difference between the two samples. It's giving detective work 🔍
  • vcfsamplenames — List sample names. That's it. Simple, but necessary 💅
  • vcfstreamsort — Sorts the input (either stdin or file) using a streaming sort algorithm. Guarantees that the positional order is correct provided out-of-order variants are no more than 100 positions in the VCF file apart. So if they're within 100 spots, you're good 🌈
  • vcfwave — Realign reference and alternate alleles with WFA, parsing out the `primitive' alleles into multiple VCF records. New records have IDs that reference the source record ID. Genotypes/samples are handled correctly. Deletions generate haploid/missing genotypes at overlapping sites. It's giving wave 🌊

✨ statistics ✨

  • bFst — okay so bFst is a Bayesian approach to Fst. Importantly bFst accounts for genotype uncertainty in the model using genotype likelihoods. For a more detailed description see: A Bayesian approach to inferring population structure from dominant markers’ by Holsinger et al. Molecular Ecology Vol 11, issue 7 2002. The likelihood function has been modified to use genotype likelihoods provided by variant callers. There are five free parameters estimated in the model: each subpopulation’s allele frequency and Fis (fixation index, within each subpopulation), a free parameter for the total population’s allele frequency, and Fst. 💖
  • genotypeSummary — Generates a table of genotype counts. Summarizes genotype counts for bi-allelic SNVs and indel. ✨
  • iHS — iHS calculates the integrated haplotype score which measures the relative decay of extended haplotype homozygosity (EHH) for the reference and alternative alleles at a site (see: voight et al. 2006, Spiech & Hernandez 2014). 🧬
  • meltEHH — no description given, bestie. It’s just out here living its mystery life. 💀
  • pFst — pFst is a probabilistic approach for detecting differences in allele frequencies between two populations. 🔥
  • pVst — pVst calculates vst, a measure of CNV stratification. 💅
  • permuteSmooth — permuteSmooth is a method for adding empirical p-values smoothed wcFst scores. 🎀
  • plotHaps — plotHaps provides the formatted output that can be used with `bin/plotHaplotypes.R'. 📊
  • popStats — General population genetic statistics for each SNP. 🌸
  • segmentFst — segmentFst creates genomic segments (bed file) for regions with high wcFst. 🧬
  • segmentIhs — Creates genomic segments (bed file) for regions with high wcFst. (yes, same as above, not a typo, bestie) ✨
  • sequenceDiversity — The sequenceDiversity program calculates two popular metrics of haplotype diversity: pi and extended haplotype homozygosity (eHH). Pi is calculated using the Nei and Li 1979 formulation. eHH a convenient way to think about haplotype diversity. When eHH = 0 all haplotypes in the window are unique and when eHH = 1 all haplotypes in the window are identical. 🦋
  • vcfaltcount — count the number of alternate alleles in all records in the vcf file. 🔢
  • vcfcountalleles — Count alleles. 💯
  • vcfgenosummarize — Adds summary statistics to each record summarizing qualities reported in called genotypes. Uses: RO (reference observation count), QR (quality sum reference observations) AO (alternate observation count), QA (quality sum alternate observations). 📈
  • vcfgenotypecompare — adds statistics to the INFO field of the vcf file describing the amount of discrepancy between the genotypes (GT) in the vcf file and the genotypes reported in the . use this after vcfannotategenotypes to get correspondence statistics for two vcfs. 👀
  • vcfgenotypes — Report the genotypes for each sample, for each variant in the VCF. Convert the numerical represenation of genotypes provided by the GT field to a human-readable genotype format. (note: “represenation” is misspelled in the original, keep it! bestie, we don’t fix typos here, we preserve the vibe) 🧬
  • vcfparsealts — Alternate allele parsing method. This method uses pairwise alignment of REF and ALTs to determine component allelic primitives for each alternate allele. 🔬
  • vcfrandom — Generate a random VCF file. 🎲
  • vcfrandomsample — Randomly sample sites from an input VCF file, which may be provided as stdin. Scale the sampling probability by the field specified in KEY. This may be used to provide uniform sampling across allele frequencies, for instance. 🎯
  • vcfroc — Generates a pseudo-ROC curve using sensitivity and specificity estimated against a putative truth set. Thresholding is provided by successive QUAL cutoffs. 📉
  • vcfsitesummarize — Summarize by site. 📍
  • vcfstats — Prints statistics about variants in the input VCF file. 📊
  • wcFst — wcFst is Weir & Cockerham’s Fst for two populations. Negative values are VALID, they are sites which can be treated as zero Fst. For more information see Evolution, Vol. 38 N. 6 Nov 1984. Specifically wcFst uses equations 1,2,3,4. 🔥

🌈 SOURCE CODE 🌈

okay so if you wanna peek at the source, bestie, it’s right here:

https://github.com/vcflib/vcflib

🫶 CREDIT 🫶

Citations are the bread and butter of Science. If you are using this software in your research and want to support our future work, please cite the following publication:

Please cite:

A spectrum of free software tools for processing the VCF variant call format: vcflib, bio-vcf, cyvcf2, hts-nim and slivar (https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1009123). Garrison E, Kronenberg ZN, Dawson ET, Pedersen BS, Prins P (2022), PLoS Comput Biol 18(5): e1009123. https://doi.org/10.1371/journal.pcbi.1009123

💜 LICENSE 💜

Copyright 2011-2024 (C) Erik Garrison and vcflib contributors. Copyright 2020-2024 (C) Pjotr Prins MIT licensed.

👑 AUTHORS 👑

Erik Garrison and vcflib contributors.

And that’s the whole page, bestie — vcflib, vcflib(1), no cap. Go slay some variants. 💅✨

📦 where this page comes from