Skip to main content

Creates self-contained html pages for visual variant review with IGV (igv.js).

Project description


Python application to generate self-contained igv.js pages that can be opened within a browser with "file" protocol. The generated html page contains all data neccessary for IGV as uuencoded blobs.



igv-reports requires Python 3.6 or greater and pip.

As with all Python projects, use of a virtual environment is recommended. Instructions for creating a virtual environment using conda follow.

1. Install Anaconda from

2. Create a virtual environment

conda create -n myenv python=3.7.1
conda install -n myenv pip
conda activate myenv

Installing igv-reports

pip install igv-reports

igv-reports requires the package pysam which should be installed automatically. However on OSX this sometimes fails due to missing dependent libraries. This can be fixed following the procedure below, from the pysam docs;
"The recommended way to install pysam is through conda/bioconda. This will install pysam from the bioconda channel and automatically makes sure that dependencies are installed. Also, compilation flags will be set automatically, which will potentially save a lot of trouble on OS X."

conda config --add channels r
conda config --add channels bioconda
conda install pysam

Creating a report

A report consists of a table of sites or regions and an associated IGV views for each site. Reports are created with the command line script create_report. Command line arguments are described below. Although --tracks is optional, a typical report will include at least an alignment track (BAM or CRAM) file from which the variants were called.


  • Required
    • sites VCF or BED file of genomic sites.
    • fasta Reference fasta file; must be indexed.
  • Optional
    • --tracks Space-delimited list of track files, see below for supported formats. If both tracks and track-config are specified tracks will appear first.
    • --track-confg File containing array of json configuration objects for igv.js tracks. See the igv.js wiki for more details. This option allows customization of track parameters.
    • --ideogram Ideogram file in UCSC cytoIdeo format.
    • --template HTML template file.
    • --output Output file name; default="igvjs_viewer.html".
    • --info-columns Space delimited list of VCF info field names to include in variant table.
    • --info-columns-prefixes Space delimited list of prefixes of VCF info field names to include in variant table.
    • --sample-columns Space delimited list of VCF sample/format field names to include in variant table.
    • --flanking Genomic region to include either side of variant; default=1000.
    • --standalone Embed all JavaScript referenced via <script> tags in the page.

Track file formats:

Currently supported track file formats are BAM, CRAM, VCF, BED, GFF3, and GTF. FASTA. BAM, CRAM, and VCF files must be indexed. Tabix is supported for other file types and it is recommended that all large files be indexed.


Data for the examples are available for download.

Creating a variant report from a VCF file:

create_report examples/variants/variants.vcf.gz --ideogram examples/variants/cytoBandIdeo.txt --flanking 1000 --info-columns GENE TISSUE TUMOR COSMIC_ID GENE SOMATIC --tracks examples/variants/variants.vcf.gz examples/variants/recalibrated.bam examples/variants/refGene.sort.bed.gz --output igvjs_viewer.html

Createing a junction report from a splice-junction bed file

create_report examples/junctions/Introns.38.bed --type junction --ideogram examples/junctions/cytoBandIdeo.txt --output junctions.html --track-config examples/junctions/tracks.json --info-columns TCGA GTEx variant_name --title "Sample A"

Converting genomic files to data URIs for use in igv.js

The script create_datauri converts the contents of a file to a data uri for use in igv.js. The datauri will be printed to stdout. NOTE It is not neccessary to run this script explicitly to create a report, it is documented here for use with stand-alone igv.js.

Convert a gzipped vcf file to a datauri.

create_datauri examples/variants/variants.vcf.gz

Convert a slice of a remote cram file to a datauri.

create_datauri \
--region 8:127,738,322-127,738,508 \ 

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for igv-reports, version 1.0.2
Filename, size File type Python version Upload date Hashes
Filename, size igv_reports-1.0.2-py3-none-any.whl (22.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size igv-reports-1.0.2.tar.gz (20.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page