Home › IGV User Guide › External Control of IGV › Creating HTML Links to IGV

Creating HTML Links to IGV

This section describes two forms of HTML links for interacting with IGV from a web page. The first can be used to launch IGV on the client machine at a specific locus with a supplied session file. The second can be used to load data and session files into IGV (after it has been launched).  

Links to Launch and Load Data

The first type of HTML link makes use of a dynamic "php" file hosted at the Broad Institute to launch IGV on a specified session or data file.  An example follows

http://www.broadinstitute.org/igv/projects/current/igv.php?sessionURL=URL&user=name&locus=locus

The table below contains the full parameter list

Parameter   Description
sessionURL Required URL to a session file (further described below), or a comma-delimited list of data files.
file   Alias for sessionURL
index Optional URL to an index file, or a comma-delimited list of index files.  This parameter is only used if sessionURL points to and indexed data file or list of files.   If a list is used, the index list must be the same length as the data file list.
locus Optional Locus to display. Use any syntax that is valid in the IGV search box.
user Optional

A short name identifying your website or organization.
genome Optional A genome identifier (e..g hg18).  This is useful if you specify a data file rather than a session file for the sessionURL.  Click here for a list of recognized genome ids.
initalHeapSize Optional Initial memory footprint, specified as an integer followed by an "m" for megabytes.  The default value is 256m. 
maxHeapSize Optional Maximum memory setting.  The default value is 1000m  (1 gigabyte). 
name Optional Specifies a name or names for the track(s).  This parameter is ignored if loading a session file. 
merge Optional Controls whether or not the loaded data is merged with the existing IGV session, or a loaded into a new session.  If false, any data currently loaded will be unloaded after clicking this link.   The default value is false if file is a session file, true otherwise. 

 

BAM File Example:

http://www.broadinstitute.org/igv/projects/current/igv.php?sessionURL=http://1000genomes.s3.amazonaws.com/data/NA12878/high_coverage_alignment/NA12878.mapped.ILLUMINA.bwa.CEU.high_coverage_pcr_free.20130520.bam&genome=hg19&locus=chr1:64,098,103-64,098,175

Session File Example:

http://www.broadinstitute.org/igv/projects/current/igv.php?sessionURL=http://www.broadinstitute.org/igvdata/exampleFiles/gbm_session.xml

 

Links to Load Data

The second type of link will load data into a running IGV.  This makes use of the listener port, which must be enabled.  This option can be controlled on the "Advanced" preferences tab, and is enabled by default listening on port 60151.   Links can be created to load data or jump to a locus as follows.

http://localhost:port/load?file=URL&locus=locus&genome=genome&merge=[true|false]&name=name

http://localhost:port/goto?locus=locus

The file parameter value can be a URL or a comma-delimited list of URLs to most IGV-supported data file types (exceptions listed below), or a session file.   The merge parameter (optional) controls whether or not the loaded data is merged with the existing IGV session, or a loaded into a new session.  If false, any data currently loaded will be unloaded after clicking this link.   The default value is false if file is a session file, true otherwise.  The name parameter (optional) specifies a name or names for the track.  If multiple tracks are loaded as a comma-delimited list, the name parameter value should also be a comma-delimited list of the same size.   The name parameter is ignored if loading a session.

Examples:

http://localhost:60151/load?file=http://www.broadinstitute.org/igvdata/annotations/hg18/conservation/pi.12mer.wig.tdf&locus=egfr&genome=hg18

http://localhost:60151/load?file=http://www.broadinstitute.org/igvdata/exampleFiles/gbm_session.xml&merge=true

http://localhost:60151/goto?locus=egfr

Session File Format

IGV produces a session file in XML format when a user clicks on File>Save Session. You can also create a session file manually.  The XML format (IGV version 1.5) is described below.

Session XML Hierarchy
  • <Global>
    • <Resources>
      • <Resource>
    • <Panel>
      • <Track>
        • <DataRange>
Description of Session Components

Required - These elements are required in a session file.

  • <Global>: The root XML element.
    • genome= The genome id (e.g., hg18).
    • locus= The initial genomic region to be viewed (chromosome:start-end or gene name).
    • version= The session version (this must equal '3').
  • <Resources>: An enclosing element for all Resource elements.
  • <Resource>: Contains information about the data sources to be loaded, including data files, feature files, sample information files, and DAS servers.
    • name= The name of the track (single track files only).
    • path= The location of the data source (file path or URL).
    • url= Defines a URL for external links associated with a feature track. Any '$$' in this string will be substituted with the name of the current feature.

Optional  - These elements are optional in a session file and are used to determine the placement of tracks and visual style choices. They are included in an XML file produce when you save a session in IGV, but are typically not included in an XML file that is created manually.

  • <Panel>:
    • name= A panel identifier used internally by IGV. 
    • height= The default height for the panel.
  • <Track>:
    • color= The default color for the data in the track.
    • expand= Whether the track is initially expanded or not.
    • height= The default height of the track.
    • id= A track identified used internally by IGV.
    • name= The display name for the track.
    • renderer= The renderer used to display the data.
    • visible= Whether the track is visible or has been filtered out.
    • windowFunction= The function to be used when displaying data
  • <DataRange>:  Defines the y axis for tracks when rendered as charts.
    • baseline= Line is drawn at this y value. Default is 0.
    • maximum= Maximum y value.
    • minimum= Minimum y value. Default is 0.
    • type= Scale type, "LINEAR" or "LOG"
    • drawBaseline (not used)
    • flipAxis (not used)
Session File Example

The XML below is an example of a minimal session file.

------------------------------------------------------------------------------------------------------------------------------

<?xml version="1.0" encoding="UTF-8"?>

<Global genome="hg18" locus="EGFR" version="3">

<Resources>

<Resource name="RNA Genes" path="http://www.broadinstitute.org/igvdata/tcga/gbm/GBM_batch1-8_level3_exp.txt.recentered.080820.gct.tdf"/>

<Resource name="RNA Genes" path="http://www.broadinstitute.org/igvdata/annotations/hg18/rna_genes.bed"/>

<Resource name="sno/miRNA" path="http://www.broadinstitute.org/igvdata/tcga/gbm/Sample_info.txt"/>

</Resources>

</Global>