How to Review Your Own Sequencing Data in IGV

By the end of this guide you will have IGV running locally against your own aligned sequencing data. You will also have a set of correctly indexed files it can open without complaint, a reproducible batch script that produces the same screenshots every time, and a self-contained HTML report you can send to a collaborator or hand to an analysis agent. You need three things to start. The first is alignments, meaning a BAM or CRAM file plus the reference FASTA if you are using CRAM. The second is a variant call file in VCF format, bgzipped and tabix-indexed. The third is enough local disk to keep a 30x whole genome, which runs roughly 50-60 GB as CRAM and 90-120 GB as BAM. A machine with 16 GB of RAM is comfortable. Everything below uses free, open-source software: IGV itself is MIT-licensed, and samtools, bcftools, and htslib are the standard toolchain for preparing its inputs.

IGV stands for Integrative Genomics Viewer, and it is a genome browser in the same family as the UCSC and Ensembl browsers, with one important difference. Those browsers are built to show you annotations over a reference. IGV is built to show you your reads over a reference, which is what you need when the question is whether a particular variant call in your own data is real.

1. Install the right IGV for the job

There are four things called IGV, and picking the wrong one wastes an afternoon. IGV Desktop is the Java application you download from igv.org. It is what you want for interactive read-level review because it handles local multi-gigabyte files without uploading anything. IGV-Web (igv.org/app) runs in the browser and is convenient for a quick look at a small file or a URL-hosted track, but it streams byte ranges over HTTP and is slower on local data. The JavaScript library underneath IGV-Web is igv.js, for embedding views in your own pages. The Python package igv-reports bakes IGV views into a static HTML file, which is the right tool for archiving evidence.

Install IGV Desktop with the bundled Java build for your platform (the “Java included” download) rather than relying on a system JDK, because IGV is sensitive to JavaFX availability and version drift. On Linux and macOS you can also install the command-line distribution and run igv.sh. Memory is set in a plain text file next to the launcher: edit igv.args in the installation directory so it contains a line like -Xmx8g. The default heap is too small for a whole genome with several tracks loaded, and the symptom of running out is not a clean error but a frozen window.

# Linux/macOS command-line distribution
unzip IGV_Linux_2.19.2_WithJava.zip && cd IGV_Linux_2.19.2
echo "-Xmx8g" > igv.args
./igv.sh

2. Index and sanity-check every input file

IGV does random access by file offset, so every input needs a companion index and will be refused without one. This is the single most common reason a file “won’t load.”

# Alignments
samtools index -@ 4 sample.bam                 # produces sample.bam.bai
samtools index -@ 4 sample.cram                # produces sample.cram.crai

# Variants: must be bgzip-compressed, not gzip
bgzip -@ 4 sample.vcf                          # produces sample.vcf.gz
bcftools index -t sample.vcf.gz                # produces sample.vcf.gz.tbi

# Interval files
sort -k1,1 -k2,2n regions.bed | bgzip > regions.bed.gz
tabix -p bed regions.bed.gz

Before you load anything, confirm that the alignment’s reference matches the genome you will select in IGV. Two properties have to agree: the build (hg19/GRCh37 versus hg38/GRCh38 versus T2T-CHM13) and the contig naming convention (chr1 versus 1). Read the header:

samtools view -H sample.cram | grep '^@SQ' | head -3
# @SQ  SN:chr1  LN:248956422   -> hg38, UCSC-style names
# @SQ  SN:1     LN:249250621   -> GRCh37, Ensembl-style names

A contig length of 248,956,422 for chromosome 1 means GRCh38. A length of 249,250,621 means GRCh37. If your VCF uses 1 and your BAM uses chr1, IGV will display both files but the variant track will appear empty at every locus you visit. Fix the mismatch rather than working around it:

printf "1\tchr1\n2\tchr2\n" > chr_map.txt   # extend for all contigs
bcftools annotate --rename-chrs chr_map.txt sample.vcf.gz -Oz -o sample.chr.vcf.gz
bcftools index -t sample.chr.vcf.gz

For CRAM, IGV needs the exact reference FASTA used at alignment time, because CRAM stores reference-relative differences. Point IGV at it by loading a genome from file (Genomes > Load Genome from File) using the same FASTA plus its .fai index. Do not use a re-downloaded copy from a different source. A FASTA with identical sequence but different contig ordering or different handling of alternate haplotypes will produce decoding errors or, worse, silently wrong bases.

3. Set preferences so IGV shows you the evidence

IGV’s defaults are tuned for responsiveness on large files, and several of them hide exactly the information you need for judging a variant. Open View > Preferences > Alignments and change the following.

Turn off downsampling, or raise its limits. By default IGV keeps a capped number of reads per window, which distorts apparent allele fraction at high-coverage sites. For targeted review of a handful of loci, uncheck “Downsample reads” entirely.

Show soft-clipped bases. Soft clips are the parts of a read the aligner declined to match. A cluster of reads soft-clipped at the same position is one of the most informative signals for a nearby insertion, deletion, or structural breakpoint ¹. They are hidden by default.

Raise the visible range threshold from 30 kb if you want to see reads across a whole gene at once, but expect memory pressure. Leave “Show duplicates” off for normal review and turn it on when you suspect a PCR-duplicate artifact is inflating support for a variant.

Finally, set “Shade base by quality” on and keep the mapping-quality-zero shading default, which renders reads with MAPQ 0 in white. White reads mean the aligner could not decide where the read belongs, and any variant supported only by white reads should be treated as unresolved rather than real.

4. Read a pileup

Navigate by typing a gene symbol, an rsID, or coordinates (chr7:140,753,000-140,753,400) into the location box. Then look at four things in order, which is essentially the workflow that has been formalized for clinical variant review ².

Allele fraction and depth. Right-click the alignment track and enable “Show allele fraction” on the coverage track, or hover a position to get the per-base counts. A heterozygous germline single-nucleotide variant in 30x whole-genome data should sit near 50 percent with both alleles represented on both strands. Fractions near 20 percent or below in germline data usually indicate mismapping, a nearby indel, or mosaicism, in that order of prior probability.

Strand and position bias. Color alignments by “read strand” and sort by base. If every supporting read carries the variant at the same distance from its 5’ end, or all support comes from one strand, the call is more likely to be an artifact of the library or the aligner than a real difference in your genome ³.

Mapping quality and repeat context. Group alignments by “mapping quality” to separate confident from ambiguous reads. Regions with segmental duplications and pseudogenes (the classic examples are the pseudogene-shadowed exons of genes with near-identical paralogs) produce piles of MAPQ 0 reads and a characteristic spray of heterozygous-looking variants at fixed positions in every sample.

Indel representation. Insertions appear as purple I markers whose width does not reflect length. Hover to read the inserted sequence. Deletions appear as black gap lines. In homopolymer and short-tandem-repeat tracts, expect genuine ambiguity: the same underlying allele can be left- or right-aligned differently by different callers, so a VCF record that appears to disagree with the reads may only be shifted. Enable “view as pairs” and compare insert sizes if the indel is large ³.

None of this establishes what a variant means for your health. Deciding that a variant is clinically significant requires curated evidence, confirmation in a clinically accredited laboratory, and a clinician or genetic counselor to interpret it in the context of your history. IGV tells you whether a call is well supported by the data in front of you, which is a prerequisite. It is not a conclusion.

5. Script the review so it reproduces

Clicking through loci is fine once. For anything you will repeat, use IGV’s batch language. Write a text file of commands and run it headlessly or from Tools > Run Batch Script.

new
genome hg38
snapshotDirectory /data/igv_snapshots
load /data/sample.cram
load /data/sample.vcf.gz
maxPanelHeight 800
preference SAM.DOWNSAMPLE_READS false
preference SAM.SHOW_SOFT_CLIPPED true

goto chr7:140753336
sort base
squish
snapshot BRAF_V600_region.png

goto chr13:32340300-32340400
sort position
snapshot BRCA2_locus.png
exit

./igv.sh --batch review.txt

IGV also listens on TCP port 60151 when “Enable port” is set in Preferences > Advanced, which lets you drive a live session from a shell or a notebook:

echo "goto chr17:43,063,900-43,064,100" | nc localhost 60151
echo "snapshot chk_brca1.png"           | nc localhost 60151

For a portable artifact, use igv-reports. It embeds slices of your BAM and VCF directly into an HTML file that opens with no server and no data dependencies, which makes it the right format for a record you want to still be readable in three years.

pip install igv-reports
create_report variants.vcf.gz \
  --genome hg38 \
  --flanking 1000 \
  --info-columns GENE IMPACT AF \
  --tracks sample.cram refGene.bed \
  --output review_report.html

6. Add RNA-seq: coverage, junctions, and sashimi plots

RNA-seq alignments in IGV answer a different question than DNA alignments. They show which exons are joined and at what relative abundance. They do not address whether a base differs. Load a coordinate-sorted, indexed BAM from a splice-aware aligner (STAR or HISAT2) and IGV will render a splice junction track from the N operations in the CIGAR strings, with arc thickness proportional to the number of spanning reads.

For a quantitative view across many samples or long regions, precompute a coverage track instead of streaming reads. Either of these works, and both produce files IGV opens instantly:

# bigWig, normalized to bins per million
bamCoverage -b rna.bam -o rna.bw --binSize 10 --normalizeUsing BPM -p 8

# IGV's native TDF, multi-resolution
igvtools count -w 25 rna.bam rna.tdf hg38

Then right-click the junction track and choose Sashimi Plot for a publication-style figure with junction read counts printed on the arcs. Sashimi plots are the fastest way to check whether a splice-region variant in your DNA corresponds to an observable change in transcript structure, for example intron retention or exon skipping that shows up as a new arc absent from reference annotation. Interpreting the magnitude requires care: a junction supported by three reads in a gene expressed at 5 TPM is noise.

7. Add copy number and structural variants

Copy-number and structural variation need different track types than point mutations. For copy number from CNVkit, export the segment calls to SEG format, which IGV renders as a heatmap-and-segment track aligned to the genome axis ⁴.

cnvkit.py export seg sample.cns -o sample.seg
# load sample.cnr as well for the per-bin log2 ratios

Load both the smoothed segments (.cns via SEG) and the raw per-bin ratios (.cnr, which IGV accepts as an IGV-format track), because a segment call is only as good as the scatter underneath it. Bins with extreme GC content or low mappability drive most spurious calls.

For structural variants, the useful IGV modes are “view as pairs” and the soft-clip display from step 3. Coloring by insert size and pair orientation also helps. A deletion shows as pairs with abnormally large inserts plus a coverage drop between the breakpoints. An inversion shows as pairs with the same orientation on both ends. A translocation shows as reads whose mates map to another chromosome, which IGV colors by mate chromosome. Short-read evidence for large rearrangements is indirect. The practical guidance is to require agreement between at least two signal types before treating a call as real, meaning discordant pairs and split reads ¹.

8. Add annotation context

Reads and calls are more interpretable against regulatory context, and IGV loads remote annotation tracks by URL from File > Load from URL. Useful additions include candidate cis-regulatory elements and DNase or ChIP signal from ENCODE, which mapped functional elements across many cell types and provides per-cell-type signal tracks in bigWig and bigBed form ⁵. A noncoding variant that falls inside a promoter-like element active in a relevant tissue is a different object of interest than one in a region with no measured activity in any assay, and the browser makes that distinction visible in a few seconds ⁶.

Keep annotation tracks in a saved session (File > Save Session) so your locus review always starts from the same configuration. Sessions are XML referencing file paths or URLs. That makes them small and diffable, so they are worth keeping under version control.

Common problems

Reads or variants do not appear even though the file loaded. Nearly always a contig naming or build mismatch. Check the @SQ lines as in step 2 and the ##contig lines in the VCF header.

Apparent allele fraction is wrong. Downsampling is on, or duplicates are hidden and the variant is duplicate-driven, or both. Toggle each and recount.

A variant looks heterozygous everywhere in a gene family member. Group by mapping quality. If the support is MAPQ 0, the locus is unresolvable with short reads and needs a different technology rather than a closer look.

CRAM fails to decode or shows nonsensical mismatches. The reference FASTA does not match the one used for alignment. Compare the M5 checksums in the @SQ lines against samtools faidx output on your candidate FASTA.

IGV freezes on a wide region. The visible range threshold is high and the window contains millions of reads. Narrow the view, or use a precomputed TDF or bigWig for the wide view and switch to alignments only when you zoom in.

Coordinates appear off by one. IGV displays 1-based inclusive coordinates, as do VCF and SAM. BED files are 0-based half-open. A BED feature starting at 1000 aligns with IGV position 1001.

The mitochondrial contig behaves oddly. Coverage on chrM is typically one to two orders of magnitude higher than the nuclear genome, so it dominates coverage-scaling and can make heteroplasmy at a few percent look like a clean call. Mitochondrial DNA also has distinct fragmentation and circularity properties that affect how reads pile up near the origin ⁷. Set the coverage track to a fixed data range rather than autoscale when viewing chrM alongside nuclear tracks.

Large cohort or reference comparisons are slow from local files. For public reference data, load from a hosted endpoint instead of downloading, and note that resources such as the broad tumor-normal collections are organized around per-sample tracks that IGV can stream individually rather than in bulk ⁸.

Footnotes

1. Lixing Yang. A Practical Guide for Structural Variation Detection in the Human Genome. Current Protocols in Human Genetics, 2020. https://doi.org/10.1002/cphg.103 ↩ ↩²

2. Eitan Halper-Stromberg, Suguna Narayan, Vincent Laufer, et al. Clinical Variant Interpretation with the Integrative Genomics Viewer (IGV) for Molecular Pathologists. Journal of Visualized Experiments, 2026. https://doi.org/10.3791/71808 ↩

3. Peter Robinson, Tomasz Zemo jtel. Integrative genomics viewer (IGV): Visualizing alignments and variants. Computational Exome and Genome Analysis, 2017. https://doi.org/10.1201/9781315154770-17 ↩ ↩²

4. Eric Talevich, A. Hunter Shain, Thomas Botton, et al. CNVkit: Genome-Wide Copy Number Detection and Visualization from Targeted DNA Sequencing. PLOS Computational Biology, 2016. https://doi.org/10.1371/journal.pcbi.1004873 ↩

5. The ENCODE Project Consortium. An integrated encyclopedia of DNA elements in the human genome. Nature, 2012. https://doi.org/10.1038/nature11247 ↩

6. The ENCODE Project Consortium. Identification and analysis of functional elements in 1% of the human genome by the ENCODE pilot project. Nature, 2007. https://doi.org/10.1038/nature05874 ↩

7. Grant T. Daly, Viktor M. Pastukh, Yong B. Tan, et al. Novel attributes of cell‐free plasma mitochondrial DNA in traumatic injury. Clinical and Translational Medicine, 2022. https://doi.org/10.1002/ctm2.1055 ↩

8. Katarzyna Tomczak, Patrycja Czerwińska, Maciej Wiznerowicz. Review The Cancer Genome Atlas (TCGA): an immeasurable source of knowledge. Współczesna Onkologia, 2015. https://doi.org/10.5114/wo.2014.47136 ↩