Integrative Genomics Viewer (IGV)

IGV supports loading public data files hosted in Amazon S3 buckets using HTTPS endpoints.

For authenticated access using s3:// URLs, you have two options:

1. OAuth via Cognito: Enable OAuth access using the UMCCR contributed AWS configuration option.
2. AWS Credentials: Set your AWS credentials and region information locally following standard AWS SDK for Java patterns.

Detailed guides for Cognito setup can be found in the UMCCR documentation for both backend and frontend provisioning.

IGV can leverage BEDTools to perform genomic data analysis on tracks currently in view.

Requirements:

1. Separate Installation: BEDTools is not bundled with IGV and must be installed on your system independently.
2. Permissions: The user account running IGV must have the necessary execution permissions for the BEDTools binaries.

Once configured, IGV provides access to several BEDTools commands to analyze overlapping or nearby features between tracks.

To build IGV, you must have Java 21 installed (though later versions may work). Builds are executed from the project root and output files to the build subdirectory.

Prerequisites:

• Java 21
• Gradle installed for your platform

Note for Windows users: Use ./gradlew.bat instead of ./gradlew.

# Build a distribution directory
./gradlew createDist

# Run the test suite
./gradlew test

Prerequisites

• Java 17 or greater is required. You can obtain a free open-source distribution from Adoptium.

Installation Steps

1. Download and unzip the IGV distribution file to your preferred directory.
2. Execute one of the following launcher scripts from your terminal/command line:

Windows:

• igv-launcher.bat (Standard GUI launch)
• igv.bat (For batch jobs)

Linux and macOS:

• igv.sh (Standard launch)
• igv_hidpi.sh (For Linux with HiDPI displays)
• igv.command (macOS: double-click to start)

Note: If the script fails to run on Linux/macOS, you may need to make it executable using chmod a+x <script_name>.

chmod a+x igv.sh
./igv.sh

To adjust the UI scaling on HiDPI displays, you can modify the scaling factor. While the igv_hidpi.sh script is pre-configured for 2x scaling, it is recommended to use the java_arguments file instead. This allows the standard igv.sh to work correctly on HiDPI screens without needing a specific script.

Scaling Options

• The scaling is controlled via the -Dsun.java2d.uiScale parameter.
• Supported values: Integer values only (e.g., 2, 4).
• Note: Fractional values are NOT supported.

Implementation

Add the following line to your java_arguments file ($HOME/.igv/java_arguments or %USERPROFILE%/.igv/java_arguments):

-Dsun.java2d.uiScale=4

By default, IGV launcher scripts are configured to start with 4GB of memory. If you are working with very large datasets, you can increase this limit by creating or editing the java_arguments file.

Configuration File Locations

• macOS and Linux: $HOME/.igv/java_arguments
• Windows: %USERPROFILE%/.igv/java_arguments

How to use

1. Create the file if it does not exist.
2. Add the -Xmx parameter. By default, this line is commented out with a #.
3. Uncomment the line and set your desired memory (e.g., 8g for 8 GB).

Example for 8 GB of memory:

-Xmx8g

IGV provides access to the following BEDTools operations for analyzing data in view:

• intersect: Identifies regions of overlapping features in two tracks. Note that IGV uses the -split flag, meaning exons are treated as separate features.
• subtract: Removes regions in one track from another. (e.g., subtracting a gene track from a feature track to find regions NOT in a gene).
• closest: For each feature in the first track, finds the closest matching feature in the second track (which may be an overlapping feature).
• window: Similar to intersect, but expands each feature in the first track by a specified number of base pairs (defaulting to 1000 bp) upstream and downstream to detect "near" features in the second track.
• coverage: Calculates the coverage of track A by track B.

The org.igv.ui.Main.Version class allows you to parse and compare IGV version strings that follow Microsoft versioning conventions (e.g., 2.3.27).

Use Version.getVersion(String versionString) to create a Version instance, and lessThan(Version anotherVersion) to perform comparisons.

// Example parsing and comparing versions
Main.Version v1 = Main.Version.getVersion("2.3.27");
Main.Version v2 = Main.Version.getVersion("2.3.28");

if (v1.lessThan(v2)) {
    // v1 is older than v2
}

Use the org.igv.ui.Main.main(String[] args) method to launch IGV as a standalone application in its own window. This method initializes the environment, sets up the look and feel, and handles command-line arguments.

public static void main(final String args[])