Package: igv-reports
igv-reportsigv-reports - A Python application to generate self-contained HTML reports for variant review and other genomic
applications. Reports consist of a table of genomic sites and an embedded IGV genome browser for viewing data for each
site. The tool extracts slices of data for each site and embeds the data as blobs in the HTML report file. The report
can be opened in a web browser as a static page, with no depenency on the original input files.InstallationPrerequisitesigv-reportsrequires Python 3.8or greater.Installing igv-reportspipinstalligv-reportsigv-reports requires the packagepysamversion 0.22.0 or greater, 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
pysamdocs;"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."condaconfig--addchannelsr
condaconfig--addchannelsbioconda
condainstallpysamCreating a reportReports are created with the command line scriptcreate_report, or
alternativelypython igv_reports/report.py. Command line arguments
are described below. Although--tracksis optional, a typical report will include at least an alignment track
(BAM or CRAM) file from which the variants were called.Arguments:RequiredsitesVCF, BED, MAF, BEDPE, or generic tab delimited file of genomic variant sites. Tabix indexed files are
supported and strongly recommended for large files.--fastaReference fasta file; must be indexed. This argument should be ommited if --genome is used,
otherwise it is required.--genomeAn igv.js genome identifier (e.g. hg38). If supplied fasta, ideogram, and the default annotation
track for the specified genome will be used.*The argumentsbegin,end, andsequenceare required for a generic tab delimitedsitesfile.--beginINT. Column of start chromosomal position forsitesfile. Used for generic tab delimited input.--endINT. Column of end chromosomal position forsites. Used for generic tab delimited input.--sequenceINT. Column of sequence (chromosome) name.Optional coordinate system flag for generic tab delimitedsitesfile only--zero_basedSpecify that the position in thesitesfile is 0-based (e.g. UCSC files) rather than
1-based. Default isfalse.Optional--ideogramFILE. Ideogram file in UCSC cytoIdeo format. Useful whenfastais used to specify the
reference.--tracksLIST. Space-delimited list of track files, see below for supported formats. If bothtracksandtrack-configare specifiedtrackswill appear first by default.--track-configFILE. File containing array of json configuration objects for igv.js tracks. See
theigv.js wikifor more details. This option allows
customization of track parameters. When using this option, the trackurlandindexURLproperties
should be set to the paths of the respective files.--roiLIST. Space-delimited list of region-of-interest (ROI) files.
Seeigv.js wiki.--templateFILE. HTML template file.--outputFILE. Output file name; default="igvjs_viewer.html".--info-columnsLIST. Space delimited list of info field names to include in the variant table. Ifsitesis
a VCF file these are the info ID values. Ifsitesis a tab delimited format these are column names.--info-columns-prefixesLIST. For VCF based reports only. Space delimited list of prefixes of VCF info field
IDs to include in the variant table. Any info field with ID starting with one of the listed values will be
included.--samplesLIST. Space delimited list of sample (i.e. genotypes) names. Used in conjunction with _--sample-columns_.--sample-columnsLIST. Space delimited list of VCF sample FORMAT field names to include in the variant table.
If--samplesis specified columns will be restricted to those samples, otherwise all samples will be included.--flankingINT. Genomic region to include either side of variant; default=1000.--standaloneEmbed all JavaScript referenced via<script>tags in the page.--sortApplies to alignment tracks only. If specified alignments are initally sorted by the specified option.
Supported values includeBASE, STRAND, INSERT_SIZE, MATE_CHR, and NONE. Default value isBASEfor
single nucleotide variants,NONE(no sorting) otherwise. See the igv.js documentation for more information.--exclude-flagsINT. Value is passed to samtools as "-F" flag. Used to filter alignments. Default value is
1536 which filters alignments marked "duplicate" or "vendor failed". To include all alignments
use--exclude-flags 0. Seesamtools documentationfor more
details.--idlinkURL tempate for information link for VCF ID values. The token $$ will be substituted with the ID
value. Example:--idlink 'https://www.ncbi.nlm.nih.gov/snp/?term=$$'--no-embedDon't embed data. Fasta and track URLs are referenced unchanged. The resulting report is dependent
on the original data files, which must be specified as URLs. Local files are not supported with this option.--subsampleFLOAT. Output only a portion of input alignments (0.0 -> 1.0). Seesamtools viewdocumentation
for more details--maxlenINT. Maximum length of a variant (SV) to show in a single view. Variants exceeding this length will
be shown in a split-screen (multilocus) view. default = 10000Track file formats:Currently supported track file formats are BAM, CRAM, VCF, BED, GFF3, GTF, WIG, and BEDGRAPH. FASTA. BAM, CRAM, and
VCFfiles must be indexed. Tabix is supported and it is recommended that all large files be indexed.ExamplesData for the examples are available in the github
repositoryhttps://github.com/igvteam/igv-reports. The repository can be
downloaded as a zip archive
herehttps://github.com/igvteam/igv-reports/archive/refs/heads/master.zip.
It is assumed that the examples are run from the root directory of the repository. Output html is written to the
examples directory.Create a variant report from a VCF file: (Example output)create_reporttest/data/variants/variants.vcf.gz\--fastahttps://igv-genepattern-org.s3.amazonaws.com/genomes/seq/hg38/hg38.fa\--ideogramtest/data/hg38/cytoBandIdeo.txt\--flanking1000\--info-columnsGENETISSUETUMORCOSMIC_IDGENESOMATIC\--samplesreads_1_fastq\--sample-columnsDPGQ\--trackstest/data/variants/variants.vcf.gztest/data/variants/recalibrated.bamtest/data/hg38/refGene.txt.gz\--outputexample_vcf.htmlCreate a variant report from a BED  file: (Example output)echobed
create_reporttest/data/variants/variants.bed\--genomehg38\--flanking1000\--info-columnsGENETISSUETUMORCOSMIC_IDGENESOMATIC\--trackstest/data/variants/variants.bedtest/data/variants/recalibrated.bam\--outputexample_genome.htmlCreate a variant report from a TCGA MAF file: (Example output)create_reporttest/data/variants/tcga_test.maf\--genomehg19\--flanking1000\--info-columnsChromosomeStart_positionEnd_positionVariant_ClassificationVariant_TypeReference_AlleleTumor_Seq_Allele1Tumor_Seq_Allele2dbSNP_RS\--trackstest/data/variants/tcga_test.maf\--outputexample_maf.htmlCreate a variant report from a generic tab-delimited file: (Example output)create_reporttest/data/variants/test.maflite.tsv\--genomehg19\--sequence1--begin2--end3\--flanking1000\--info-columnschrstartendref_allelealt_allele\--outputexample_tab.htmlCreate a structural variant report from a vcf file with CHR2 and END info fields: (Example output)create_reporttest/data/variants/SKBR3_Sniffles_sv.vcf\--genomehg19\--flanking1000\--maxlen10500\--info-columnsSVLEN\--trackstest/data/variants/SKBR3_Sniffles_sv.vcfhttps://igv-genepattern-org.s3.amazonaws.com/test/bam/reads_lr_skbr3.sampled.bam\--outputexample_sv.htmlCreate a structural variant report from a bedpe file with two locations (BEDPE format): (Example output)create_reporttest/data/variants/SKBR3_Sniffles_tra.bedpe\--genomehg19\--flanking1000\--trackstest/data/variants/SKBR3_Sniffles_variants_tra.vcftest/data/variants/SKBR3.ill.bam\--outputexample_bedpe.htmlCreate a report using a genome identifier: (Example output)create_reporttest/data/variants/variants.vcf.gz\--genomehg38\--flanking1000\--info-columnsGENETISSUETUMORCOSMIC_IDGENESOMATIC\--trackstest/data/variants/variants.vcf.gztest/data/variants/recalibrated.bam\--outputexample_genome.htmlCreate a variant report with tracks defined in anigv.js track config json file: (Example output)create_reporttest/data/variants/variants.vcf.gz\--fastahttps://igv-genepattern-org.s3.amazonaws.com/genomes/seq/hg38/hg38.fa\--ideogramtest/data/hg38/cytoBandIdeo.txt\--flanking1000\--info-columnsGENETISSUETUMORCOSMIC_IDGENESOMATIC\--track-configtest/data/variants/trackConfigs.json\--outputexample_config.htmlCreate a variant report with custom ID link urls: (Example output)create_reporttest/data/variants/1kg_phase3_sites.vcf.gz\--genomehg19\--flanking1000\--trackstest/data/variants/1kg_phase3_sites.vcf.gztest/data/variants/NA12878_lowcoverage.bam\--idlink'https://www.ncbi.nlm.nih.gov/snp/?term=$$'\--outputexample_idlink.htmlCreate a junction report from a splice-junction bed file: (Example output)create_reporttest/data/junctions/Introns.38.bed\--genomehg38\--typejunction\--track-configtest/data/junctions/tracks.json\--info-columnsTCGAGTExvariant_name\--title"Sample A"\--outputexample_junctions.htmlCreate a fusion report from a Trinity fusion json file:create_reporttest/data/fusion/igv.fusion_inspector_web.json\--fastatest/data/fusion/igv.genome.fa\--templateigv_reports/templates/fusion_template.html\--track-configtest/data/fusion/tracks.json\--outputexample_fusion.htmlCreate a report containing wig and bedgraph filescreate_reporttest/data/wig/regions.bed\--genomehg19\--exclude-flags512\--trackstest/data/wig/ucsc.bedgraphtest/data/wig/mixed_step.wigtest/data/wig/variable_step.wig\--outputexample_wig.htmlUse ofinfo-columns-prefixesoption. Variant track only, no alignments. (Example output)pythonigv_reports/report.pytest/data/annotated_vcf/consensus.filtered.ann.vcf\--genomehg19\--flanking1000\--info-columnscosmic_gene\--info-columns-prefixesclinvar\--trackstest/data/annotated_vcf/consensus.filtered.ann.vcf\--outputexample_ann.htmlUse--exclude-flagsoption to include duplicate alignments in report by specifying a samtools--exclude-flagsvalue. Default value is 1536 which filters duplicates and vendor-failed reads.create_reporttest/data/dups/dups.bed\--genomehg19\--exclude-flags512\--trackstest/data/dups/dups.bam\--outputexample_dups.htmlUse-no-embedoption to use external URL references for tracks in the report.create_reporttest/data/variants/variants.vcf.gz\--genomehg38\--no-embed\--trackshttps://igv-genepattern-org.s3.amazonaws.com/test/reports/variants.vcf.gzhttps://igv-genepattern-org.s3.amazonaws.com/test/reports/recalibrated.bam\--outputexample_noembed.htmlConverting genomic files to data URIs for use in igv.jsThe scriptcreate_datauri(python igv_reports/datauri.py) converts the contents of a file to a data uri for
use in igv.js. The datauri will be printed to stdout.NOTEIt 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_datauritest/data/variants/variants.vcf.gzConvert a slice of a local bam file to a datauri.create_datauri--regionchr5:474,969-475,009test/data/variants/recalibrated.bamConvert a remote bam file to a datauri.create_datauri--regionchr5:474,969-475,009https://1000genomes.s3.amazonaws.com/phase3/data/NA12878/alignment/NA12878.mapped.ILLUMINA.bwa.CEU.low_coverage.20121211.bamRelease Notes