# How to Visualize Variants from a VCF File in IGV By the end of this guide you will be able to take a Variant Call Format (VCF) file produced by any common variant caller, confirm that it matches the reference genome you intend to view, compress and index it correctly, load it into the Integrative Genomics Viewer (IGV), and read the resulting track alongside aligned reads so that a variant call becomes something you can actually inspect. You will also be able to recognize the three failures that account for most empty or misleading IGV sessions: a chromosome naming mismatch, a missing index, and a build mismatch between the VCF and the genome loaded in the viewer. You need four things on hand before you start. A VCF file, ideally one you can trace back to the exact reference build it was called against. The matching reference genome sequence in FASTA format, or the identifier of a genome already hosted inside IGV. The aligned reads in BAM format if you want to see the evidence behind each call rather than the calls alone. And a working installation of IGV, plus `bcftools`, `tabix`, and `bgzip` from htslib for the preparation steps. The packaged IGV installers include a Java runtime, while the command line launcher expects a Java runtime already on your path. ## What IGV Actually Adds to a Variant Table A VCF is a text file. You can read it with `less`, filter it with `bcftools`, and summarize it in R. What IGV adds is spatial and contextual. It places each variant against the reference sequence, stacks the aligned reads underneath, and lets you judge whether a heterozygous call looks like a clean 50/50 split or like a handful of reads at the edge of a coverage drop. The Integrative Genomics Viewer is described in the clinical genomics literature as a tool that enables visualization and interpretation of complex sequencing data, and the same work emphasizes that visual evaluation of sequencing results is a primary means by which molecular pathologists assess and finalize cases, and that inspection in IGV can reveal contextual cues that routine variant-calling algorithms do not report [1]. That framing matters for how you use the tool. IGV is not a variant caller and it does not re-score your calls. It is a viewer that renders files faithfully, which means it will also faithfully render your mistakes. A VCF with Ensembl-style contig names loaded against a University of California Santa Cruz (UCSC) style genome will produce a blank track, and IGV will not warn you about why. ## The File Formats You Need to Keep Straight Variant visualization sits at the end of a chain of bioinformatics file formats, and most confusion in IGV sessions traces back to mixing them up. A useful review of online resources for high-throughput sequencing describes the use and applications of common file formats for coding and storing genomic data alongside web-accessible open-source resources for visualization and analysis [2]. The clinical IGV literature makes the same point more directly, covering the format and purpose of FASTQ, BAM, and VCF files before describing which IGV features derive from each [1]. ### FASTA versus FASTQ A FASTA file stores sequence with no quality information. Each record begins with a `>` header line, followed by the sequence, optionally wrapped across multiple lines: ``` >chr7:140753336-140753386 TACAGAAACATGAAGGTAAA ``` A FASTQ file stores raw sequencing reads and, critically, a per-base quality score for every base. Each record has four lines: an `@` header, the sequence, a `+` separator, and a string of ASCII characters that encode Phred quality scores. ``` @A00123:45:H7ABC:1:1101:1000:1000 1:N:0:ATCACG GTACAGAAACATGAAGGTAAATTT + FFFFFFFFFFFFFFFFFFFFFFFF ``` Both use the same four-letter alphabet, so they look similar at a glance, but they answer different questions. FASTA holds a reference or a consensus and is what you load into IGV as the genome. FASTQ holds raw instrument output, has no coordinates, and IGV does not display it. The reason this distinction bites people is that FASTQ is where the mutation evidence actually originates. One tool designed for exactly that problem, MutScan, scans FASTQ files directly to grab all reads supporting a target mutation and piles them up for visualization, explicitly because conventional alignment viewing tools such as IGV were considered too heavy for validating mutations in ultra-[deep sequencing](/knowledge/molecular-biology/deep-sequencing) data [3]. If your variant sits at 0.1 percent allele fraction in a 50,000x library, IGV may be the wrong instrument and a direct FASTQ scan may be the right one. ### BAM and VCF A BAM file holds reads that have been aligned to a reference, with each read carrying a chromosome, a start position, a mapping quality, and a CIGAR string describing how it aligns. A VCF holds the variants inferred from those alignments, one line per site per sample combination. The two are complements, and IGV is designed to show them together. The genome-browser community has repeatedly used this pairing: proBAM files, which encode peptide spectrum matches in genomic coordinates, were noted as being readily visualized in genome browsers, bringing proteomics data to a general audience beyond the proteomics community [4]. The same logic applies here. The VCF tells you what was called and the BAM tells you why. A fourth format worth knowing is bigWig, a binary indexed format for continuous signal such as coverage or a per-base score. Tools that compute selection statistics often emit bigWig because it is widely supported by genome browsers [5]. If you want to see depth or a score track beneath your variants, bigWig is the format to produce, not a text table. ## Step 1: Inspect the VCF Before You Load It Never open a VCF in IGV as the first action. Spend sixty seconds on the header. The header tells you the file format version, the contig names and lengths, the INFO and FORMAT field definitions, and often the reference build the caller used. ```bash grep "^##" tumor.vcf | head -40 ``` Expected output, abbreviated: ``` ##fileformat=VCFv4.2 ##reference=file:///refs/GRCh38_full_analysis_set.fa ##contig= ##INFO= ##FORMAT= ##FORMAT= ``` Two things matter in that block. The `##contig` lines give you the exact chromosome strings the file uses, here `chr7` with the `chr` prefix. The `##reference` line, when present, names the FASTA the caller used. If `##reference` is absent, you have to ask whoever ran the pipeline. A VCF does not reliably self-describe its build. ### What one VCF record contains Take a single well-known record, the BRAF V600E substitution on chromosome 7: ``` #CHROM POS ID REF ALT QUAL FILTER INFO FORMAT TUMOR NORMAL chr7 140753336 rs113488022 T A . PASS DP=412 GT:AD 0/1:188,224 0/0:400,0 ``` The core columns are CHROM, POS, ID, REF, ALT, QUAL, FILTER, INFO, FORMAT, then one column per sample. POS is 1-based. REF and ALT are given on the forward strand of the reference. QUAL is a Phred-scaled quality, so a value of 30 corresponds to an estimated 1 in 1,000 chance that the site is not variant. FILTER is `PASS` when the site survived the caller's filters. INFO holds site-level annotations. FORMAT declares the per-sample fields, and here GT:AD means each sample column carries a genotype followed by allelic depths. Reading `0/1:188,224` takes a little practice. The genotype `0/1` means one reference allele and one alternate allele, so a heterozygous call. The two depth values are reference allele depth 188 and alternate allele depth 224, which is a near-perfect 46 percent alternate fraction. That record should look convincing in IGV. `0/0:400,0` in the normal sample means 400 reference reads and zero alternate reads, which is what a somatic caller wants to see in matched normal tissue. Pulling that record out with a query is faster than scrolling: ```bash bcftools query -f '%CHROM\t%POS\t%REF\t%ALT[\t%GT\t%AD]\n' tumor.norm.vcf.gz ``` ``` chr7 140753336 T A 0/1 188,224 ``` ## Step 2: Match the VCF to a Reference Build This is the single most common failure point, so treat it as a hard gate. IGV loads a genome and then places tracks onto that genome by matching chromosome names and coordinates. It does not cross-check the VCF's build declaration against the genome you loaded. If you load human GRCh37 coordinates onto a GRCh38 genome, the variants will appear, and they will be in the wrong place, shifted by hundreds of kilobases in some regions and by different amounts in others. The track will not look broken. It will look plausible, which is worse. Confirm the build by comparing three things: the `##reference` or pipeline metadata, the contig lengths in the `##contig` lines, and the naming convention. A contig line reading `##contig=` indicates GRCh38 coordinates with Ensembl-style naming. A line reading `##contig=` indicates GRCh37 coordinates with UCSC-style naming. Both the prefix and the length have to agree with the genome you plan to load. ```bash bcftools view -h tumor.vcf | grep -E "^##(contig|reference)" ``` If the naming does not match the genome you want to use, rename the contigs rather than switching genomes. The mapping is mechanical: ```bash printf "1\tchr1\n2\tchr2\n7\tchr7\nX\tchrX\nY\tchrY\nMT\tchrM\n" > chr_map.txt bcftools annotate --rename-chrs chr_map.txt tumor.vcf.gz -Oz -o tumor.chr.vcf.gz tabix -p vcf tumor.chr.vcf.gz ``` Remember to rewrite the `##contig` lines to match, since renaming the CHROM column without rewriting the header leaves the file internally inconsistent and produces the `[W::vcf_parse] Contig 'chr1' is not defined in the header` warning when you next index or query it. ## Step 3: Normalize and Split Multiallelic Records IGV renders multiallelic records poorly and renders left-aligned, parsimonious records well. A record whose ALT field reads `A,AT` represents two distinct alleles on one line, which makes per-allele depth hard to read and can shift the apparent position of an insertion. Splitting and left-aligning is cheap and reversible in the sense that you keep the original file untouched. ```bash bcftools norm -m -any -f GRCh38.fa tumor.chr.vcf.gz -Oz -o tumor.norm.vcf.gz ``` The `-m -any` flag splits multiallelic sites into biallelic records. The `-f` flag supplies the reference FASTA so that indels are left-aligned and checked against the reference sequence. Expect output like: ``` Lines total/split/realigned/skipped: 14231/318/96/0 ``` A nonzero realigned count is normal for indel-heavy call sets. A large skipped count usually means the reference FASTA you passed does not match the VCF's coordinates, which is your cue to stop and recheck Step 2. Normalization also gives you a quieter benefit. When a REF allele in the VCF disagrees with the reference base in the FASTA, `bcftools norm` reports it. IGV will show that disagreement as a mismatch in the pileup, but it will not label the cause, so catching it here saves you an hour of confusion later. ## Step 4: Compress and Index IGV can open an uncompressed VCF, but it must read the entire file into memory to do so. For a whole-genome multi-sample VCF that is tens of gigabytes, which is why people report IGV freezing. Compress with `bgzip` and index with `tabix` and IGV will fetch only the region on screen. ```bash bgzip -c tumor.norm.vcf > tumor.norm.vcf.gz tabix -p vcf tumor.norm.vcf.gz ``` Verify the index exists and covers what you think it covers: ```bash ls -1 tumor.norm.vcf.gz* tabix -l tumor.norm.vcf.gz ``` ``` tumor.norm.vcf.gz tumor.norm.vcf.gz.tbi chr7 ``` The `.tbi` file must sit next to the `.vcf.gz` file with exactly that name. IGV finds it by name convention, not by configuration. If you move the VCF, move the index with it. If you regenerate the VCF, regenerate the index, because a stale index produces the `[tabix] the index file is older than the data file: reindex please` error and IGV will show stale or missing features. For a targeted review, subset before loading. A 2 megabase window around your gene of interest loads in a second and keeps the session responsive: ```bash bcftools view -r chr7:140450000-140800000 -Oz -o braf_window.vcf.gz tumor.norm.vcf.gz tabix -p vcf braf_window.vcf.gz ``` ## Step 5: Visualize the VCF Variants in IGV, Step by Step The walkthrough below is the sequence that produces a reliable session. Deviating from it is where most problems begin. 1. Launch IGV with the correct genome selected before loading any track. Choosing the genome first avoids the situation where IGV auto-guesses from a file and guesses wrong. 2. Confirm the genome. The genome selector in the upper left should read the build you intended, for example Human (GRCh38/hg38). If it reads something else, switch it now. 3. Load the compressed, indexed VCF using File > Load from File, or drag the `.vcf.gz` onto the window. Load the `.vcf.gz`, not the plain `.vcf`, unless the file is small. 4. Load the matching BAM if you have one, plus its `.bai` index. Order does not matter, but loading the VCF first makes the track appear on top, which is easier to read. 5. Navigate to the variant. Paste a locus into the search box in the format `chr7:140753336-140753336` and press Enter. The view centers on that base. 6. Zoom to a range of roughly 50 to 200 bases. At whole-chromosome zoom IGV shows a density summary rather than individual variant rows. Individual records appear only once the scale is fine enough. 7. Right-click the VCF track and set the track height so that rows are legible. A track set to a few pixels tall will show colored ticks with no labels. 8. Right-click the VCF track and use Color by to color records by allele frequency, genotype, or another field. Coloring by genotype is the fastest way to separate heterozygous from homozygous calls across many samples. 9. Confirm the variant row aligns with the base you expect in the reference sequence track. The reference sequence track at the top of the window shows the base at each position, so a T-to-A substitution should show T in the reference row and A in the variant row at the same column. 10. Read the alignment pileup at that column. Count the reads carrying the alternate base, note their strand distribution, and check whether the alternate allele appears in both orientations rather than clustering on one strand. A typical command line invocation that skips the manual clicking: ```bash igv.sh -g hg38 -l chr7:140753336-140753336 tumor.norm.vcf.gz tumor.bam ``` The `-g` flag sets the genome, `-l` sets the initial locus, and any trailing file arguments load as tracks. Exact flags vary between IGV releases, so confirm against `igv.sh, help` for your installed version. ### Batch snapshots for reproducible figures Manual clicking does not reproduce. IGV accepts a batch script that replays a session and writes images, which is how you generate the same figure for a manuscript twice. ``` new genome hg38 load tumor.norm.vcf.gz load tumor.bam goto chr7:140753336-140753336 sort base snapshot BRAF_V600E.png exit ``` ```bash igv.sh -b snapshots.txt ``` The `snapshot` command writes a PNG of the current view to the working directory. The `sort base` command groups reads by the base at the center of the view, which makes a heterozygous site visually obvious because the reference and alternate reads separate into two blocks. ## Reading the VCF Track in Context Once the track is rendering, the interpretive work begins. IGV shows each VCF record as a row with the reference and alternate alleles drawn as colored blocks. Hovering a record displays the ID, QUAL, FILTER, INFO fields, and per-sample FORMAT values in a popup. Clicking a record opens a details panel with the full record text. Three checks belong in every review. First, allele balance. Divide the alternate allele depth by total depth from the AD field. A heterozygous germline call should land near 0.5. A somatic call in a tumor sample with normal contamination often lands lower, and a clonal homozygous call lands near 1.0. Values far from the expected range warrant a look at the reads themselves. Second, strand bias. In the alignment track, color reads by strand and check whether alternate-supporting reads appear on both the forward and reverse strand. A variant supported only by forward-strand reads is more likely to be an artifact. The `sort strand` batch command makes this visible quickly. Third, mapping quality and local context. A variant sitting in a region of collapsed repeats, in a segmental duplication, or at the edge of a coverage cliff is a candidate for a mapping artifact regardless of what the caller reported. The clinical IGV literature makes exactly this argument, that visual inspection can unmask subtle contextual cues that variant-calling algorithms do not surface on their own [1]. ## Key Options That Change What You See | Control | Where to find it | What it does | When to change it | |--|--|--|--| | Genome | Genome selector, or `-g` on the command line | Sets the coordinate system and sequence that all tracks are placed against | Always set it before loading tracks | | Index file | Must be named `file.vcf.gz.tbi` beside the VCF | Enables region-based random access | Whenever a VCF is larger than a few megabytes | | Track height | Right-click the track > Set track height | Controls whether variant rows show labels or just colored ticks | When the track looks empty but is not | | Color by | Right-click the VCF track > Color by | Colors records by genotype, allele frequency, or other fields | Multi-sample VCFs, cohort review | | Visibility window | Right-click the track > Set visibility window | Limits how much data is fetched at low zoom | Slow sessions on large files | | Sort by | Right-click an alignment track > Sort by | Groups reads by base, strand, quality, read group, or haplotype | Judging allele balance and strand bias | | Squish / Expanded | Right-click a track > track height mode | Compresses or expands rows | Fitting more tracks in one window | | Batch script | `-b script.txt` on launch | Replays a session and writes snapshots | Publication figures, reproducible QC | ## Verifying That What You See Is Correct Do not trust the picture alone. Three independent checks confirm the session. The first is a coordinate check. Query the VCF for the same region and compare to what IGV displays. ```bash bcftools view -H -r chr7:140753336-140753336 tumor.norm.vcf.gz ``` ``` chr7 140753336 rs113488022 T A . PASS DP=412 GT:AD 0/1:188,224 0/0:400,0 ``` The REF and ALT must match the blocks IGV drew. A mismatch means the VCF was renormalized after indexing, or that IGV is displaying a cached version of an older file. The second is a read count check. Count the reads carrying the alternate base directly from the BAM and compare to the AD field. ```bash samtools mpileup -f GRCh38.fa -r chr7:140753336-140753336 tumor.bam ``` The fourth pileup column lists the bases observed at each position, with `.` for reference-matching forward reads, `,` for reference-matching reverse reads, and the uppercase and lowercase alternate bases for forward and reverse alternate reads respectively. Counting those characters should approximate the AD values. Small differences are normal because AD is computed after the caller's own read filters. The third is a build spot check. Pick one variant with a known rsID and confirm its position in a public database matches the position in your file. This catches build swaps that survived every earlier check. ## Scaling to Many Samples and Many Variants A cohort VCF with thousands of samples will strain any viewer. Two techniques keep it workable. Subset by sample before loading. If you only need to compare a tumor and its matched normal out of a thousand-sample cohort, extract those two columns: ```bash bcftools view -s TUMOR,NORMAL -Oz -o pair.vcf.gz cohort.vcf.gz tabix -p vcf pair.vcf.gz ``` Filter by quality or consequence before loading, rather than after. Loading 400,000 variants to find 30 is a waste of both your time and IGV's memory: ```bash bcftools view -i 'QUAL>=30 && INFO/DP>=20' -Oz -o filtered.vcf.gz tumor.norm.vcf.gz tabix -p vcf filtered.vcf.gz ``` If you need a compact cohort-level summary rather than a per-variant view, a different class of tool is appropriate. CoMut-style plots summarize mutation rates and sample burden across a cohort, and CoMutPlotter accepts VCF among its input formats to produce those publication-quality summaries without command line work [6]. IGV answers a per-site question. Tools of that family answer a per-cohort question. For exploratory work across many regions, the genomics visualization ecosystem has broader options. SeqPlots was built as a graphical interface for profile plots and heatmaps, accepting all major genomic file formats as input and generating configurable plots in seconds through graphical controls [7]. A general review of online resources for sequencing analysis describes several web-accessible open-source options for visualization and analysis [2]. The practical rule is that IGV handles locus-level inspection well, browser-based frameworks handle portal-scale distribution, and dedicated plotting tools handle cohort summaries. ## Common Mistakes and Limitations **Loading an uncompressed VCF.** IGV will read the whole file into memory. On a whole-genome call set this appears as a frozen window or a session that never finishes loading. Always `bgzip` and `tabix` first. **Forgetting that the index must be co-located and current.** The `.tbi` file is found by name convention. Move the VCF without the index and IGV falls back to a full scan. Regenerate the VCF without reindexing and IGV reads stale offsets, which can show variants at the wrong position or omit them entirely. **Chromosome naming mismatch.** A VCF using `7` loaded against a genome using `chr7` produces an empty track with no error. This is the most frequent cause of a blank IGV session and it does not announce itself. **Build mismatch.** GRCh37 variants loaded on GRCh38 render plausibly but sit in the wrong place. IGV does not reconcile builds for you and will not warn you. Confirm contig lengths, not just prefixes. **Judging a variant from the VCF track alone.** A row in the VCF track reflects what the caller decided. Without the BAM loaded underneath, you cannot see allele balance, strand bias, mapping quality, or whether the site sits in a collapse of reads from a paralogous region. **Assuming IGV validates.** IGV does not re-evaluate QUAL, does not re-apply filters, and does not check that the REF allele matches the reference base. A record with a REF allele that disagrees with the FASTA will render, and the disagreement shows as a mismatch in the pileup, not as a warning. **Using IGV where it is the wrong instrument.** For ultra-deep targeted assays where a variant may sit at very low allele fraction, alignment viewers can be too heavy and too coarse. MutScan was built specifically to scan FASTQ data directly for reads supporting a target mutation because conventional alignment-viewing tools were unsuitable for validating mutations in ultra-deep sequencing data [3]. **Treating a visual as a diagnosis.** A clean-looking pileup supports a call. It does not confirm pathogenicity, and it does not replace orthogonal confirmation by a second method. **Expecting individual variant rows at low zoom.** At whole-chromosome scale, IGV summarizes. If the track looks empty, zoom in before concluding the file is broken. **Ignoring contig definitions in the header.** Renaming CHROM values without rewriting `##contig` lines leaves the file internally inconsistent and produces warnings on the next indexing or querying step. **Loading a FASTA without an index.** Genome browsers expect FASTA to be accompanied by an index for efficient random access, and the general workflow for loading a reference from FASTA into a genome browser treats that preparation as part of setup rather than an optional extra [8]. ## Frequently Asked Questions ### Does IGV require a VCF index to open a file? No, but it requires one to be fast. IGV will open an uncompressed or unindexed VCF by reading the entire file, which is impractical beyond a few megabytes. Compressing with `bgzip` and indexing with `tabix -p vcf` enables region-based access. ### Why is my VCF track blank in IGV? The most common cause is a chromosome naming mismatch between the VCF and the loaded genome, followed by a missing or stale index. Check the `##contig` lines in the VCF header and confirm the genome selector shows the build you intended. ### Can IGV show per-sample genotypes from a multi-sample VCF? Yes. Each sample column in the VCF becomes a separate row group in the track, and the Color by menu can tint records by genotype so that heterozygous and homozygous calls are visually distinct across many samples. ### Can IGV read an uncompressed VCF file? Yes, it can, and it will load the whole file into memory rather than fetching only the visible region. For anything larger than a targeted panel, compress and index first. ### How do I see the reads supporting a called variant? Load the BAM file containing the aligned reads alongside the VCF, navigate to the variant position, and read the pileup column at that base. Color reads by strand and sort by base to judge allele balance and strand bias. ### What is the difference between a FASTA file and a FASTQ file? FASTA stores sequence without quality scores and is used for reference genomes. FASTQ stores raw sequencing reads with a per-base Phred quality string encoded as ASCII characters. IGV displays FASTA as the genome but does not display FASTQ. ### How do I export an image of a variant for a figure? Use the IGV batch script interface with the `snapshot` command, which writes a PNG of the current view. This reproduces the same figure reliably across sessions, unlike a manual screen capture. ### Why does IGV show a different position than my clinical report? Almost always a build difference. A report may cite GRCh37 coordinates while the genome loaded in IGV is GRCh38, or the reverse. Compare the contig lengths in the VCF header with the genome you loaded to confirm which build each source uses. ## Sources 1. [Clinical Variant Interpretation with the Integrative Genomics Viewer (IGV) for Molecular Pathologists.](https://pubmed.ncbi.nlm.nih.gov/42611741/) 2. [Online resources for genomic analysis using high-throughput sequencing.](https://pubmed.ncbi.nlm.nih.gov/25655493/) 3. [MutScan: fast detection and visualization of target mutations by scanning FASTQ data.](https://pubmed.ncbi.nlm.nih.gov/29357822/) 4. [proBAMsuite, a Bioinformatics Framework for Genome-Based Representation and Analysis of Proteomics Data.](https://pubmed.ncbi.nlm.nih.gov/26657539/) 5. [Prioritising positively selected variants in whole-genome sequencing data using FineMAV.](https://pubmed.ncbi.nlm.nih.gov/34922440/) 6. [CoMutPlotter: a web tool for visual summary of mutations in cancer cohorts.](https://pubmed.ncbi.nlm.nih.gov/31296206/) 7. [SeqPlots - Interactive software for exploratory data analyses, pattern discovery and visualization in genomics.](https://pubmed.ncbi.nlm.nih.gov/27918597/) 8. [Setting Up the JBrowse 2 Genome Browser.](https://pubmed.ncbi.nlm.nih.gov/39126338/)