Reviewing a whole SV callset

A somatic structural-variant caller reports junctions, points where two distant loci are joined, and we'll check each one in the COLO829 callset against the tumor and normal reads. We:

• render every junction as an image with jb2export batch
• render the matched normal the same way, as the control
• sort the calls with the manifest
• render a three-chromosome rearrangement with jb2export breakpoint

Prerequisites#

• @jbrowse/img, which puts jb2export on your PATH
• a JBrowse for the last section (Web or Desktop)

npm install -g @jbrowse/img

The data#

The COLO829 somatic SV callset comes from the ONT open-data release's wf-somatic-variation run (Valle-Inclán et al. 2022), rehosted alongside the cancer SV demo. The first command downloads the VCF, and every command streams the reads by URL.

Rendering every tumor junction with jb2export batch#

We'll start with jb2export batch, which renders one image per record. An event on one chromosome gets a single row, and a junction between two chromosomes gets a breakpoint split view with one panel per chromosome.

curl -fO https://jbrowse.org/demos/cancer_sv/COLO829.somatic-sv.vcf.gz
# --track: the track id, then display settings as key:value pairs
# --flank: bases drawn either side of each breakend
# --manifest: writes manifest.tsv beside the images
jb2export batch --sites COLO829.somatic-sv.vcf.gz \
  --config https://jbrowse.org/demos/cancer_sv/config.json --assembly hg38 \
  --track COLO829_tumor_ont height:240 \
  --outDir tumor --flank 600 --width 1100 --manifest

Each image is named 002_chr1_33053494-chr6_2919922_r_0_0.png: the record's index in the callset, its coordinates, and the caller's ID where it has one.

For your own callset, point --config at a JBrowse config with the assembly and an alignments track whose reads have an index (.bai or .crai) beside them. The VCF's chromosome names must match the assembly's:

# --dryRun: list each row's file and loci without rendering
# --limit: render only the first rows; a later --resume run keeps them
# --passOnly: drop records the caller filtered out
# --jobs: render processes, about a gigabyte each
jb2export batch --sites calls.vcf.gz \
  --config your/config.json --assembly <assemblyName> --track <trackId> \
  --outDir out --passOnly --limit 20

Rendering the matched normal as the control#

Next we'll render the matched normal into a second directory. Each call keeps its file name across tumor/ and normal/:

jb2export batch --sites COLO829.somatic-sv.vcf.gz \
  --config https://jbrowse.org/demos/cancer_sv/config.json --assembly hg38 \
  --track COLO829BL_normal_ont height:240 \
  --outDir normal --flank 600 --width 1100 --manifest

✕

Agent

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

The figure stacks 6 frames: one command draws each, and ImageMagick stacks them.

Frame 1

Copy

npx @jbrowse/img breakpoint \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 \
  --track COLO829_tumor_ont force:true height:240 \
  --loc chr7:104844021-104845221 \
  --loc chr7:104971255-104972455 \
  --width 1100 \
  --out frame-1.png

Frame 2

Copy

npx @jbrowse/img breakpoint \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 \
  --track COLO829BL_normal_ont force:true height:240 \
  --loc chr7:104844021-104845221 \
  --loc chr7:104971255-104972455 \
  --width 1100 \
  --out frame-2.png

Frame 3

Copy

npx @jbrowse/img breakpoint \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 \
  --track COLO829_tumor_ont force:true height:240 \
  --loc chr1:168054750-168055950 \
  --loc chr19:23849782-23850982 \
  --width 1100 \
  --out frame-3.png

Frame 4

Copy

npx @jbrowse/img breakpoint \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 \
  --track COLO829BL_normal_ont force:true height:240 \
  --loc chr1:168054750-168055950 \
  --loc chr19:23849782-23850982 \
  --width 1100 \
  --out frame-4.png

Frame 5

Copy

npx @jbrowse/img breakpoint \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 \
  --track COLO829_tumor_ont force:true height:240 \
  --loc chr2:20405166-20406366 \
  --loc chr2:20408103-20409303 \
  --width 1100 \
  --out frame-5.png

Frame 6

Copy

npx @jbrowse/img breakpoint \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 \
  --track COLO829BL_normal_ont force:true height:240 \
  --loc chr2:20405166-20406366 \
  --loc chr2:20408103-20409303 \
  --width 1100 \
  --out frame-6.png

Copy

magick frame-1.png frame-2.png -bordercolor white -border 12 +append stack-1.png
magick frame-3.png frame-4.png -bordercolor white -border 12 +append stack-2.png
magick frame-5.png frame-6.png -bordercolor white -border 12 +append stack-3.png
magick stack-1.png stack-2.png stack-3.png -background white -smush 40 figure.png

The figure's callouts across its frames are drawn over the stacked image, which these commands leave out.

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

The caller filed 009_chr1_168055349-chr19_23850381 as somatic, but the normal has the same curves, so the junction is germline.

Sorting the calls with the manifest#

Each manifest.tsv row describes one image:

• links counts the split reads with pieces in more than one window. Sort tumor/manifest.tsv on it to put the unsupported calls first; re-render one with a wider --flank before calling it false.
• alt holds, for an SNV, indel, <DEL> or <INS>, the reads carrying the ALT over the reads covering it (17/41). A deletion that one alignment holds has its reads here and a links of zero.
• spec is the view as a session spec that opens the same windows in JBrowse.
• line is the record's line in the VCF, to join a row back to the callset.

A dense fan in a region of ragged coverage is usually a repeat, since a read mismapped there draws a curve like any other.

Rendering a three-chromosome rearrangement#

COLO829's der(3) joins pieces of chr3, chr10 and chr12, and its reads visit all three. We'll render it with jb2export breakpoint, one --loc per panel, then run the same command with COLO829BL_normal_ont as the control:

# featureHeight:super-compact draws each read 1 px tall
jb2export breakpoint \
  --config https://jbrowse.org/demos/cancer_sv/config.json --assembly hg38 \
  --track COLO829_tumor_ont height:130 force:true featureHeight:super-compact \
  --loc chr3:25,358,511-25,359,711 \
  --loc chr10:58,716,962-58,718,162 \
  --loc chr12:72,272,512-72,273,712 \
  --width 1000 --out der3_tumor.png

✕

Agent

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

The figure stacks 3 frames: one command draws each, and ImageMagick stacks them.

Frame 1

Copy

npx @jbrowse/img breakpoint \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 \
  --track COLO829_tumor_ont height:130 force:true featureHeight:super-compact \
  --loc chr3:25,358,511-25,359,711 \
  --loc chr10:58,716,962-58,718,162 \
  --loc chr12:72,272,512-72,273,712 \
  --width 1000 \
  --out frame-1.png

Frame 2

Copy

npx @jbrowse/img breakpoint \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 \
  --track COLO829BL_normal_ont height:130 force:true featureHeight:super-compact \
  --loc chr3:25,358,511-25,359,711 \
  --loc chr10:58,716,962-58,718,162 \
  --loc chr12:72,272,512-72,273,712 \
  --width 1000 \
  --out frame-2.png

Frame 3

Copy

npx @jbrowse/img --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly der3_RARB_BICC1_TRHDE \
  --track der3_segments height:128 \
  --track reads_vs_der3 height:440 \
  --loc der3_RARB_BICC1_TRHDE:1-39,549 \
  --width 1000 \
  --out frame-3.png

Copy

magick frame-1.png frame-2.png frame-3.png -bordercolor white -border 12 +append figure.png

The figure's callouts across its frames are drawn over the stacked image, which these commands leave out.

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

The complex rearrangements tutorial builds the reconstructed contig on the right.

Opening a call in the browser#

Take the coordinates from an image's filename, open the SV inspector on the same VCF, and click through to the breakpoint split view, which adds the gene track and read details.

Rendering calls from other SV callers#

jb2export batch and jb2export breakpoint read any caller that writes breakends or symbolic SVs (such as <DEL>) to a VCF:

• cuteSV, Sniffles, pbsv, Delly, Manta and GRIDSS write a VCF that --sites reads directly.
• LINX writes clusters and chained links as TSVs. Convert the junction columns to the six BEDPE columns with awk and pass the .bedpe file as --sites.
• To draw PURPLE's copy-number segments under the reads, convert them to a bedGraph, run bedGraphToBigWig, and pass the result as --bigwig.

A caller that groups one rearrangement's junctions under VCF 4.4's EVENT key, as DRAGEN and the C-GIAB benchmark do, gets the der(3) image from batch itself, which renders each event visiting more than two loci once more as event_<n>_<label>. Severus writes the grouping as CLUSTERID, which the SV inspector guide renames to EVENT.

See also#

• Tutorial: Complex rearrangements and derivative alleles
• Tutorial: Structural variants (Cancer GIAB) part 1: breakpoints
• Tutorial: Low-mappability regions (SMN)
• User guide: SV inspector view
• User guide: SV visualization
• Docs: Static image export (@jbrowse/img)

Citations#

• Valle-Inclán et al. (2022). A multi-platform reference for somatic structural variation detection

Feedback on this tutorial is welcome: contact us.