Alignments track
TL;DR: An alignments track shows BAM/CRAM reads two ways at once: a coverage histogram on top (read depth at each position) and a pileup below (one box per read). Zoom to base level and most of what you need is already on screen. Almost everything else is a track-menu option that changes how reads are sorted, colored, grouped, sized, or filtered.
A coverage bar that is part red means that fraction of reads carry a mismatch there. The track menu's Show coverage and Show pileup toggles turn either panel off independently: coverage-only is compact for surveying depth across many samples, and pileup-only gives the reads the vertical space.
Sorting reads
Right-click a base in the pileup and choose Sort by base at position. Reads group by the nucleotide they carry there, so haplotype-correlated SNPs line up.
The track menu's Sort by... does the same against the center line (a 1bp
indicator at the middle of the view), and also sorts by strand, mapping quality,
or any BAM tag. Sort by... → Longest reads first and Sort by... → Spliced
reads first order the whole layout instead, putting the widest reads, or the
reads with a reference skip (N) in the CIGAR, at the top.
Color by
The track menu's Color by... offers several schemes.
Strand
| Color | Name | Value | Description |
|---|---|---|---|
| Forward strand | #EC8B8B | Read maps to the forward strand | |
| Reverse strand | #8F8FD8 | Read maps to the reverse strand |
Read quality and bases
- Mapping quality shades each read by its MAPQ, so reads in repeats fade
out. The SAM specification
defines MAPQ as
-10 log10 Pr{mapping position is wrong}, so a MAPQ 0 read is drawn where it aligned with the aligner putting no better than even odds on it being the right copy, which happens when the best score is tied across positions (Li, Ruan and Durbin 2008). A secondary alignment (FLAG0x100) is a competing placement recorded as its own record; the defaultflagExcludeof 1540 (duplicate, QC-fail, unmapped) does not drop those. The mappability QC tutorial works a locus where MAPQ 0 covers a whole gene. - Per-base quality colors every base by Phred score on a red→yellow→green ramp, the quickest way to tell a variant from a run of low-confidence calls.
- Per-base lettering draws every aligned base in its nucleotide color, not just the mismatches.
Modifications and methylation
For a BAM/CRAM with MM/ML modification calls (nanopore, PacBio), Color by → Modifications paints them in two modes:
- One color per modification type marks only where the MM tag reports a modified base, so an unmethylated region looks empty. Threshold raises the probability cutoff and Modification types restricts to one type such as 5mC
- One color per type, plus low-probability & unmodified in blue (IGV's "2-color") also paints the not-modified side blue. For cytosine data it fills every CpG in context, including ones the basecaller left implicit, inferred from the reference. Cytosine context picks CpG/CHG/CHH
See the methylation tutorial for an end-to-end modified-base workflow.
Any type in the MM tag paints, so fiber-seq's N6-methyladenine (A+a) draws
like any other modification, and since the assay adds 6mA to accessible DNA the
call density doubles as a chromatin-accessibility readout.
Bisulfite and EM-seq
Bisulfite (WGBS) and EM-seq reads carry no MM/ML tags; methylation is in the C→T conversion itself. Color by → Bisulfite / EM-seq reads it off the aligned bases against the reference, so a plain BAM from a bisulfite-aware aligner colors without a methylation caller. Methylated cytosines paint red, Show unmethylated (blue) paints the converted sites too, and the same submenu picks the CG, CHG or CHH context, which plant genomes methylate in all three. The bisulfite tutorial runs it on Arabidopsis data.
Pair orientation and insert size
For paired-end data, Color by → Pair orientation and Color by → Insert size highlight discordant pairs, the main way to scan short reads for structural variants: unexpectedly large inserts turn red, small ones pink, and abnormal orientations get their own colors. Insert size and orientation paints whichever cue is strongest. The SV visualization guide has the color tables, the expected-insert threshold, and what each pattern means at a breakpoint.
By tag
Any BAM tag can color, sort, or filter. The common case is the HP haplotype
tag for phased reads, where grouping by HP (below) usually reads more clearly
than coloring alone. See the
phased trio tutorial.
Grouping reads
The track menu's Group by... splits the pileup into one coverage+pileup
section per value of a dimension. It is a radio list, one dimension at a time:
Strand, First-of-pair strand, Pair orientation, Split read (SA
tag) (separating reads crossing a breakpoint from those spanning it intact),
Mapping quality, and Tag..., which opens a dialog for the tag name (HP
for haplotype, RG for read group, or any other). Groups share one coverage
scale and reads missing the tag collect in a trailing "none" section. Grouping
caps at 40 sections; past that the tail merges into one "N merged values"
section, and the tag dialog refuses a tag that would reach the cap, telling you
how many distinct values it found in view first.
Each section is headed by a label chip, and the chip is where the section's height is controlled:
- The chevron collapses that section to just its coverage band, and expands it again.
- Show all reads appears when the section's reads were clipped to fit the shared height budget; it gives that one section the track's full row cap, and turns into Fit to view to hand it back.
- Right-click a chip to hide that section. Its reads leave the shared coverage scale, the legend and the arcs with it, which is how to read the rest of the stack without the section that dominates it. Show... → Show N hidden groups puts them back.
- Dragging the boundary below a section resizes that section alone.
Show... → Collapse groups to one row draws every section as a single row with overlap depth as darker shading, the compact reading for a track with many groups; expanding one section from its chip opts that one back out to a true stack.
These per-section choices are per view: they are not saved to a session or a shared link, and changing the grouping dimension clears them, since a section name means nothing under a different dimension.
Grouping by HP is also how to check that a heterozygous variant's supporting
reads sit on one haplotype; see
phasing heterozygous SVs.
Each section's coverage band is built from only its own reads. Group by Strand and turn off Show... → Show pileup for a forward and a reverse histogram on a shared scale, each with its own mismatch coloring. On a strand-specific paired-end library group by First-of-pair strand instead, since there the transcript strand is which mate the read is; the RNA-seq tutorial shows that. Long-read cDNA is the clearest case, since the reads are oriented to the transcript.
The same split is a check on the reads: a position colored in one band and not the other is carried by one strand alone, the signature of a basecalling error rather than a variant.
Track menu → Read connections → SV channels (pairs by orientation) groups by pair orientation, drops the pileup and turns the arcs on together, so each orientation class is its own coverage band with its own arcs. See SV channels.
Read height and track sizing
The track menu's Read height submenu sets how tall each read is drawn and how the track absorbs more reads than fit. The presets are Normal, Compact and Super-compact, plus Custom... for an exact pixel height. Each preset's pin makes it the default for every alignments track; see defaults for all tracks.
Track sizing in the same submenu has three modes, each label naming what happens to the read height, then to the track height:
- Fixed read height + fixed track height - the pileup scrolls when it overflows
- Fixed read height + autogrow track height - the track grows to hold the reads, up to growMaxHeight, past which it scrolls again. Real sequencing depth passes that ceiling quickly, so raise the slot to keep growing
- Fit read height to track height - the read height is derived from the track height so the whole pileup fits, shrinking as coverage deepens. No preset reads as selected while fitting; picking one drops back to fixed
Fit mode is for the shape of a pileup: drag the track taller or shorter and the reads re-fit. Reads draw no taller than the Normal preset and no smaller than 1px, so an extremely deep pileup still overflows. With grouping, each group's coverage row is reserved first and the expanded groups share what is left, so collapsing a group gives the rest more height.
Insertion and clipping indicators
The coverage row shows an upside-down histogram of insertions and clips, with a colored triangle wherever an event exceeds a depth-dependent fraction of the reads at that base.
| Color | Name | Value | Description |
|---|---|---|---|
| Insertion | #800080 | Reads carry an insertion relative to the reference | |
| Soft clip | #00f | Reads are soft-clipped (clipped bases retained in the read) | |
| Hard clip | #f00 | Reads are hard-clipped (clipped bases removed from the read) | |
| Overlapping segments of one molecule | #555555 | Both reads of a pair, or both arms of a split read, align here — so the junction between them is this span rather than a point |
Insertions larger than 10bp also draw a purple rectangle in the pileup.
Soft clipping
Bases at a read's end that don't align are soft-clipped (kept in the read) or hard-clipped (dropped). Soft-clipped bases are hidden by default; Show soft clipping in the track menu reveals them. Clusters of them often mark a structural-variant breakpoint.
A read with no SEQ field (secondary reads among them) has no clipped bases to
draw, so its clip indicator appears black.
Filtering reads
The track menu's Filter by... hides reads by SAM flag (drop duplicates and
secondaries, or keep only properly-paired reads), by read name, or by tag value
(HP:1 for one haplotype, HP:* for any read carrying the tag). The splicing
radios keep only spliced reads (a reference skip, N, in the CIGAR) or only
unspliced ones. The coverage histogram follows the filter.
Right-click a read for the Filter submenu: Filter for this read, Filter for this haplotype (HP:n) and Filter for this read group (RG:x) read their value off that read. They combine, and Clear read/tag filters appears once any is active.
Sashimi arcs
Sashimi-style arcs draw automatically over spliced alignments (N in the
CIGAR), so RNA-seq and Iso-Seq junctions appear with no setup. The arc strand
follows the aligner's strand tag: XS or TS give the transcript strand,
minimap2's ts is relative to the read and combined with the read's strand, and
a read with none (default STAR output without --outSAMstrandField) casts no
vote.
JBrowse also reads the two bases at each end of every intron off the reference and classifies the splice motif: GT-AG, GC-AG or AT-AC on either strand, or non-canonical. The motif shows in the arc's tooltip, and a junction with no strand-tagged reads takes the strand its motif implies, so untagged STAR output still colors by strand. This needs a sequence adapter on the assembly.
The track menu's Sashimi arcs submenu controls them:
- Show labels prints each junction's supporting-read count on its arc
- Hide non-canonical junctions drops junctions whose motif is none of the three canonical pairs. On deep RNA-seq the thin arcs are mostly these, so it is the filter to reach for first
- Arc placement splits the arcs above/below the coverage row
- Min read support drops the junctions carried by fewer reads than the slider's value
Turn the arcs off from the same submenu. See the RNA-seq tutorial. When one junction peak dominates the coverage histogram, Coverage → Scale type → Log scale keeps the shallower junctions visible.
Read connections
The track menu's Read connections submenu connects paired or split reads, the long-range relationships behind structural variants.
Read arcs
Show read arcs draws a bezier curve between the ends of each pair, so long-range and discordant pairs stand out from the short local arcs. A partner the view has not loaded draws as a large semicircle reaching toward it. A mate on another chromosome draws as an arc when that chromosome is on screen and as a vertical line at the breakpoint when it is not. Both can be toggled off, and dragging the track taller re-fits the arcs.
An arc whose ends are in different displayed regions spans them, so a second region either side of a breakpoint shows the connection as one curve. Interchromosomal arcs draw in one colour, since insert size and orientation mean nothing across chromosomes.
Reads describing the same connection draw as one arc, thickened by how many
there are, on a log scale, so the arcs rank the evidence. A single-read
connection draws at
readConnectionsLineWidth.
Arcs coalesce only on exactly equal endpoints.
Hovering an arc reports its location, the distance between the ends, the supporting read count and its colour bucket. In read-cloud mode it also gives the insert size.
Read cloud
Show read cloud lays pairs out on the Y axis by the log distance between mates, so the insert-size distribution is visible directly and short-insert (insertion-supporting) pairs lift away from the background.
Going to a read's mate
Right-click a read and open the View mate submenu, present when the mate is mapped:
- Split current view to show mate replaces the displayed regions with the read's locus and its mate's side by side, each padded by a read length. A snackbar offers Undo
- Open breakpoint split view puts the two loci in their own stacked panels, which draws the connecting splines
For a split read, Split current view to show split alignments does the same
with one region per segment of its SA tag, in read order, and turns on View
as pairs / link supplementary alignments; Undo restores both.
One read against the reference
A long read crossing a structural variant aligns in pieces: a primary alignment
plus one supplementary per additional locus, the whole set recorded in each
record's SA tag, drawn as separate rows in the pileup.
Right-click any of them and choose Launch → Linear read vs ref to put them back together. The read becomes its own assembly along one lane, every reference locus it touches lies along the other, and each alignment segment is a ribbon between them in the order the read visits them. An insertion shows as a gap in the diagonal. Dragging over the read lane extracts that sequence.
Dotplot of read vs ref plots the same alignment as a dotplot, clearer when a
read visits one locus repeatedly.
See also
- Consensus sequence
- Structural variant visualization
- SV inspector
- User guide: Variant track
- Alignments track configuration
- LinearAlignmentsDisplay config schema
- Gallery: alignments and long reads
- MODIFICATION_TAGS.md — how this repo reads MM/ML base-modification tags, checked line by line against htslib, and the one place it deliberately differs
- DEEP_COVERAGE.md — what these defaults do at 300x, where the insert-size cut flags a tight library's own tail, and why a support floor has to count over a window