Alignments

Open a BAM/CRAM track with a chosen display, group reads by SAM tag, and set the display options up front.

Initialize an alignments display

An init.tracks entry can be an object rather than a trackId string, carrying a displaySnapshot — the initial display state, read once at startup. That matters most on alignments tracks, whose display has a large configuration surface (height, showSoftClipping, colorBy here).

The keys come from LinearAlignmentsDisplay, and the track-level slots from AlignmentsTrack. See advanced init for the general displaySnapshot / trackSnapshot shape.

View source — 47 lines

import { LinearGenomeView } from '@jbrowse/react-linear-genome-view2'

const cramTrackId = 'NA12878.alt_bwamem_GRCh38DH.20150826.CEU.exome'

const tracks = [
  {
    type: 'AlignmentsTrack',
    trackId: cramTrackId,
    name: 'NA12878 Exome',
    assemblyNames: ['GRCh38'],
    adapter: {
      type: 'CramAdapter',
      uri: 'https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/alignments/NA12878/NA12878.alt_bwamem_GRCh38DH.20150826.CEU.exome.cram',
    },
  },
]

// managed API: props are initial values, the component owns the engine
export default function WithInitAlignmentsDisplay() {
  return (
    <LinearGenomeView
      assembly={{
        name: 'GRCh38',
        aliases: ['hg38'],
        uri: 'https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/fasta/GRCh38.fa.gz',
        refNameAliases: {
          uri: 'https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt',
        },
      }}
      tracks={tracks}
      init={{
        loc: '1:100,987,200..100,987,450',
        tracks: [
          {
            trackId: cramTrackId,
            displaySnapshot: {
              type: 'LinearAlignmentsDisplay',
              height: 250,
              showSoftClipping: true,
              colorBy: { type: 'pairOrientation' },
            },
          },
        ],
      }}
    />
  )
}

Group alignments by tag

groupBy splits a pileup into labeled lanes, each laid out independently — by haplotype (HP), cell barcode, or any tag the BAM/CRAM carries. Pairing colorBy on the same tag shades each lane distinctly, so HP:0, HP:1 and the unassigned reads read apart at a glance.

Both are LinearAlignmentsDisplay slots, set here as a displaySnapshot on an init.tracks entry. See custom display options for the rest of them.

View source — 42 lines

import { LinearGenomeView } from '@jbrowse/react-linear-genome-view2'

// managed API: props are initial values, the component owns the engine
export default function WithGroupByTag() {
  return (
    <LinearGenomeView
      assembly={{
        name: 'volvox',
        uri: 'https://jbrowse.org/genomes/volvox/volvox.2bit',
      }}
      tracks={[
        {
          type: 'AlignmentsTrack',
          trackId: 'volvox_bam',
          name: 'volvox-sorted.bam',
          assemblyNames: ['volvox'],
          adapter: {
            type: 'BamAdapter',
            uri: 'https://jbrowse.org/code/jb2/main/test_data/volvox/volvox-sorted.bam',
          },
        },
      ]}
      init={{
        loc: 'ctgA:39,728..40,459',
        tracks: [
          {
            trackId: 'volvox_bam',
            // colorBy + groupBy are alignments config slots. pairing them on the
            // same tag colors each haplotype distinctly within its group.
            // increase height so all groups (HP:0, HP:1, unassigned) are visible
            displaySnapshot: {
              type: 'LinearAlignmentsDisplay',
              height: 400,
              colorBy: { type: 'tag', tag: 'HP' },
              groupBy: { type: 'tag', tag: 'HP' },
            },
          },
        ],
      }}
    />
  )
}

Custom alignments display options

HG002 haplotagged nanopore reads at the imprinted SNRPN locus. The reads carry an HP tag, so coloring and grouping by it stacks the two parental alleles into separate lanes.

An AlignmentsTrack draws through a LinearAlignmentsDisplay, configured up front in init.tracks[].displaySnapshot (below) or via displayDefaults, and changeable afterwards from the track menu. The slots worth knowing:

colorBy — { type, tag? }, where type is strand, pairOrientation, insertSize, modifications, tag, … (the config page linked above carries the current enum; restating it here would drift the first time one is added)
groupBy — stacked lanes, e.g. { type: 'tag', tag: 'HP' }
filterBy — SAM flags plus read-name/tag filters, e.g. { flagInclude: 0, flagExclude: 3844 }
sortedBy — read order at a position, usually set by right-clicking a column
showSoftClipping, showCoverage, mismatchAlpha — clipped bases, the coverage band, quality-faded mismatches
height, featureHeight, heightMode
linkedReads, readConnections — long-read and paired-read chaining

The always-current list is the generated config and state model pages. These reads also carry 5mC calls; the DNA methylation tutorial covers per-read, aggregate and allele-specific methylation.

View source — 55 lines

import { LinearGenomeView } from '@jbrowse/react-linear-genome-view2'

// GRCh38 (hg38). The hosted alias file maps chr-prefixed names onto the fasta's
// bare "1".."22" refNames, so navigating with `chr15` resolves.
const assembly = {
  name: 'GRCh38',
  aliases: ['hg38'],
  uri: 'https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/fasta/GRCh38.fa.gz',
  refNameAliases: {
    uri: 'https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt',
  },
}

// HG002 nanopore reads at the imprinted SNRPN locus, basecalled with 5mC
// modification tags (MM/ML) and haplotagged (HP tag).
const tracks = [
  {
    type: 'AlignmentsTrack',
    trackId: 'hg002_snrpn_5mc',
    name: 'HG002 SNRPN 5mC (haplotagged nanopore)',
    assemblyNames: ['GRCh38'],
    adapter: {
      type: 'BamAdapter',
      uri: 'https://jbrowse.org/demos/methylation/HG002_SNRPN_5mC_haplotagged.bam',
    },
  },
]

export default function WithAlignmentsDisplayOptions() {
  return (
    <LinearGenomeView
      assembly={assembly}
      tracks={tracks}
      init={{
        loc: 'chr15:24,954,000..24,972,000',
        tracks: [
          {
            trackId: 'hg002_snrpn_5mc',
            // Every key in displaySnapshot below is a LinearAlignmentsDisplay
            // config slot. Coloring and grouping reads by their HP (haplotype)
            // tag stacks the two alleles at the imprinted SNRPN locus into
            // separate, distinctly-colored groups. See the config/model docs
            // linked from the writeup for the full option set.
            displaySnapshot: {
              type: 'LinearAlignmentsDisplay',
              height: 500,
              colorBy: { type: 'tag', tag: 'HP' },
              groupBy: { type: 'tag', tag: 'HP' },
            },
          },
        ],
      }}
    />
  )
}