@gmod/jbrowse/docs/site/config_alignments.md

JBrowse - client-side genome browser

---
id: alignments
title: Alignments tracks
---

# Alignment Tracks (BAM and CRAM)

JBrowse has several track types that are designed for displaying alignment data, particularly from BAM and CRAM files. BAM and CRAM files used with JBrowse must be compressed and sorted by leftmost coordinate.

The JBrowse BAM parsing library makes extensive use of code from [BioDalliance](http://www.biodalliance.org/), while the CRAM support is based on the `@gmod/cram` npm module.

## Alignments2

Introduced in JBrowse 1.8.0, `Alignments2` tracks are designed to display alignment data, such as from BAM files. This track type shows basepair-level mismatches, insertions, deletions, and skipped regions between aligned reads and the reference, and highlights paired reads in red if their mates are missing.

Base mismatches are displayed based on the contents of the feature's `MD` field (containing a BAM MD mismatch string), and/or `CIGAR` field. If your BAM file does not contain MD tags, one common way to generate them is with the `samtools calmd` command.

`Alignments2` is a faster implementation of the older `Alignments` track type that draws alignments using the HTML5 canvas. In the interest of speed, `Alignments2` tracks do not display any text labels or descriptions alongside features, and do not draw arrowheads indicating strandedness, instead relying on color to denote the strand of alignments.

`Alignments2` tracks support the same advanced clicking behavior as CanvasFeatures tracks, but does not support right-click menus.

The most basic Alignments2 track configuration in tracks.conf format is

   [tracks.alignments]
   urlTemplate=FM.01.new.sorted.chr11.bam
   type=Alignments2


The above track template infers that the storeClass is a BAM store. Not all track and store types can do this inference but Alignments2 allows this


### List of configuration options

|Option|Value|
|------|-----|
|`maxHeight`|Available in JBrowse 1.9.0 and later. Maximum displayed height of the track in pixels. Defaults to 1000. Features that would cause the track to grow taller than the `maxHeight` are not shown. If a section of a track has features that are not drawn because of a `maxHeight` constraint, a notification is displayed at the bottom of that track section.|
|`style→color`|HTML-style color for drawn alignments. By default, this varies with the alignment's strandedness, and whether its mate pair is missing, using the `style→color_fwd_strand`, `style→color_rev_strand`, and `style→color_missing_mate` variables. To gain complete control over the displayed color, you could set this to be a function callback.|
|`style→color_fwd_strand`|HTML-style color for alignments on the forward strand. Default \#EC8B8B, which is a light red.|
|`style→color_rev_strand`|HTML-style color for alignments on the reverse strand. Default \#898FD8, which is a light blue.|
|`style→color_missing_mate`|HTML-style color for alignments with a missing mate. Default \#D11919, which is a dark red.|
|`style→height`|Height in pixels of each alignment. Default 7.|
|`style→marginBotton`|Number of pixels of vertical spacing to put on the bottom of each alignment. Default 1.|
|`style→showMismatches`|If true, draw mismatches (SNPs, insertions, deletions, skips) on the alignent. Default true.|
|`style→mismatchFont`|CSS string describing the font to use for labeling mismatches. Default "bold 10px Courier New,monospace".|
|`histograms.storeClass`|A store class for summary histograms used for the Alignments2 track. Usually JBrowse/Store/SeqFeature/BigWig. Can be used on any CanvasFeatures-type track but generally used in Alignments2 tracks|
|`histograms.urlTemplate`|Path to a histogram file (such as a BigWig) to be used for summary histograms used for the Alignments2 track. Can be used on any CanvasFeatures-type track but generally used in Alignments2 tracks|
|`histograms.color`|Color for the histograms e.g. "purple". Default is orange. Can be used on any CanvasFeatures-type track but generally used in Alignments2 tracks|
|`histograms.binsPerBlock`|"Granularity" of the bins in histogram. Default is 200 for Alignments2 tracks. Default is 25 on other CanvasFeatures type tracks.|
|`hideDuplicateReads`|Hide duplicate reads to the same location. Default: true|
|`hideQCFailingReads`|Hide QC failing reads that did not pass some aligner quality. Default: true|
|`hideSecondary`|Hide secondary reads which mapped to multiple locations. Default: true|
|`hideUnmapped`|Hide unmapped reads. Default: true|
|`hideMissingMatepairs`|If a read is missing a mate pair or paired-end match, hide the read. Default: false|
|`hideForwardStrand`|Hide all reads from the forward strand. Default: false|
|`hideReverseStrand`|Hide all reads from the reverse strand. Default: false|
|`useReverseTemplate`|Use an algorithm for reversing the template of paired-end reads so that they appear on the same strand. Default: false. Added in 1.11.6|
|`useReverseTemplateOption`|Present a checkbox to the user for changing the "Use reverse template" option. Default: true. Added in 1.11.6|
|`useXS`|Use an algorithm for only coloring reads when the XS tag indicates strandedness. Default: false. Added in 1.11.6|
|`useXSOption`|Present a checkbox to the user for changing the "Use XS" option. Default: true. Added in 1.11.6|
|`cacheMismatches`|Cache mismatch calculations so that long reads are faster to browser. Default: false. Added in 1.12.3|
|`renderAlignments`|Add a text display of the BAM alignment on a single line in the View details popup. Default: false|
|`renderPrettyAlignments`|Add a text display of the BAM alignment using prettier "BLAST style" to the View details popup. Default: false|

### Alignments2 coloring schemes

Since JBrowse 1.11.3, there is a new coloring scheme for BAM files that allows for new coloring of paired end reads, such as a different coloring for unpaired reads and aberrant pairing split across chromosomes.

The coloring styles that can be configured for the Alignments2 track are as follows

|Option|
|------|
|`style→color_fwd_strand`|1.  EC8B8B (original red)|
|`style→color_rev_strand`|1.  8F8FD8 (original blue)|
|`style→color_fwd_missing_mate`|1.  D11919 (hard red)|
|`style→color_rev_missing_mate`|1.  1919D1 (hard blue)|
|`style→color_fwd_strand_not_proper`|1.  ECC8C8 (light red)|
|`style→color_rev_strand_not_proper`|1.  BEBED8 (light blue)|
|`style→color_fwd_diff_chr`|1.  000000 (black)|
|`style→color_rev_diff_chr`|1.  969696 (gray)|
|`style→color_nostrand`|1.  999999 (gray) Added in 1.11.6|

If this scheme is undesirable, the style-\>color variable can be overridden entirely as well, with a callback for example

## SNPCoverage

Introduced in JBrowse 1.8.0, `SNPCoverage` tracks draw the coverage of alignment features along the genome, along with a graphical representation of base-mismatch (possible SNP) distribution, and tables showing frequencies for each mismatching base.

Like the other alignment tracks, base mismatches are displayed based on the contents of the feature's `MD` field (containing a BAM MD mismatch string).

**Note: Since the SNPCoverage track dynamically calculates coverage and putative SNPs directly from alignment data, it is not recommended for use with very dense feature data, such as deep-coverage BAM files.** For these types of files, it's recommended to pre-generate a BigWig file of the coverage and a VCF file of putative SNPs, and display those instead.

![800px|thumb|center|A SNPCoverage track with corresponding Alignments2 track.](assets/config/JBrowse_SNP_Coverage.png)

### Example SNPCoverage Configuration

In your data/tracks.conf file:

    [tracks.my-bam-coverage-track]
    storeClass = JBrowse/Store/SeqFeature/BAM
    urlTemplate = volvox-sorted.bam
    type = JBrowse/View/Track/SNPCoverage
    metadata.Description = SNP/Coverage view of volvox-sorted.bam, simulated resequencing alignments.
    key = BAM - volvox-sorted SNPs/Coverage

Note that urlTemplate will refer to a file relative to the "data" directory that you are using.

## Alignments

Introduced in JBrowse 1.7.0, `Alignments` tracks are an HTML-based track type for alignment display. They display everything that `Alignments2` do, and also can be configured with right-click menus and strand arrowheads.

They display everything that `Alignments2` tracks do, plus they support the same configuration options as feature tracks, including advanced clicking behavior, feature modification callbacks, and so forth. The price of this additional capability is that `Alignments` tracks are **significantly slower** when used with dense data such as deep BAM alignments.

`Alignments2` is recommended over `Alignments` for most users.

![center|1124px|border|JBrowse displaying short-read alignments](assets/config/JBrowse_alignment_and_coverage.png)


## BAM Data Configuration Options

|Option|Value|
|------|-----|
|`urlTemplate`|URL for the BAM file to display.|
|`baiUrlTemplate`|URL for the corresponding BAM index (BAI) file. If not set, this is assumed to be the same URL as `urlTemplate` with `.bai` appended.|
|`chunkSizeLimit`|Maximum size in bytes of BAM chunks that the browser will try to deal with. Default 5000000 (5 MiB). When this is exceeded, most tracks will display some kind of "Too much data" message. If you increase this, be careful. You could blow up your web browser.|

`Note: you can also increase maxFeatureScreenDensity if you get the "Too much data to show; zoom in to see detail".`

## Example BAM Alignments2 track configuration

~~~~ {.javascript}
      {
         "storeClass"  : "JBrowse/Store/SeqFeature/BAM",
         "urlTemplate" : "../../raw/volvox/volvox-sorted.bam",
         "label"       : "volvox-sorted.bam",
         "type"        : "JBrowse/View/Track/Alignments2"
      },

~~~~

## Apache Configuration Note

If you are using the Apache web server, please be aware that the module `mime_magic` can cause BAM files to be served incorrectly. Usually, the error in the web developer console will be something like "Not a BAM file". Some packaged versions of Apache, particularly on Red Hat or CentOS-based systems, are configured with this module turned on by default. We recommend you deactivate this Apache module for the server or directory used to serve JBrowse files. If you do not want to deactivate this module for the entire server, try adding this line to your HTTPD config or .htaccess file:

`   AddType application/octet-stream .bam .bami .bai`