Overview

The CRAM format is a compressed column-oriented file format for storing read alignments. It is significantly smaller than BAM, making it ideal for large genomic datasets. igvR supports CRAM visualization via the CramTrack class.

Important Note: Unlike BAM files, which igvR can load from local file paths, CRAM files must be loaded via a URL (HTTP/HTTPS). This is due to the underlying igv.js library requiring HTTP Range Requests to efficiently stream portions of the highly compressed CRAM data, a feature not currently supported by igvR’s internal data server.

This vignette demonstrates: 1. Loading a remote CRAM file (from the 1000 Genomes Project). 2. The workaround for visualizing local CRAM files using a simple local web server.

Load the libraries

library(igvR)

Initialize igvR

igv <- igvR()
setBrowserWindowTitle(igv, "CRAM Demo")
setGenome(igv, "hg19")

Scenario 1: Loading a Remote CRAM File

If your CRAM file is already hosted on a web server (Amazon S3, Google Cloud, EBI, or your own nginx/Apache server), you can load it directly by providing the URLs for the .cram file and its index (.cram.crai).

Here we use a public exome alignment from the 1000 Genomes Project.

# 1000 Genomes Phase 3 Exome alignment (hg19)
cram.url <- "https://ftp.1000genomes.ebi.ac.uk/vol1/ftp/phase3/data/HG00096/exome_alignment/HG00096.mapped.ILLUMINA.bwa.GBR.exome.20120522.bam.cram"
index.url <- "https://ftp.1000genomes.ebi.ac.uk/vol1/ftp/phase3/data/HG00096/exome_alignment/HG00096.mapped.ILLUMINA.bwa.GBR.exome.20120522.bam.cram.crai"

track <- CramTrack(trackName = "Remote CRAM (HG00096)",
                   cramUrl = cram.url,
                   indexUrl = index.url)

displayTrack(igv, track)

# Zoom into a region with known coverage (e.g., HLA-A)
showGenomicRegion(igv, "chr6:29,909,000-29,915,000")

Scenario 2: Visualizing Local CRAM Files

As noted above, you cannot simply pass a file path like "/path/to/my.cram" to CramTrack. Attempts to do so will result in the track loading but displaying empty alignments, or an error.

To view local files, you must “serve” the directory containing your files using a lightweight local web server.

Step 1: Start a Local Web Server

Open your terminal (outside of R) and navigate to the directory containing your CRAM and CRAI files. Run one of the following commands to start a simple server on port 8000:

Using Python 3:

cd /path/to/your/cram/files
python -m http.server 8000

Using Python 2:

cd /path/to/your/cram/files
python -m SimpleHTTPServer 8000

Note: Ensure you have permissions to bind to this port and that your firewall allows local connections.

Step 2: Load the Track using “localhost”

Once the server is running, your files are accessible at http://localhost:8000/your_file.cram. You can now use this URL in igvR.

# Assuming you started the server in the directory containing 'my_sample.cram'
local.cram.url <- "http://localhost:8000/my_sample.cram"
local.index.url <- "http://localhost:8000/my_sample.cram.crai"

track <- CramTrack(trackName = "Local CRAM (via localhost)",
                   cramUrl = local.cram.url,
                   indexUrl = local.index.url)

displayTrack(igv, track)

Session Info

sessionInfo()

Visualizing CRAM Alignments