BAM Pileup Panel
Look at the reads in a BAM file inside Visual Studio Code, on the machine where the BAM is.
- Pileup. Reads packed into rows, coloured by strand, mapping quality or read group.
Mismatches, insertions, deletions and, if asked, soft clips.
- Coverage. Depth per base, from every read in the region. Positions where another
base is over 20 % of the reads are marked.
- Locus box.
chr20:1,000,000-1,002,000, 20:1000000, or a gene name when an
annotation file is set. chr20 and 20 are treated as the same name, and the panel
says when it did that.
- Reference. A FASTA with a
.fai. Only the bases on screen are read. Without one,
mismatches come from the reads' MD tags, and the caption says so.
- Header and file report. Sort order, index kind and age, references, read groups,
programs, whether the file ends properly, whether the reference names match the FASTA.
- Exports. The reads of the region as CSV. The picture as a standalone SVG for a
figure.
Price
Free. No paid tier, no key, no account. Every command works for everyone.
What it is for, and what it is not
It is for looking: is the alignment there, is this variant real, what does this region
look like. It does not call variants, does not edit, and never writes to a BAM or an index.
CRAM is out of scope for this release. CRAM needs its reference resolved by MD5,
which is a separate problem. SAM text files are out of scope too. A BAM must be
coordinate-sorted and indexed (.bai or .csi): this extension will not scan a whole
file to make up for a missing index, and says what to run instead.
Large files and remote files
Only the blocks the index points at are read. Measured on a 318 MB human BAM: opening it
and drawing a 2 kb region read 1,440,829 bytes in all, 0.45 % of the file. The region
alone was 471,923 bytes. The summary line of the panel shows the bytes read for every region.
Under Remote-SSH the extension runs on the remote machine. Measured over a real SSH
connection: 16,396 bytes crossed the wire to draw that region. The BAM does not.
| Setting |
What happens above it |
bamPileup.maxReadsPerRegion (5,000) |
A fixed sample is drawn, chosen by read name, the same every time. The fraction is stated. Coverage still counts every read. |
bamPileup.maxRegionBases (100,000) |
Reads are not drawn. Coverage only, read in windows. A 10 Mb region of a 4× genome takes under a second. |
Things it tells you rather than hides
- No index: which names it looked for, and the
samtools index command.
- An index older than its BAM: a warning above the reads, because a stale index returns
reads from the wrong places with no error.
- A truncated BAM: what the index can reach is shown. A region in the missing part says so.
- A name-sorted or unsorted BAM: refused, with the header line that says so.
- A reference whose names or lengths do not match the BAM:
NAMES DISAGREE, in the panel
and in the file report.
- An annotation for a different assembly: refused when its
##sequence-region lines
disagree with the BAM's header.
- Mismatches too small to draw at the current zoom: not drawn, and the caption says to
look at the coverage track.
Commands
BAM: Open pileup · BAM: Go to locus… · BAM: Set reference FASTA… · BAM: Set annotation file… · BAM: Export reads in region as CSV · BAM: Export pileup as SVG ·
BAM: Show header and references · BAM: File report
Settings
bamPileup.maxReadsPerRegion, bamPileup.maxRegionBases, bamPileup.referencePath,
bamPileup.indexPath, bamPileup.colorBy, bamPileup.showSoftClips,
bamPileup.minMappingQuality, bamPileup.rowHeight.
Where it runs
In the extension host: under Remote-SSH that is the machine where the data is. Works
offline. No server, no account, no telemetry. No WebGL: the pileup is SVG, so it works
over a remote desktop with no GPU.
Third-party software
BAM and index decoding is @gmod/bam 9.0.1, MIT, bundled with six packages it depends
on. Their licence texts are in THIRD-PARTY-NOTICES.txt, which ships in the package.
