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.
In the coverage row, a bar that is part red means that fraction of reads carry a
mismatch (e.g. a T where the reference has an A) at that position. In the
pileup, the same mismatches appear as colored ticks on the otherwise-grey reads.
The track menu's Show coverage and Show pileup toggles turn either panel off independently. Dropping the pileup leaves a compact coverage-only track (handy for surveying depth across many samples), while dropping the coverage row reclaims that vertical space for the reads.
Sorting reads
The quickest way to sort is to right-click a mismatch (or any base) in the pileup and choose Sort by base at position. Reads are then grouped by which nucleotide they carry there, so haplotype-correlated SNPs line up at a glance.
The track menu's Sort by... does the same thing against the center line (a 1bp indicator at the middle of the view), and can also sort by read strand, mapping quality, or any BAM tag.
Two entries in the same menu order the whole layout rather than one column.
Sort by... → Longest reads first gives the widest alignments the lowest
rows, and Sort by... → Spliced reads first does the same for every read
whose CIGAR carries a reference skip (N), so on RNA-seq the junction-spanning
reads sit together at the top of the pileup instead of interleaving with the
unspliced majority.
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
Three schemes surface per-read or per-base signal directly on the pileup:
- Mapping quality shades each read by its MAPQ, so poorly-mapped reads (often in
repeats or segmental duplications) fade out and confidently-placed reads stay
solid. The SAM specification
defines MAPQ as
-10 log10 Pr{mapping position is wrong}, so a MAPQ 0 read is aligned, and drawn where it aligned, with the aligner putting no better than even odds on that being the right copy. Aligners assign it when the best alignment score is tied across positions (Li, Ruan and Durbin 2008, which introduced the estimator). That is separate from a secondary alignment (FLAG0x100), which is one of the competing placements recorded as its own record; JBrowse's defaultflagExcludeof 1540 (duplicate, QC-fail, unmapped) does not filter those out. The mappability QC tutorial works through a locus where MAPQ 0 covers a whole gene. - Per-base quality colors every base by its Phred score on a red→yellow→green ramp (low-quality bases run red, high-quality bases green), which is the quickest way to tell a real variant from a run of low-confidence base calls.
- Per-base lettering draws every aligned base in its nucleotide color, not just the mismatches, turning the whole pileup into a colored base grid at base-pair resolution.
Modifications and methylation
If a BAM/CRAM carries MM/ML modification calls (common in nanopore and PacBio data), Color by → Modifications paints them. It offers two modes:
- One color per modification type draws a mark only where the MM tag reports a modified base, each type in its own color, so an unmethylated region looks empty. Use the Threshold slider to raise the probability cutoff, or Modification types to restrict to a single type such as 5mC (both sit directly beneath the two mode radios).
- One color per type, plus low-probability & unmodified in blue (IGV calls this "2-color") additionally paints the not-modified side blue: modified sites keep their per-type color, while low-probability and unmodified sites turn blue. For methylation (cytosine) data it fills every CpG in context, including the ones the basecaller left implicit, which JBrowse infers from the reference CpG context. The cytosine context (CpG/CHG/CHH) is a Cytosine context submenu in the same list.
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 because the assay adds 6mA to accessible DNA
the density of those calls doubles as a chromatin-accessibility readout. Use
Modification types to restrict the track to one code when the basecaller
emitted several.
Bisulfite and EM-seq
Bisulfite (WGBS) and EM-seq reads carry no MM/ML tags: methylation is encoded in the C→T conversion itself. Color by → Bisulfite / EM-seq reads it straight off the aligned bases against the reference, so a plain BAM from bwameth (or any bisulfite-aware aligner) colors without a methylation caller. Methylated cytosines paint red; Show unmethylated (blue) paints the converted sites too. Pick the cytosine context (CG, CHG, or CHH) from the same submenu, which matters for plant genomes that methylate in all three. The bisulfite tutorial runs the pipeline end to end 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. Reads with an unexpectedly large insert turn red, smaller turn pink, and abnormal pair orientations get their own colors. A combined Insert size and orientation mode paints whichever cue is strongest. The SV visualization guide has the full color tables, the threshold the "expected" insert range is built from, how the combined mode breaks ties, and what each pattern means at a real breakpoint.
By tag
You can color, sort, or filter by any BAM tag. The common case is the HP
(haplotype) tag to see phased reads; grouping by HP (below) usually reads more
clearly than coloring alone. The
phased trio tutorial walks through working with
HP-tagged reads alongside a phased VCF.
Grouping reads
The track menu's Group by... splits the pileup into one coverage+pileup
section per value of a chosen dimension: strand, split read (whether the read
carries an SA tag, which separates the reads crossing a breakpoint from the
ones spanning it intact), read group (RG), or any tag such as HP. Each group
gets a divider label and the groups share one coverage scale, so they read
independently, and reads missing the chosen tag collect in a trailing "none"
section. Grouping costs no extra fetching, and each divider has a control to
collapse its section down to just its coverage.
Grouping by HP is also how you 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 that section's reads, which is how you get strand-split coverage. Group by Strand and turn off Show... → Show pileup, and the band becomes a forward histogram and a reverse histogram on a shared scale, each carrying 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 on a pair of genes transcribed in opposite directions.
On data where read strand carries meaning, the two bands are the whole result. Long-read cDNA is the clearest case: the reads are oriented to the transcript, so a gene's coverage lands in one band and its neighbour's in the other.
The same split read the other way is a check on the reads. Each band's mismatch coloring is computed from only its own strand's reads, so a position colored in one band and not the other is carried by one strand alone, the signature of a systematic basecalling error rather than a variant.
One arrangement of those two moves has a row of its own, under the overlay it builds on. 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 arrives as its own coverage band with its own arcs; SV channels is what the bands say.
Read height and track sizing
The track menu's Read height submenu holds two independent choices: how tall each read is drawn, and how the track absorbs more reads than fit.
The size presets at the top are Normal, Compact, and Super-compact, plus Custom... for an exact pixel height. Each preset's trailing pin makes that height the default for every alignments track; see defaults for all tracks for how pinning works.
Under the Track sizing subheading in the same submenu are three modes. Each label names both halves of what it does: what happens to the read height, then what happens to the track height.
- Fixed read height + fixed track height - reads keep their configured height, the track keeps the height you gave it, and the pileup scrolls when it overflows.
- Fixed read height + autogrow track height - reads keep their height and the track grows to hold them instead of scrolling, up to the growMaxHeight ceiling, past which it scrolls again. At real sequencing depth a pileup passes that ceiling quickly, so raise the slot if you want the track to keep growing.
- Fit read height to track height - the read height is derived from the track height so the whole pileup fits on screen at once, shrinking as coverage deepens and growing back as it thins. Because the size is computed, no size preset reads as selected while fitting; picking one drops back to fixed.
Fit mode is the one to reach for when you care about the shape of a pileup: drag the track taller or shorter and the reads re-fit to whatever height you gave it. It draws reads no taller than the Normal preset, so a shallow pileup in a tall track doesn't balloon, and no smaller than 1px per read, so an extremely deep pileup overflows the display. Grouping interacts with it directly: each group's coverage row is reserved first and only the expanded groups' rows share what's 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 (roughly 30% at high coverage, rising toward 80% at low coverage, to suppress noise).
| 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, most visible with long reads, which span larger insertions.
Soft clipping
When a read has bases at one end that don't align, the aligner can mark them soft-clipped (kept in the read sequence) or hard-clipped (dropped). JBrowse hides soft-clipped bases by default; turn on Show soft clipping from the track menu to reveal them. Clusters of soft-clipped bases often mark a structural-variant breakpoint.
Some reads carry no SEQ field on their record — secondary reads among them —
so there are no clipped bases to draw and their clip indicators appear black.
Filtering reads
The track menu's Filter by... hides reads by SAM flag, for example excluding
duplicates and secondary alignments to clean up a dense pileup, or keeping only
properly-paired reads. You can also filter to a specific read name or tag value
(HP:1 for one haplotype, HP:* for any read carrying the tag), and the
dialog's splicing radios keep only spliced reads (a reference skip, N, in the
CIGAR) or only unspliced ones. The coverage histogram follows the filter, so
"Only spliced reads" leaves a histogram of the junction-spanning evidence alone.
To filter by what a read in front of you actually carries, right-click it and use the Filter submenu: Filter for this read, Filter for this haplotype (HP:n), and Filter for this read group (RG:x) each read their value off that read, so there is nothing to type. They combine rather than replace each other, and Clear read/tag filters appears once any is active.
Sashimi arcs
Sashimi-style arcs are drawn automatically over spliced alignments (reads with
N in the CIGAR), so RNA-seq and Iso-Seq splice junctions appear with no setup.
The arc strand follows whichever strand tag the aligner wrote: XS or TS give
the transcript strand directly, while minimap2's ts gives the orientation
relative to the read and is combined with the read's own strand. A read carrying
none of the three (default STAR output without --outSAMstrandField, for one)
casts no vote, so tagged and untagged reads mix freely on the same arc.
JBrowse also reads the two bases at each end of every intron off the reference sequence and classifies the junction's splice motif: GT-AG, GC-AG or AT-AC on either strand, or non-canonical. The motif shows in the arc's tooltip and detail panel, and a junction none of whose reads carry a strand tag takes the strand its motif implies, so untagged STAR output still colors by strand. This needs the assembly to have a sequence adapter; without one the motif stays unknown.
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 the junctions whose motif is none of the three canonical pairs. On deep RNA-seq the thin arcs are mostly these alignment artefacts, and a read-count floor cannot separate them from a real junction at low depth, so this 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 for a worked splice-junction example.
When one exon-junction peak dominates the coverage histogram behind the arcs, switch the coverage to a log scale via the track menu's Coverage → Scale type → Log scale, so the shallower junctions stay visible.
Read connections
The track menu's Read connections submenu connects paired or split reads, which surfaces the long-range relationships behind structural variants.
Read arcs
Show read arcs draws a bezier curve between the ends of each pair. Long-range and discordant pairs stand out from the short local arcs. A partner the view has not loaded draws as a large semicircular arc reaching toward it. A mate on another chromosome draws as an arc too, when that chromosome is one of the regions on screen, and as a vertical line at the breakpoint when it is not — the line says the connection reaches somewhere this view is not showing. Both can be toggled off. Dragging the track taller re-fits the arcs into the available height.
An arc whose two ends are in different displayed regions spans them, so opening a second region either side of a breakpoint shows the connection as one curve. Interchromosomal arcs are drawn in one colour, since insert size and pair orientation mean nothing across chromosomes.
Reads describing the same connection draw as one arc, thickened by how many of
them there are, the way a sashimi arc is sized by its junction's read count,
so the arcs rank the evidence. Thickness is on a log scale, and a connection
supported by a single read draws at the width
readConnectionsLineWidth
sets. Arcs coalesce only on exactly equal endpoints, so junctions a few bases
apart stay separate curves.
Hovering an arc reports the junction behind it: its location, the distance between the two ends, how many reads support it, and which colour bucket it fell in. In read-cloud mode the tooltip also gives the pair's insert size, which is what that mode plots on the Y axis.
Read cloud
Show read cloud lays pairs out on the Y axis by the log distance between mates, making the insert-size distribution visible at a glance. Patterns that arcs flatten separate clearly, for example short-insert (insertion-supporting) pairs drawn pink lift away from the background.
Going to a read's mate
When a pair is discordant, the question is usually what is at the other end. Right-click a read and open the View mate submenu:
- Split current view to show mate replaces the view's displayed regions with two: the read's locus and its mate's, side by side in the one view, each padded by a read length. An inter-chromosomal mate is simply a second region on another chromosome. A snackbar offers Undo to put the original view back, so this is cheap to try and reverse.
- Open breakpoint split view puts the two loci in their own stacked panels instead, which draws the connecting splines.
The submenu appears only for a read whose mate is mapped.
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 that crosses a structural variant aligns in pieces: the aligner
splits it into a primary alignment plus one supplementary alignment per
additional locus, records the whole set in each record's SA tag, and the
pileup draws them as separate rows, often far apart or on different chromosomes.
Right-click any of them and choose Launch → Linear read vs ref to put them
back together, which the SA tag makes possible from one record. The read
becomes its own assembly along one lane, every reference locus it touches is
laid out along the other, and each alignment segment is drawn as a ribbon
between them, in the order the read visits them rather than in reference order.
An insertion shows as a gap in the diagonal, since those bases are in the read and not in the reference. Dragging over a region in the read lane extracts that sequence.
The companion item Dotplot of read vs ref plots the same alignment as a
dotplot, which reads more clearly when a read visits one locus repeatedly.
See also
- Consensus sequence
- Structural variant visualization
- SV inspector
- 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