Main Window

The following figure shows data from The Cancer Genome Atlas:

	The tool bar provides access to commonly used functions. The menu bar and pop-up menus (not shown) provide access to all other functions.
	The red box on the chromosome ideogram indicates which portion of the chromosome is displayed. When zoomed out to display the full chromosome, the red box disappears from the ideogram.
	The ruler reflects the visible portion of the chromosome. The tick marks indicate chromosome locations. The span lists the number of bases currently displayed.
	IGV displays data in horizontal rows called tracks. Typically, each track represents one sample or experiment. This example shows methylation, gene expression, copy number, LOH, and mutation data.
	IGV also displays features, such as genes, in tracks. By default, IGV displays data in one panel and features in another, as shown here. Drag-and-drop a track name to move a track from one panel to another. Combine data and feature panels by selecting that option on the General tab of the Preferences window.
	Track names are listed in the far left panel. Legibility of the names depends on the height of the tracks; i.e., the smaller the track the less legible the name.
	Attribute names are listed at the top of the attribute panel. Colored blocks represent attribute values, where each unique value is assigned a unique color. Hover over a colored block to see the attribute value. Click an attribute name to sort tracks based on that attribute value.

Menu Bar

Tool Bar

Genome drop-down box	Loads a genome. more...
Chromosome drop-down box	Zooms to a chromosome. more...
Search box	Displays the chromosome location being shown. To scroll to a different location, enter the gene name, locus, or track name and click Go. more...
Whole genome view	Zooms to whole genome view. more...
	Moves backward and forward through views of the genome like the back and forward buttons in a web browser.
Refresh	Refreshes the display.
Define a region	Defines a region of interest on the chromosome. more...
	Reduces the row height on all tracks to fit all data for the region in view into the window; will also expand tracks (to their maximum preferred size) to fill the view, if needed.
	Toggles the pop-up information windows in IGV on or off.
Zoom slider	Zooms in and out on a chromosome. Sometimes referred to as the "railroad track." more...

Pop-up Menus

To select tracks and display the pop-up menu, do one of the following:

• Right-click a track to select it and display the pop-up menu.
• Right-click an attribute value to select all tracks with that attribute value and display the pop-up menu. Tip: Keep in mind that right-clicking an attribute may select tracks that are not visible in the data panel. Scroll down the data panel to view all the selected tracks.
• Control-click track names (Mac: Command-click) to select the tracks, then right-click one of the selections to display the pop-up menu.

Commands in the track pop-up menu change the display options for the selected tracks. Most changes made via the pop-up menu are lost when you exit IGV unless you save the session. In a few cases, changing the pop-up menu also changes an option in the Preferences window; these changes are persistent.

The type of data displayed in the selected tracks determines which commands appear in the pop-up menu. This page lists commands by track type: data track, feature track, and alignment track. Use your browser's search function to find a particular command.

Data Track

Data tracks display numeric values. For an example, click File>Load from Server and select The Cancer Genome Atlas.GBM.Expression.GBM Batch 1-8 Centered and Normalized (hg18). The following commands appear in the pop-up menu for data tracks:

Feature Track

Feature tracks identify genomic features. For an example, see the Gene track, which IGV loads when you select a genome. The following commands appear in the pop-up menu for feature tracks:

Alignment Track

Alignment tracks display alignments (more...). For an example, select the Human b36 genome, click File>Load from Server and select an alignment from the 1000 Genomes project. Tip: Zoom in to view alignments and the alignment track pop-up menu.

Preferences

To display the Preferences window, click View>Preferences. Preferences are preserved across sessions. To override preferences during a session, use the track display pop-up menu. Each section on this page describes the options on a tab of the Preferences window: General, Tracks, Mutations, Charts, Alignments, Probes, Proxy and Advanced.

General

	Select to distinguish regions with zero values (white) from regions with missing data (gray). Clear (default) to display both regions in the same way (white). Affects only bar charts and scatter plots.
	Select to display all tracks in a single panel. Clear (default) to display data tracks (e.g., expression data) in one panel and feature tracks (e.g., genes) in another.
	Select (default) to show attributes and attribute values to the left of the data panel. Clear to hide the attributes. This option and View>Show Attribute Display have the same effect on attribute display.
	Select to outline the boundaries of regions of interest in black. Clear (default) to leave them without black boundaries.
	Zoom in on search results. When selected (default) the zoom level is automatically adjusted so that the target feature fills the view after a successful search. If not checked, the target feature of a search is centered in the view but the zoom level is unaffected.
	Change this to change the resolution (in base pairs) at which the sequence track becomes visible.
	Change this to define how large a flanking region (in base pairs) IGV will add before and after a feature locus when you zoom to a feature, or when you view gene/loci lists in multiple panels.
	Click here to change the background color of the IGV display.
	Use this to set a default font size for labeling tracks and features.

Tracks

	Default track height for bar charts, scatter plots, and line plots.
	Default track height for all other tracks.
	Name of an attribute in the sample information file. IGV uses the corresponding attribute value as the track name.
	Select to expand feature tracks by default. You may have to restart IGV for this to take effect. Collapsed: Expanded:
	Select (default) to show the "expand/collapse" triangular icon on feature tracks. Collapsed with the icon:                          Expanded with the icon:
	Select to normalize tracks containing coverage data in .tdf files that were created using igvtools.  This normalization option multiplies each value by [1,000,000 / (totalReadCount)].  This is only available for .tdf files created using igvtools builds dated 1/28/2010 or later.  Earlier versions of igvtools did not record the total read count.

Mutations

	Select to overlay mutation data on other tracks. more...
	Name of an attribute column in the sample information file. IGV uses the corresponding attribute values to "link" mutation tracks with other tracks. more...
	Select this to show mutation tracks that are not linked to other tracks, and therefore will not be seen if the overlay option is checked.  This option has no affect if the overlay option is not selected.
	Select to color-code mutation data. Click Choose Colors (or View>Color Legends) to display the Color Legends window, which allows you to view and change mutation color codes.

Charts

	Select to add a border at the top to the track.
	Select to add a border at the bottom of the track.
	Select (default) to color the top and bottom borders (if any). Clear to show the borders in black regardless of the track color. Tip: To change the track color, use the track display pop-up menu.
	Select to label the track with its name, provided the track is at least 25 pixels high.
	Select to label the y-axis with its data range.
	Select (default) to allow charts (barchart, scatterplot, and lineplot) to automatically adjust the plot Y scale to the data range currently in view.  As the user pans and moves, this scaling continually adjusts.  Clear to turn autoscaling off.  There is an option in the popup menu to enable autoscaling for a single track.
	Select (default) to show the range of the data.
	Select to show all features in heatmaps.

The following figures illustrate these track display options.

• Color borders selected (default):
  
• All options selected:
  

Alignments

	Sets the threshold at which IGV displays reads. Reads are visible only when IGV is zoomed in to display a number of bases less than or equal to this threshold.
	Downsampling IGV can randomly sample alignments instead of keeping all of them in memory. The coverage track, displaying total coverage at a region, is unaffected; that is, it always shows unsampled values. Downsample reads: Select to perform downsampling (default). Max read count: The maximum number of reads per window. IGV uses reservoir sampling, so that all reads are kept if the read count is less than Max read count. If the read count is greater, the probability of any given read being sampled is equal to (Max read count) / (actual read count). per window size (bases): Sampling is performed over windows, using the window size specified here.
	Filter and Shading Options Coverage allele-freq threshold: Sets the mismatch threshold at which bases on an alignment coverage track are colored.  The default is 0.2, i.e., if a nucleotide differs from the reference sequence in greater than 20% of quality-weighted reads, IGV colors the bar in the coverage bar chart in proportion to the read count of each base (A, C, G, T). The threshold for an individual track can be changed from the pop-up menu. Filter duplicate reads: Clear to display alignments marked as duplicate reads. Filter vendor failed reads: Select (default) to filter out reads that are marked "vendor failed". Flag unmapped pairs: Select to draw a red box around any paired alignment whose mate is not mapped. Show center line: Select so that, when zoomed in sufficiently, IGV displays a line at the center of the display. At higher resolutions, the center line becomes two lines that frame the aligned bases at the center of the display, as shown in the figure above. Filter alignments by read group: Select to hide alignments that match the read groups listed in the filter file. The filter file is a text file that lists read groups, one per line.  This option means that IGV does not load the alignments associated with these read groups. Mapping quality threshold: Sets a threshold on alignment mapping quality. Only alignments with mapping quality greater than or equal to this threshold are shown. Show coverage track: Select to display a coverage track for each alignment track. The coverage track is visible only when alignments are visible. It displays a gray bar chart showing the depth of the reads at each locus. If a nucleotide differs from the reference sequence in greater than 20% of quality-weighted reads, IGV colors the bar in proportion to the read count of each base (A, C, G, T). Modifying this option affects the display of subsequently loaded alignment tracks. Note, to change the threshold from the default 20%, see Coverage allele-freq threshold. Show soft-clipped bases: Select to show the soft clipped sections of the read. Flag zero-quality alignments: Shade mismatched bases by quality: Select (default) to shade mismatched bases by quality.  The letters representing bases of lower quality will be more transparent, while higher-quality bases will appear more solid.
	Splice Junction Track Options Show junction track: Select to display the splice junction track. Min flanking width: The minimum amount of nucleotide coverage required on both sides of a junction for a read to be associated with the junction. This affects the coverage of displayed junctions, and the display of junctions covered only by reads with small flanking regions. Min junction coverage:  The minimum number of reads associated with a junction required for the junction to be displayed.
	Sets default size thresholds for color-coded flagging of paired end alignments. Only paired end alignments with insert sizes between these thresholds are flagged.  Select Compute to compute selected values from the actual size distribution of each library.

Probes

Select an option to determine how IGV places expression data on the genome:

• Map probes to target loci: Use the probe ID to determine the probe locus and display data at that location. If that fails, map the probe ID to a gene, determine the gene locus, and display data at that location.

• Map probes to genes: Map the probe ID to a gene, determine the gene locus, and display data at that location.

Modifying this option affects the display of subsequently loaded alignment tracks.

Proxy

	Sets proxy parameters for connecting to the Internet.  IGV will use this to load hosted genomes and hosted data sets.
	Select and enter values if a username and password is required for the proxy.
	Clears all proxy settings.

Advanced

	Select this option to enable a port on which IGV listens for commands and http requests. Enabling the port allows control of IGV from a web browser. more...
	Select this option to edit URLs for the IGV data and genome servers. These settings are rarely changed.  IGV caches each genome that it loads. On rare occasions, it may be necessary to clear the cached genome file to display an updated version of the genome. Click Clear Genome Cache to do this. Genome Server URL is the URL for the genome server that populates the genome drop-down list. Data Registry URL is the URL for the hosted data sets registry (populates File>Load from Server dialog).
	Keep this selected to allow IGV to automatically check for updated genomes. Clear to disable this automatic check.
	This allows you to move your default IGV directory.

Color Legends

By default, IGV uses heatmaps to display certain types of data (see Default Display). Use the Color Legends window to change the default colors for these heatmaps.

To change the default colors:

1. Click View>Color Legends to display the Color Legends window.
2. Click a heatmap legend to set its color and range.
3. For LOH and Mutation data, click a colored box to change its color.

Keyboard Shortcuts

There are some useful keyboard shortcuts you can use in IGV.

Sequence Track Options

Flipping the Strand

You can change the strand that is displayed by clicking on the arrow in the title to the left of the track. Note that the sequence and the arrow are only displayed when zoomed in to a sufficiently small region. 

The direction of the arrow indicates which strand is currently displayed. An arrow pointing left indicates that the negative strand is showing. This strand will show the complement nucleotides and reverse complement translations. 

You can also flip the strand by right-clicking on the sequence track and selecting Flip Strand in the track popup menu.

Sequence Translation

With the reference genome sequence track, you can optionally display a 3-band track that shows a 3-frame translation of the amino acid sequence for the corresponding nucleotide sequence. The translation is shown for the strand indicated.

Amino acids are displayed as blocks colored in alternating shades of gray. Methionines are colored green, and all stop codons are colored red. When you zoom all the way in, the amino acid symbols will appear. 

You can toggle the display of this translation track by clicking once, anywhere in the sequence or translation track, or by toggling Show Translation in the track popup menu.

Feature Track Options

Viewing Options for the Feature Track

There are 3 different options for viewing the feature track.  These allow you to display overlapping features, such as different transcripts of a gene, on one line or multiple lines

To change the view of the feature track, right-click on the feature track and select one of the options:

Collapsed

Squished

Expanded

Exon Jumping

This feature is similar to feature jumping.  To feature-jump, you select a feature track and press Ctrl-F for forward, Ctrl-B for back.  To exon-jump, you select a feature track and press SHIFT-Ctrl-F to center the next exon in your view, SHIFT-Ctrl-B to move back one exon.

GFF style tags for BED files

The "name" field (column 4) of a BED file can contain GFF3 style key-value attribute tags by specifying "gffTags=on" on the track line.  These attributes will be displayed in the mouse hover popup text.

Default Display

When you load genomic data, IGV displays the data in horizontal rows called tracks. Typically, each track represents one sample or experiment. For each track, IGV displays the track identifier, one or more attributes, and the data.

When loading a data file, IGV uses the file extension to determine the file format (see File Formats), the file format to determine the data type (Table 1), and the data type to determine the track default display options (Table 2).

Changing the Display

You can override IGV's default display options in several ways:

• Use the track pop-up menu to change the appearance of selected tracks.
• Use the Preferences window to set display preferences for all tracks.
• Use the Color Legends window to set the default data range and color for heatmaps, which IGV uses to display copy number, gene expression, RNAi, methylation, LOH, and mutation data (Table 2).
• For IGV and segmented (SEG, CBS) data files, add a type line to the data file to override the default data type associated with the file format and thus the default display options for the data.
• Add a track line at the top of a data file to specify the display settings for the data.
• Override the default display settings by including display attributes in the sample information file. Note that changes made with this method take precedence over the defaults prescribed by a #type line.  

This section describes a few commonly used display options that apply to all (or most) tracks: graph type, data range, track color, track height, and track names. For information about how to load and display specific types of data, see Viewing Data. For a complete list of display options, review the options available in the pop-up menus, Preferences window, Color Legends window, and the menu bar (View and Tracks menus).

Graph Type

Most tracks are displayed using one of four graph types (the following graphs show the same data):

Heatmap:
Bar chart:
Scatter plot:
Line plot:

IGV determines the default graph type for a track as described in Default Display.

To change the graph type of selected tracks:

• Right-click a track and select a graph type from the pop-up menu.

Data Range

The data range for a track provides the minimum, baseline, and maximum value for the graph, and also whether the scale is linear or logarithmic. IGV determines the default data range for a track as described in Default Display.

To change the data range for selected heat map tracks:

• Right-click a track and select Set Heatmap Scale from the pop-up menu.  The heatmap scale can be set per track.

To change the data range for other selected tracks:

• Right-click a track and select Set Data Range from the pop-up menu.

Changing the data range can significantly affect the data display: 

minimum, baseline, maximum	Result
0,0,3
-1.5,0,1.5
-5,0,5

Track Color

To change the track color for selected heat map tracks:

• Right-click a track and select Set Heatmap Scale from the pop-up menu.

To change the track color for tracks that are displayed as something other than a heatmap (i.e., bar chart, scatter plot, or line plot):

• Right-click a track and from the pop-up menu select either Change Track Color (Positive Values) or Change Track Color (Negative Values).

Track Height

To change the height of selected tracks:

• Use the track pop-up menu.

To change the height of all tracks:

• Select Tracks>Set Track Height and enter a value.

To fit the data to the window:

• Select Tracks>Fit to Window.
  IGV displays all tracks. If necessary, it sets the track height to 1 pixel and scrolls the data.

Track Names

By default, IGV displays track names to the left of the attribute panel. Legibility of the track names depends on track height; for example, track names will not be legible when track height is 1 pixel).

To select the attribute IGV uses as the track name:

• Use the Tracks tab of the Preferences window.

To display the track name as a track label:

• Use the Charts tab of the Preferences window.

To rename a track:

• Right-click a track or a track name, then select Rename Track in the pop-up menu.

You can only rename one track at a time. You can preserve track name changes only by saving the session.

Viewing Options for the Feature Track

There are 3 different options for viewing the feature track.  These allow you to display overlapping features, such as different transcripts of a gene, on one line or multiple lines

To change the view of the feature track, right-click on the feature track and select one of the options:

Collapsed

Squished

Expanded

Expression Data

File Formats

For expression data, use the GCT file format. This a tab-delimited format that contains a row for each probe set ID (or gene), a column for each sample, and expression values for each feature in each sample.

Display Notes

• By default, IGV displays expression data as a blue-to-red heatmap where the data range is -1.5 to 1.5. If loaded expression data appears in tracks colored all red, check the data values and modify the data range as necessary.
• To change track display options, use the track pop-up menu. The commands that appear in the pop-up menu are those relevant to any data track.

Genomic Locations for Probes

To display expression data, IGV must first map the probe set IDs named in the expression data file to their genomic locations. IGV displays data for all of the probes that it can map to genomic locations. If none of the probes in the file can be mapped, IGV displays an error message.

IGV determines the genomic locations for probes as follows:

1. If you use the delimiters |@ and | to specify the probe loci in the file (see the GCT file format), IGV uses the specified loci. Otherwise, it goes to the next step.
2. IGV searches all loaded annotation tracks for each probe. (This is the same as entering the ID in the first column [the Name column] of the file into the search box on the IGV tool bar and clicking Go.) If a probe is found, IGV displays the data at that location. Otherwise, it goes to the next step.
3. IGV searches its probe mapping files for each probe. If a probe is found, IGV determines the probe locus and displays the data at that location. Otherwise, it goes to the next step.
4. IGV uses its gene mapping files to map each probe ID to a gene symbol, determines the gene locus, and displays the data at that location.

Choose preferred mapping: By default, IGV uses its probe mapping files before its gene mapping files. If you prefer to map probes to genes, select the Map probes to genes radio button on the Probes tab of the Preferences window.

Probe Mapping Files

Probe mapping files map probe identifiers to chromosomal locations. They are compiled from source files provided by Affymetrix, Agilent, and Illumina. The Affymetrix and Agilent mapping files are split by species due to their large size. Separate mapping files are provided for human, mouse, and other (non-mouse, non-human) species. Human probe identifiers are mapped to hg18. Depending on the vendor, mouse probe identifiers are mapped to mm9 (Affymetrix), mm5 (Agilent) or mm8 (Illumina).

Following are links to the probe mapping files:

• http://www.broadinstitute.org/igv/resources/probes/affy/affy_human_mappings.txt.gz
• http://www.broadinstitute.org/igv/resources/probes/affy/affy_mouse_mappings.txt.gz
• http://www.broadinstitute.org/igv/resources/probes/affy/affy_other_mappings.txt.gz
• http://www.broadinstitute.org/igv/resources/probes/agilent/agilent_human_mappings.txt.gz
• http://www.broadinstitute.org/igv/resources/probes/agilent/agilent_mouse_mappings.txt.gz
• http://www.broadinstitute.org/igv/resources/probes/agilent/agilent_other_mappings.txt.gz
• http://www.broadinstitute.org/igv/resources/probes/illumina/illumina_allMappings.txt.gz

Gene Mapping Files

Gene mapping files map probe identifiers to gene identifiers. Following are links to the gene mapping files:

• http://www.broadinstitute.org/igv/resources/probes/affy/affy_probe_gene_mapping.txt.gz
• http://www.broadinstitute.org/igv/resources/probes/agilent/agilent_probe_gene_mapping.txt.gz
• http://www.broadinstitute.org/igv/resources/probes/illumina/illumina_probe_gene_mapping.txt.gz

Sources for the Mapping Files

The probe and gene mapping files are compiled from source files provided by Affymetrix, Agilent, and Illumina. A list of the source files is available at http://www.broadinstitute.org/igv/resources/probes/data_sources_for_mapping.txt.

RNAi Data

IGV displays RNAi data similarly to expression data, with one exception: to facilitate analysis of hairpin scores, IGV provides a unique RNAi bar chart. To display the bar chart:

• Right-click an RNAi track and select Bar Chart from the pop-up menu.

The following figure explains how to read the bar chart.

Hover over a track to view hairpin values.

Segmented Data

File Format

For segmented copy number data, use the SEG or CBS file format.

Display Notes

• By default, IGV displays segmented data as a blue-to-red heatmap where the data range is -1.5 to 1.5. If loaded segmented data appears in tracks colored all red, check the data values and modify the data range as necessary.
• To change track display options, use the track pop-up menu. The commands that appear in the pop-up menu are those relevant to any data track.

GWAS Data

IGV can display genome-wide association study (GWAS)  data as a "manhattan plot", color-coded by chromosome.   Data formats are describe here.

The plot represents the significance of the association between a SNP or haplotype and the trait being measured.  The Y-axis shows -log10 transformed P values, which represent the strength of association.

The size of the data points in the plot and their height on the left-hand side of the data pane relate directly to their significance: the larger the point and the higher the point on the scale, the more significant the association with the trait.  You can see the point size difference in the following screenshot of data on chromosome 1.

As in other parts of IGV, hovering over a data point allows you to see a pop-up containing the data specifically associated with that point.  You can see the pop-up for the topmost data point in this image. Note that the point's position on the scale on the left is associated with its P value. 

GWAS Pop-up Menu

 The following commands appear in the pop-up menu for GWAS tracks:

Interpreting Color by Insert Size

The inferred insert size can be used to detect structural variants, such as:

• deletions
• insertions
• inter-chromosomal rearrangements

IGV uses color coding to flag anomalous insert sizes. When you select Color alignments>by insert size in the popup menu, the default coloring scheme is:

• for an inferred insert size that is larger than expected (deletion)
• for an inferred insert size that is smaller than expected (insertion)
• for paired end reads that are coded by the chromosome on which their mates can be found

Deletions

In a deletion a section of DNA is absent in the subject genome compared to the reference genome.

When pairs from a section of DNA spanning the deletion are aligned to the genome the inferred insert size will be larger than expected.  This is due to the deleted section of the genome, not present in the subject.  Schematically this can be visualized as follows:

So in the case of a deletion, the inferred insert size is GREATER THAN the expected insert size.   In IGV such an event might look like the following.

Reads that are colored red have larger than expected inferred sizes, and therefore indicate posibble deletions.

Insertions

In the case of an insertion a section of DNA is present in the subject genome that is not represented in the reference genome.

The affect on distance between aligned pairs is opposite the case of a deletion,  the "inferred insert size" is smaller than expected.

The maximum size of an insertion detectable by insert size anomaly is limited by the size of the fragments.  They must be long enough to span the insertion and include sequence on both ends that are mapped to the reference.  The maximum detectable size is approximately equal to:

fragment length - (2x read length)

Detection of this event is therefore more likely with larger fragment libraries, such as Illumina mate-pair (not paired-end) and SOLID.

In the example above reads that are colored blue have smaller than expected inferred sizes, and therefore indicate insertions.

Inter-chromosomal Rearrangement

IGV codes inserts for inter-chromosomal rearrangements.  For instance, in this case, one end is on chromosome 1 and the other is on chromosome 6.

Interpreting Color by Pair Orientation

The orientation of paired reads can be used to detect structural events including:

• inversions
• duplications
• translocations

By selecting Color alignments>by pair orientation, you can flag anomalous pair orientations in IGV.

Orientation is defined in terms of read-strand: left versus right, and first read versus second read of a pair.

(figure courtesy of Bob Handsaker)

These categories only apply where both mates map to the same chromosome.

Inversions

An inversion is a large section of DNA that is reversed in the subject genome compared to the reference genome.

When an inversion shows up in paired-end reads, the reads are distinctively variant from the reference genome.

This appears in IGV as shown below.

Inverted Duplication

When a large section of DNA is duplicated and inserted into the genome in a reversed configuration compared to the original sequence, this is called an inverted duplication.

There will be overlapping left and right reads, and there will likely be altered coverage depth/copy number.

This appears in IGV as shown below.

Tandem Duplication

When a large section of DNA is duplicated and inserted into the genome next to the original sequence, this is called a tandem duplication.

 The reads will not only be duplicated, but also be arranged as shown below.

IGV will display this rearrangement as shown below.

Translocation on the Same Chromosome

When a large section of DNA is removed from one location and inserted elsewhere, that is a translocation. 

Translocations on the same chromosome can be detected by color-coding for pair orientation, whereas translocations between two chromosomes can be detected by coloring by insert size.

Splice Junctions

The splice junction view displays an alternative representation of .bed files encoding splice junctions, such as the "junctions.bed" file produced by the TopHat program.  This view is enabled by including a track line that specifies either name=junctions or graphType=junctions. TopHat's "junctions.bed" file includes a track line specifying name=junctions by default, so no action is required for these files. Note: The track can also be computed dynamically from an Alignment track by enabling the "Show splice junctions track" option in the alignment preferences.

Junction files should be in the standard .bed format.  The 'score' field is used to indicate depth of coverage.

Each splice junction is represented by an arc from the beginning to the end of the junction.  Junctions from the '+' strand are colored red and extend upward from the center line.  Junctions from the '-' strand are blue and extend downward.  The height of the arc, and its thickness, are proportional to the depth of read coverage.  All junctions with more than 50 reads have the same thickness.  Hovering the mouse over a junction will display the coverage.

Mutation Files

File Formats

Mutation data is loaded from a .mut file.   The resulting values can be visualized as distinct tracks or overlaid on other associated tracks (e.g., expression or SNP data from the same patient).  This association is specified by means of a special "linking" column in a sample information file.   By default IGV looks for a column with the heading LINKING_ID for this association, but the exact heading is configurable as a user preference under the Mutations tab of the Preferences window.   Mutations are overlaid on another track when the values of this column are equal.   A typical use case is to record an identifier identifying a patient, or sample, in this column.

To visualize mutation data:

1. Format mutation data using the MUT file format; e.g., example.mut.
2. Format the data from platform-specific assays using an appropriate file format; e.g., example.gct (expression data) and example.seg (segmented copy number data).
3. Define attributes and their values in a sample information file; e.g., example_sampleinfo_LINKING_ID.txt. A sample information file contains a row for each track and a column for each attribute:

   	The first column contains track identifiers. The track identifier for each mutation track and each associated data track must be included in the sample information file. The track identifiers can be found in the data files (e.g., example.mut, example.gct, and example.seg).
   	Each subsequent column identifies an attribute and its value (if any) for each track. IGV uses the value of one attribute (by default, LINKING_ID) to link mutations to associated data tracks; a mutation track and data track that have the same value for this attribute are linked.

In the example sample information file, the LINKING_ID attribute (2nd column) links the mutation and data tracks. However, in practice, it might be easier to use an existing an attribute rather than adding a LINKING_ID attribute. Notice that, in this example, the LINKING_ID and Sample attributes have the same value. The LINKING_ID attribute could be removed from the sample information file and the Sample attribute used to link the mutation and data tracks. By default, IGV uses the LINKING_ID to overlay mutations on data tracks. If you use an attribute other than LINKING_ID, enter that attribute name on the Mutations tab of the Preferences window. 

Display Notes

By default, IGV displays mutations (variant bases) in distinct tracks and overlaid on associated data tracks. Mutations displayed in distinct tracks are color coded by type (missense, silent, and so on). Mutations overlaid on data tracks are colored black for clarity.

Use the Color Legends window to view or change the mutation color codes.

Use the Mutations tab of the Preferences window to modify other display options for mutations.

VCF Files

VCF stands for Variant Call Format, and this file format is used by the 1000 Genomes project to encode SNPs and other structural genetic variants.  The format is further described on the 1000 Genomes project Web site.  VCF calls are available at EBI / NCBI.

Viewing a VCF File with Genotypes

	Each bar across the top of the plot shows the allele fraction for a single locus.
	The genotypes for each locus in each sample. Dark blue = heterozygous, Cyan = homozygous variant, Grey = reference.  Filtered entries are transparent.

If a file has more than 10 genotypes, the VCF file will be opened in its own pane, with a scroll bar, as shown below.

VCF Popup Menu

To see the options for changing the view of your VCF file, right-click on a variant.  Some of the options are specific to the variant selected.

The window size at which VCF data is loaded is proportional to the number of samples.  To change this, right-click and select Set Feature Visibility Window...

To change the color coding of the plot, select Color By>Allele.

The Sort Variant By options allow you to sort the set by a trait of a specific variant.  You can select the sort twice for the same variant to flip it, i.e., if you sort depth, it sorts from high to low; select the depth sort a second time to sort from low to high.

The Display Mode changes what you can see of the data:

Collapsed removes all the genotypes, leaving only the allele frequency bars.

Expanded shows the genotypes at the usual row height, with the sample names in the first column.

Squished shows the genotypes with the rows compressed to maximize the data visible on the page.

You can also adjust the height of the squished row by right-clicking and selecting Change Squished Row Height. You can change the height of the rows in the window provided.

Viewing a VCF File Without Genotypes

If you open a VCF file that does not contain genotypes data, the view will be different, displaying only the bars marking the calls, as shown below. 

Similarly, the popup menu will be more limited, with only the Set Feature Visibility Window... and Remove Track options functional.

Configuring a Genome Server

To upload a new genome to your own server so you can share it with others:

1. Use the steps here  ("Importing a Genome") to create an initial .genome file and sequence directory.   The product of this step will be a ".genome" file and a sequence directory.  The sequence directory contains a file for each chromosome/contig sequence in the genome. 
2. Copy the sequence directory to a web-accessible directory.
3. Copy the .genome file (which is a zip archive) to a temporary directory and unzip it.
4. Remove the .genome file from the temporary directory.
5. Open the property.txt file in a text editor. The following properties need to be edited: 

   id: Unique identifier for the genome (for example, "hg18"). This property is input to some commands in igvtools.  
   name: This is the name that appears in the users' pull-down genome list in IGV.
   sequenceLocation: http:// <path to sequence directory> (this is the location of the sequence directory discussed in step #1)

6. Zip all the files in the temporary directory, including the edited property.txt file, and name the resulting archive <id>.genome.  This naming convention is mandatory for igvtools.
7. Copy the <id>.genome file to a web-accessible directory.
8. To make your genome appear in the users' pull-down list, you will need to create a genomes list file.  The IGV default genomes list file can be used as a starting point.  Each line in the genomes list is formatted as follows:

        <name> <tab> <URL of the .genome file> <tab> <id>

   for example

        Human hg18  http://www.broadinstitute.org/igvdata/genomes/hg18.genome hg18
    

9. To test in IGV, change the genome URL in the Advanced preferences tab (View>Preferences) to: http://<path to your genomes.txt file>.  You must quit IGV and restart for this preference to take effect.  The genome should appear in the drop-down list.

Configuring a Data Server

By default, the File>Load from Server option in IGV provides access to public datasets stored on the IGV data server. You can host your own web accessible datasets by creating server registry and configuration files.

 To create a custom load from server menu

1. For each top level node in the hierarchy, create an XML file that describes the datafiles accessible under that node.  Each datafile is specified by a Resource element which has 2 attributes: a name to be displayed to the user and a URL to the file.   The resources can be organized into categories, which in turn can be nested to form a tree structure.  An example follows.
   
   <?xml version="1.0" encoding="UTF-8"?>
   <Global name="Example Project"  infolink="http://www.broadinstitute.org/igv/" version="1">
       <Category name="Category">
           <Category name="Subcategory One">
           <Resource name="pi.12mer.tdf"
                     path="http://www.broadinstitute.org/igvdata/annotations/hg18/conservation/pi.12mer.wig.tdf" />
           </Category>
           <Category name="Subcategory One">
           <Resource name="omega.12mer.tdf"
                     path="http://www.broadinstitute.org/igvdata/annotations/hg18/conservation/omega.12mer.tdf" />
           </Category>
       </Category>
   </Global>
   
   The infolink attribute, which displays an information link for the resource, may be included in any <Global> or <Category> element.
   
   
2. Create a registry (text) file that lists the XML files. For example:
   

   http://www.broadinstitute.org/igvdata/annotations/hg18/hg18_annotations.xml
   http://www.broadinstitute.org/igvdata/tcga_external.xml
   http://www.broadinstitute.org/igvdata/mmgp.xml
   http://www.broadinstitute.org/igvdata/epigenetics_public.xml
   http://www.broadinstitute.org/igvdata/1KG/1KG.xml
   http://www.mycompany.org/igvdata/example_project.xml

   
   
3. In IGV, on the Advanced tab of the Preferences window, update the Data Registry URL to point to your registry file.

IGV points to exactly one data registry file. If you'd like your data server to provide access to the public datasets on the IGV data server, include them in your registry file, as shown above.

Password Protected Directories

Overview

When a user enters a password-protected URL, IGV prompts for a user name and password. If the username/password combination is incorrect, IGV will continue to ask the user to authenticate until the combination is entered correctly or the user clicks Cancel.

Verification and Examples

There is an example site so that users can test the password protection feature. Click http://www.broadinstitute.org/igvdata/private/.  IGV should prompt for a username and password.  Enter:

username: guest
password: password

After verifying that server connection and authentication, user can try the following example files in IGV by clicking File>Load from URL:

• http://www.broadinstitute.org/igvdata/private/SignalK562H3k36me3.tdf
• http://www.broadinstitute.org/igvdata/private/cpgIslands.hg18.bed
• http://www.broadinstitute.org/igvdata/private/snp130.bedz
• http://www.broadinstitute.org/igvdata/private/snp130.bedz.sai

Setting Up a Password-protected Site

There are many ways to set up a password-protected site.  The following describes one method of handling this on an Apache server.

Apache

The Apache HTTP Server is a commonly used web server; it is, for example, in use at the Broad Institute. Setting up a password requires:

• an Access File
• a Password File

The Access File (.htaccess) is located in the restricted directory.  It should contain the following information:

AuthUserFile /home/[path]/.htpasswd
AuthName "Private IGV Folder"
AuthType Basic
Require valid-user

The first line should contain the path to the Password File.

The Password File (.htpasswd) should be placed in a directory that is accessible internally, not through the web. This is can be the home directory, but it must be a location that is not externally visible.  An example password file might look like this:

user1:kJs1GPxWtLet2

The file contains the usernames and passwords for all authenticated users, with one user per line. In the example line,  the username is "user1" and the password is "kJx1GPxWtLet2," which is an encrypted password representing the human-readable word, "password."

To make the authentication lines, users can contact IT staff or use one of several websites that help generate them.  The one used for this line was http://www.kxs.net/support/htaccess_pw.html. This website provides a string that can be used in the .htpasswd file.

To test use a web browser to access a file in  the password-protected directory URL.   You should be prompted for a username and password.

Controlling IGV through a Port

IGV can optionally listen for http requests over a port. This option is turned off by default but can be enabled from the Advanced tab of the Preferences window. 

Note:  IGV will write a response back to the port socket upon completion of each command.  It is good practice to read this response before sending the next command.   Failure to do so can overflow the socket buffer and cause IGV to freeze.   See the example below for the recommended pattern.

Commands

Example

Example java code:

        Socket socket = new Socket("127.0.0.1", 60151);
        PrintWriter out = new PrintWriter(socket.getOutputStream(), true);
        BufferedReader in = new BufferedReader(new InputStreamReader(socket.getInputStream()));

        out.println("load na12788.bam,n12788.tdf");
        String response = in.readLine();
        System.out.println(response);

        out.println("genome hg18");
        response = in.readLine();
        System.out.println(response);

        out.println("goto chr1:65,827,301");
        //out.println("goto chr1:65,839,697");
        response = in.readLine();
        System.out.println(response);

        out.println("snapshotDirectory /screenshots");
        response = in.readLine();
        System.out.println(response);

        out.println("snapshot");
        response = in.readLine();
        System.out.println(response);
 

Running IGV with a batch file

As of version 1.5, a user can load a text file to execute a series of sequential tasks by using File>Run Batch Script. The user loads a TXT file that contains a list of commands, one per line, that will be run by IGV.   Arguments are delimited by spaces (NOTE: not tabs).  Lines beginning with # or // are are skipped. See Controlling IGV through a Port for accepted commands.

Example

new
load  myfile.bam
snapshotDirectory mySnapshotDirectory
genome hg18
goto chr1:65,289,335-65,309,335
sort position
collapse
snapshot
goto chr1:113,144,120-113,164,120
sort base
collapse
snapshot
goto chr4:68,457,006-68,467,006
sort strand
collapse
snapshot

The example script does the following:

1. Loads a file.
2. Sets the genome and snapshot directory.
3. Jumps to a specified locus.
4. Sorts, collapses, and then takes a snapshot of the screen.
5. Repeats these steps for other loci.

Running igvtools from the Command Line

Downloading igvtools

The igvtools utilities can be downloaded from the Downloads page on the IGV Web site.

          igvtools_<version #>.zip includes the jar file and shell scripts for running igvtools, as well as the genome files.
          igvtools_nogenomes_<version #>.zip includes the jar file and shell scripts and shell scripts for running igvtools.

Starting with shell scripts

The igvtools utilities can be invoked, with or without the graphical user interface (GUI), from one of the following scripts:

   igvtools (command-line version for linux and  Mac OS 10.x)
   igvtools_gui (gui version for linux and  Mac OS 10.x)

   igvtools.bat (command-line version for windows)
   igvtools_gui.bat (gui version for windows)

The general form of the command-line version is:

   igvtools [command] [options][arguments]
or
   igvtools.bat [command] [options][arguments]

Recognized commands, options, arguments, and file types are described below.

Starting with java

Igvtools can also be started directly using Java.  This option allows more control over Java parameters, such as the maximum memory to allocate.  In this example, igvtools is started with 1500 MB of memory allocated:

   java -Xmx1500m  -Djava.awt.headless=true -jar igvtools.jar [command] [options][arguments]

To start with a GUI the command is

   java -Xmx1500m  -jar igvtools.jar -g

Memory settings

The scripts above allocate a fixed amount of memory.  If this amount is not available on your platform you will get an error along the lines of "Could not start the Virtual Machine".   If this happens you will need to edit the scripts to reduce the amount of memory requested,  or use the Java startup option.  The memory is set via a "-Xmx" parameter. For example  -Xmx1500m requests 1500 MB,  -Xmx1g requests 1 gigabyte.

Genome

The genome argument in the tile and count command can be either an id, or a full path to a .chrom.sizes or an IGV .genome file. 
 

Commands

Tile

The tile command converts a sorted data input file to a binary tiled data (.tdf) file. Use this command to pre-process large datasets for improved IGV performance. 

Supported input file formats are: .wig, .cn, .snp, .igv, and .gct.

Usage:

          igvtools tile [options]  [inputFile] [outputFile] [genome]

Required arguments:

          inputFile    The input file (see supported formats below).

          outputFile   Binary output file.  Must end in ".tdf".

          genome      A genome id or path to a .chrom.sizes or .genome file.  Default is hg18.

Options:

  -z num  Specifies the maximum zoom level to precompute. The default
               value is 7 and is sufficient for most files. To reduce file
               size at the expense of IGV performance this value can be
               reduced.

  -f  list     A comma delimited list specifying window functions to use
               when reducing the data to precomputed tiles.   Possible
               values are min, max, and mean.  By default only the mean
               is calculated.

  -p file    Specifies a "bed" file to be used to map probe identifiers
               to locations.  This option is useful when preprocessing . gct
               files.  The bed file should contain 4 columns:
                           chr start end name
               where name is the probe name in the .gct file.

Example:

          igvtools tile -z 5  copyNumberFile.cn copyNumberFile.tdf hg18

Notes:

Data file formats, with the exception of .gct files, must be sorted by start position.  Files can be sorted with the sort command described below.  Attempting to preprocess an unsorted file will result in an error.

Count

The count command computes average feature density over a specified window size across the genome. Common usages include computing coverage for alignment files and counting hits in Chip-seq experiments. By default, the resulting file will be displayed as a bar chart when loaded into IGV.

Supported input file formats are: .sam, .bam, .aligned, .psl, .pslx, and .bed.

Usage:

          igvtools count [options] [inputFile] [outputFile] [genome]

Required arguments:

          inputFile    The input file (see supported formats above).

          outputFile   Binary output file.  Must end in ".tdf" or ".wig".  To indicate that you want to
                             output both a .tdf and a .wig file, list both output filenames as a single string,
                             separated by a comma with no other delimiters.  To display feature
                             intensity in IGV, the density must be computed with this command, and the
                             resulting file must be named <feature track filename>.tdf.

          genome      A genome id or path to a .chrom.sizes or .genome file.  Default is hg18.

Options:

-z, --maxZoom num

Specifies the maximum zoom level to precompute.

-w, --windowSize num

The window size over which coverage is averaged. Defaults to 25 bp.

 -e, --extFactor num

The read or feature is extended by the specified distance in bp prior to counting. This option is useful for chip-seq and rna-seq applications. The value is generally set to the average fragment length of the library minus the average read length.

--preExtFactor num

The read is extended upstream from the 5' end by the specified distance.

--postExtFactor num

Effectively overrides the read length, defines the downstream extent from the 5' end. Intended for use with preExtFactor.

-f, --windowFunctions list

A comma delimited list specifying window functions to use when reducing the data to precomputed tiles. Possible values are min, max, mean, median, p2, p10, p90, and p98. The "p" values represent percentile, so p2=2nd percentile, etc.

--strands [arg]

By default, counting is combined among both strands. This setting outputs the count for each strand separately. Legal argument values are 'read' or 'first'. 'read' Separates count by 'read' strand, 'first' uses the first in pair strand".  Results are saved in a separate column for .wig output, and a separate track for TDF output.

--bases

Count the occurrence of each base (A,G,C,T,N). Takes no arguments. Results are saved in a separate column for .wig output, and a separate track for TDF output.

--query [querystring]

Only count a specific region. Query string has syntax <chr>:<start>-<end>. e.g. chr1:100-1000. Input file must be indexed. 

--minMapQuality [mqual]

Set the minimum mapping quality of reads to include. Default is 0.

--includeDuplicates

Include duplicate alignments in count. Default false. If this flag is included, duplicates are counted. Takes no arguments

--pairs

Compute coverage from paired alignments counting the entire insert as covered. When using this option only reads marked "proper pairs" are used.

Notes:

The input file must be sorted by start position. See the sort command below.

Example:
          igvtools count -z 5 -w 25 -e 250 alignments.bam  alignments.cov.tdf  hg18

Index

Creates an index for an alignment or  feature file.  Index files are required for loading alignment files into IGV, and can significantly improve performance for large feature files.  Note that the index file is not directly loaded into IGV. Rather, IGV looks for the index file when the alignment or feature file is loaded.  This command does not take an output file argument. Instead, the filename is generated by appending ".sai" (for alignments) or ".idx" (for features) to the input filename as IGV relies on this naming convention to find the index . The input file must be sorted by start position (see sort command, below). 

Supported input file formats are: .sam, .aligned, .vcf, .psl, and .bed.

NOTES:

• This command will not index a binary (BAM) file.  Use the samtools package to sort and index BAM files. 
• The "sai" index is an IGV format, it does not work with samtools or any other application.

Usage:

  igvtools index [inputFile]

Sort

Sorts the input file by start position, as required.

Supported input file formats are: .cn, .igv, .sam, .aligned, .psl, .bed, and .vcf.

NOTE:  This command does not work with BAM files.  The samtools package can be used to sort .bam files.

Usage:

          igvtools  sort [options] [inputFile]  [outputFile]

Required arguments:

          inputFile 

          outputFile 

Options:

  -t tmpdir  Specify a temporary working directory.  For large input files
             this directory will be used to store intermediate results of
             the sort. The default is the users temp directory.

  -m maxRecords  The maximum number of records to keep in memory during the
             sort.  The default value is 500000.  Increase this number
             if you receive "too many open files" errors.   Decrease it
             if you experience "out of memory" errors.

Version

  Prints the igvtools version number to the console.

Running igvtools from the IGV Interface

Select Tools>Run igvtools to open the igvtools window.  This window allows you to run the Tile, Count, Sort, and Index tools:

1. Select the tool that you want from the Command drop-down list.  The Tile tool is selected by default.
2. Specify the necessary files and/or genome.
3. Select any of the alternative options you want.
4. Click Run.

Information about the run will appear in the Messages box.  Note that if you exit the IGV application, any tool that is in progress will be terminated. 

Tile

The Tile tool converts a sorted data input file to a binary tiled data (.tdf) file.  Use this tool to pre-process large datasets for improved IGV performance.

Select:

• the Input File (supported formats are .wig, .cn, .snp, .igv, and .gct)
• the Output File (must end in .tdf)
• the Genome (default is whatever genome is selected in IGV)

Options you can change include:

• Zoom Levels: specifies the maximum zoom level to precompute.  The default is 7; this is sufficient for most files. This value can be reduced to reduce file size, though it will impair IGV performance.
• Window Functions: allows user to select the window functions to use when reducing data to precomputed tiles.  Mean is the default, but you can also select Min, Max, or Median, as well as percentiles of the data.
• Probe to Loci Mapping: specifies a .bed file to be used to map probe identifiers to locations.  This is useful when preprocessing .gct files.  The .bed file should contain 4 columns: chr start end name (where name is the probe name in the .gct file).

Count

Count computes average feature density over a specified window size across the genome. Common usages include computing coverage for alignment files and counting hits in Chip-seq experiments.  By default, the resulting file will be displayed as a bar chart when loaded into IGV.  To display feature intensity in IGV, the density must be computed with this option, and the resulting file must be named <feature track filename>.tdf.

Select:

• the Input File, which must be sorted by start position (see the Sort tool, below). Supported file formats are .sam, .bam, .aligned, .psl, .pslx, and .bed.
• the Output File (must end in .tdf or .wig)
• the Genome (default is whatever genome is selected in IGV)

Options you can change include:

• Zoom Levels: specifies the maximum zoom level to precompute.  The default is 7; this is sufficient for most files. This value can be reduced to reduce file size, though it will impair IGV performance.
• Window Functions: allows user to select the window functions to use when reducing data to precomputed tiles.  Mean is the default, but you can also select Min, Max, or Median, as well as percentiles of the data.
• Window Size: specifies the window size over which coverage is averaged, in base pairs; default is 25 bp

Index

This command creates an index for an alignment file or a feature file.  Index files are required for loading alignment files into IGV, and can significantly improve performance for large feature files. Note that you do not directly load the index file into IGV. Rather, IGV looks for a corresponding index file when the alignment or feature file is loaded.  This command does not take an output file argument. Instead, the filename is generated by appending ".sai" (for alignments) or ".idx" (for features) to the input filename as IGV relies on this naming convention to find the index . The input file must be sorted by start position (see the Sort tool, below).

NOTE: This tool cannot index a binary (BAM) file.   Use the samtools package to sort and index BAM files.

Select the Input File.  Supported file formats are .sam, .aligned, .vcf, .psl, and .bed.

Sort

Sort sorts the input file by start position.

NOTE:  This option does not work with BAM files.  The samtools package can be used to sort .bam files.

Select:

• the Input File. Supported file formats: .cn, .igv, .sam, .aligned, .psl, .bed, and .vcf.
• the Output File

Options you can change include:

• Temp Directory: specifies a temporary working directory.  For large input files, this directory will be used to store intermediate results of the sort. The default is the user's Temp directory.
• Max Records: specifies the maximum number of records to keep in memory during the sort.  The default value is 500000.  Increase this number if you receive "too many open files" errors.   Decrease it if you experience "out of memory" errors.

New File Formats

IGV 2.0 supports a number of new file formats, including:

• Cufflinks files
• Custom file formats (custom specification of columns for the ".igv" file format)
• Goby
• GWAS
• Merged BAM file (.bam.list)
• VCF

New Toolbar Features

	The back and forward buttons allow you to move backward and forward through your views of the genome the way you move back and forward in a web browser.
	The "Fit to Window" button reduces the row height on all tracks to fit all data for the region in view into the window. It will also expand tracks (to their maximum preferred size) to fill the view, if needed.
	The "Popup On/Off" button toggles the pop-up information windows in IGV on or off.

New Sequence Track Pop-up Menu Options

Sort Alignments

There is a new option to sort alignments by insert size.

Set Maximum Coverage Depth...

IGV now allows you to Set maximum coverage depth.  IGV downsamples reads if the depth exceeds that threshold.

Color Alignments

There are now options to color alignments:

• by insert size
• by read group
• by sample

Details About the by insert size Option

IGV uses color coding to flag anomalous insert sizes.

Blue is for inserts that are smaller than expected.  That is, the inferred insert size on the reference genome is smaller than expected given the actual insert size.

Red is for inserts that are larger than expected.  That is, the inferred insert size on the reference genome is larger than expected given the actual insert size.

View As Pairs

For more information on this option, see this page.

View Mate Region in Split Screen

For more information on this option, see this page.

Track Settings

There are now three ways to view the tracks: Collapsed, Squished, or Expanded.

New NGS Functionality

New NGS functionality includes:

• a split-screen view of paired-end reads, invoked by right-clicking over an alignment and selecting View mate region in split screen from the drop-down list
• a view as pairs option, where paired-end reads are drawn as a single "template", with a connecting line joining the two pairs; invoke by right-clicking over the alignments and select View as pairs
• the ability to view splice junctions as an alternative representation of .bed files encoding splice junctions, such as the "junctions.bed" file produced by the TopHat program

Other new functionality is listed below.