Complex rearrangements and derivative alleles
The tutorials target the JBrowse v5 beta, and the v4.3.0 release
on the download page lacks some of what they show. To install the
beta of JBrowse Web, run npm install -g @jbrowse/cli@next, then
jbrowse create jbrowse2 --branch v5.0.0-beta.22. Desktop beta builds for Linux and
macOS are on the releases page;
the Windows build waits on code signing.
A cancer genome can stitch several distant pieces of the genome into one molecule through a chain of junctions. A short read spans one junction at most; a long read can cross several, and the reads crossing all of them can be assembled into the rearranged chromosome itself. We follow one such chain across chr3, chr10 and chr12 in the COLO829 melanoma cell line. We:
- load tumor and normal long reads with the somatic SV calls, and sort split reads first at the chr3 breakpoints
- open a breakpoint split view from a breakend's right-click menu, following the chain to all three loci
- load the derivative allele assembled from the spanning reads as an assembly, with a synteny track against GRCh38
- open both in a linear synteny view with the realigned reads and the truth-set VCF
Prerequisites
- a JBrowse to open them in: Desktop takes a local file by path, Web through Add track
- Command line tools (JBrowse CLI)
- samtools (v1.21 or later)
- minimap2
bedGraphToBigWigfrom the UCSC utilitiespython3- a GRCh38 FASTA, and roughly 40 GB of free disk
# Debian/Ubuntu
sudo apt install samtools tabix minimap2 nodejs
# or conda, which has every tool above
conda install -c bioconda -c conda-forge samtools htslib minimap2 nodejs \
ucsc-bedgraphtobigwig
# or Linux x86_64 binaries for the tools apt lacks
wget -P ~/.local/bin \
https://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/bedGraphToBigWig
chmod +x ~/.local/bin/bedGraphToBigWig
# any platform
npm install -g @jbrowse/cli@nextThe data
All but the last file come from the ONT COLO829 open-data release and its
wf-somatic-variation run; the last is the multi-platform truth set
(Valle-Inclán et al. 2022).
The read and SV call tracks read these files by URL. The derivative-allele
tracks read local files that the build script
writes, so run it first, or swap the uri for your own sample's reads and
follow The derivative allele to assemble a contig from them.
| What it is | File |
|---|---|
| COLO829 tumor reads (ONT R10, haplotagged), streamed and never downloaded | COLO829_tumor.ht.cram |
| COLO829BL matched normal reads, streamed and never downloaded | PAU59807.d052sup4305mCG_5hmCGvHg38.bam |
| The somatic SV calls this page works from | COLO829.wf-somatic-sv.vcf.gz |
| Mosdepth coverage regions, tumor | COLO829_tumor.regions.bed.gz |
| Mosdepth coverage regions, normal | COLO829_normal.regions.bed.gz |
| The GRCh38 build the CRAM decodes against, and the der(3) (derivative chromosome 3) contig aligns to | GCA_000001405.15_GRCh38_no_alt_analysis_set.fasta |
| The COLO829 somatic SV truth set, lifted to GRCh38 | content |
Tumor and normal coverage as bigWigs
The demo config also has tumor and normal coverage tracks, for a chromosome-wide
look at where the tumor gained and lost. They are the wf-somatic-variation
run's mosdepth output in 50 kb windows, converted to bigWig the same way for
each sample:
curl -O https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.chrom.sizes
# awk keeps the contigs in hg38.chrom.sizes; bedGraphToBigWig fails on any other
gzip -dc COLO829_tumor.regions.bed.gz | sort -k1,1 -k2,2n |
awk 'NR==FNR{ok[$1];next} ($1 in ok)' hg38.chrom.sizes - > cov.bg
bedGraphToBigWig cov.bg hg38.chrom.sizes COLO829_tumor.coverage.bwThe rearrangement chain across chr3, chr10 and chr12
The chain is COLO829's der(3), a derivative chromosome 3 built from pieces of three chromosomes, whose three junctions close a triangle across chr3, chr10 and chr121:
chr3:25,359,111 <-> chr12:72,273,112
chr3:25,359,568 <-> chr10:58,717,464
chr10:58,717,662 <-> chr12:72,273,294The genes at the junctions are RARB (a tumor suppressor) on chr3, BICC1 on chr10, and TRHDE on chr12.
Tumor and normal reads at the chr3 breakpoints
The ONT reads are aligned to GRCh38, so we load that assembly and the two read
tracks. Each read file needs its index beside it, a .crai for the CRAM and a
.bai for the BAM; for your own sample, swap the uri:
Goes in the assemblies array of config.json. See Assemblies.
{
"name": "hg38",
"uri": "https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz",
"refNameAliases": {
"uri": "https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt"
},
"cytobands": "https://jbrowse.org/genomes/GRCh38/cytoBand.txt"
}Edits config.json in the current folder, creating it if there is none. See JBrowse CLI with Desktop.
jbrowse add-assembly https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz \
--name hg38 \
--refNameAliases https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt \
--config '{"cytobands":"https://jbrowse.org/genomes/GRCh38/cytoBand.txt"}'hg38 is one of the genomes JBrowse Desktop hosts, with gene tracks already set up: on the start screen click Browse hosted genomes and pick it. To load the files of this config instead:
In JBrowse Desktop, Open your own genome on the start screen (or File → Open genome... in a session), then Open from a URL and paste, one per line:
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.fai
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.gziJBrowse reads the format off the file name. Then fill in:
- Genome name:
hg38 - refName aliases (under More options):
https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt - cytobands (under More options):
https://jbrowse.org/genomes/GRCh38/cytoBand.txt
Goes in the tracks array of config.json. See Tracks.
{
"trackId": "COLO829_tumor_ont",
"name": "COLO829 tumor (ONT R10)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829_tumor.ht.cram",
"assemblyNames": ["hg38"]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829_tumor.ht.cram \
--trackId COLO829_tumor_ont \
--name "COLO829 tumor (ONT R10)" \
--assemblyNames hg38In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:
- Main file:
https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829_tumor.ht.cram
JBrowse reads the adapter and track type off the file name. Then fill in:
- Track name:
COLO829 tumor (ONT R10) - Assembly:
hg38
Click Add.
Open this track in JBrowse Web ↗
Needs JBrowse Desktop 5.0 or newer. If nothing opens, copy the link and paste it into Desktop's Open JBrowse Web link..., on the start screen or under File → Session.
https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg38%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22trackId%22%3A%22COLO829_tumor_ont%22%2C%22name%22%3A%22COLO829+tumor+%28ONT+R10%29%22%2C%22uri%22%3A%22https%3A%2F%2Font-open-data.s3.amazonaws.com%2Fcolo829_2024.03%2Fwf_somatic_variation%2Fsup%2FCOLO829_tumor.ht.cram%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr3%3A25%2C357%2C600-25%2C361%2C000%22%2C%22tracks%22%3A%5B%22COLO829_tumor_ont%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+COLO829+tumor+%28ONT+R10%29This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.
from jbrowse_anywidget import JBrowseApp, fetch_hub
config = fetch_hub("https://jbrowse.org/ucsc/hg38/config.json")
app = JBrowseApp(
assemblies=config["assemblies"],
tracks=config.get("tracks", []) + [
{
"trackId": "COLO829_tumor_ont",
"name": "COLO829 tumor (ONT R10)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829_tumor.ht.cram",
"assemblyNames": [
"hg38"
]
}
],
views=[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr3:25,357,600-25,361,000",
"tracks": [
"COLO829_tumor_ont"
]
}
],
)
app # display the widgetThis view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.
import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'
const configUrl = "https://jbrowse.org/ucsc/hg38/config.json"
const configPromise = fetch(configUrl)
.then(res => res.json())
.then(config => {
addRelativeUris(config, new URL(configUrl))
return config
})
export default function Figure() {
const config = use(configPromise)
return (
<JBrowse
assemblies={config.assemblies}
tracks={[...(config.tracks ?? []), ...[
{
"trackId": "COLO829_tumor_ont",
"name": "COLO829 tumor (ONT R10)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829_tumor.ht.cram",
"assemblyNames": [
"hg38"
]
}
]]}
aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
configuration={config.configuration}
views={[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr3:25,357,600-25,361,000",
"tracks": [
"COLO829_tumor_ont"
]
}
]}
/>
)
}jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.
cat > tracks.json <<'JSON'
[
{
"trackId": "COLO829_tumor_ont",
"name": "COLO829 tumor (ONT R10)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829_tumor.ht.cram",
"assemblyNames": [
"hg38"
]
}
]
JSON
npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
--trackConfigs tracks.json \
--assembly hg38 --loc chr3:25,357,600-25,361,000 \
--track COLO829_tumor_ont \
--out figure.svgFor a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).
Goes in the tracks array of config.json. See Tracks.
{
"trackId": "COLO829BL_normal_ont",
"name": "COLO829BL matched normal (ONT R10)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/basecalls/colo829bl/sup/PAU59807.d052sup4305mCG_5hmCGvHg38.bam",
"assemblyNames": ["hg38"]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track https://ont-open-data.s3.amazonaws.com/colo829_2024.03/basecalls/colo829bl/sup/PAU59807.d052sup4305mCG_5hmCGvHg38.bam \
--trackId COLO829BL_normal_ont \
--name "COLO829BL matched normal (ONT R10)" \
--assemblyNames hg38In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:
- Main file:
https://ont-open-data.s3.amazonaws.com/colo829_2024.03/basecalls/colo829bl/sup/PAU59807.d052sup4305mCG_5hmCGvHg38.bam
JBrowse reads the adapter and track type off the file name. Then fill in:
- Track name:
COLO829BL matched normal (ONT R10) - Assembly:
hg38
Click Add.
Open this track in JBrowse Web ↗
Needs JBrowse Desktop 5.0 or newer. If nothing opens, copy the link and paste it into Desktop's Open JBrowse Web link..., on the start screen or under File → Session.
https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg38%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22trackId%22%3A%22COLO829BL_normal_ont%22%2C%22name%22%3A%22COLO829BL+matched+normal+%28ONT+R10%29%22%2C%22uri%22%3A%22https%3A%2F%2Font-open-data.s3.amazonaws.com%2Fcolo829_2024.03%2Fbasecalls%2Fcolo829bl%2Fsup%2FPAU59807.d052sup4305mCG_5hmCGvHg38.bam%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr3%3A25%2C357%2C600-25%2C361%2C000%22%2C%22tracks%22%3A%5B%22COLO829BL_normal_ont%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+COLO829BL+matched+normal+%28ONT+R10%29This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.
from jbrowse_anywidget import JBrowseApp, fetch_hub
config = fetch_hub("https://jbrowse.org/ucsc/hg38/config.json")
app = JBrowseApp(
assemblies=config["assemblies"],
tracks=config.get("tracks", []) + [
{
"trackId": "COLO829BL_normal_ont",
"name": "COLO829BL matched normal (ONT R10)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/basecalls/colo829bl/sup/PAU59807.d052sup4305mCG_5hmCGvHg38.bam",
"assemblyNames": [
"hg38"
]
}
],
views=[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr3:25,357,600-25,361,000",
"tracks": [
"COLO829BL_normal_ont"
]
}
],
)
app # display the widgetThis view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.
import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'
const configUrl = "https://jbrowse.org/ucsc/hg38/config.json"
const configPromise = fetch(configUrl)
.then(res => res.json())
.then(config => {
addRelativeUris(config, new URL(configUrl))
return config
})
export default function Figure() {
const config = use(configPromise)
return (
<JBrowse
assemblies={config.assemblies}
tracks={[...(config.tracks ?? []), ...[
{
"trackId": "COLO829BL_normal_ont",
"name": "COLO829BL matched normal (ONT R10)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/basecalls/colo829bl/sup/PAU59807.d052sup4305mCG_5hmCGvHg38.bam",
"assemblyNames": [
"hg38"
]
}
]]}
aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
configuration={config.configuration}
views={[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr3:25,357,600-25,361,000",
"tracks": [
"COLO829BL_normal_ont"
]
}
]}
/>
)
}jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.
cat > tracks.json <<'JSON'
[
{
"trackId": "COLO829BL_normal_ont",
"name": "COLO829BL matched normal (ONT R10)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/basecalls/colo829bl/sup/PAU59807.d052sup4305mCG_5hmCGvHg38.bam",
"assemblyNames": [
"hg38"
]
}
]
JSON
npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
--trackConfigs tracks.json \
--assembly hg38 --loc chr3:25,357,600-25,361,000 \
--track COLO829BL_normal_ont \
--out figure.svgFor a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).
The breakends come from the run's somatic SV calls, which need their .tbi
beside them:
Goes in the tracks array of config.json. See Tracks.
{
"trackId": "COLO829_somatic_sv",
"name": "COLO829 somatic SVs (nanomonsv)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829.wf-somatic-sv.vcf.gz",
"assemblyNames": ["hg38"]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829.wf-somatic-sv.vcf.gz \
--trackId COLO829_somatic_sv \
--name "COLO829 somatic SVs (nanomonsv)" \
--assemblyNames hg38In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:
- Main file:
https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829.wf-somatic-sv.vcf.gz
JBrowse reads the adapter and track type off the file name. Then fill in:
- Track name:
COLO829 somatic SVs (nanomonsv) - Assembly:
hg38
Click Add.
Open this track in JBrowse Web ↗
Needs JBrowse Desktop 5.0 or newer. If nothing opens, copy the link and paste it into Desktop's Open JBrowse Web link..., on the start screen or under File → Session.
https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg38%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22trackId%22%3A%22COLO829_somatic_sv%22%2C%22name%22%3A%22COLO829+somatic+SVs+%28nanomonsv%29%22%2C%22uri%22%3A%22https%3A%2F%2Font-open-data.s3.amazonaws.com%2Fcolo829_2024.03%2Fwf_somatic_variation%2Fsup%2FCOLO829.wf-somatic-sv.vcf.gz%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr3%3A25%2C357%2C600-25%2C361%2C000%22%2C%22tracks%22%3A%5B%22COLO829_somatic_sv%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+COLO829+somatic+SVs+%28nanomonsv%29This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.
from jbrowse_anywidget import JBrowseApp, fetch_hub
config = fetch_hub("https://jbrowse.org/ucsc/hg38/config.json")
app = JBrowseApp(
assemblies=config["assemblies"],
tracks=config.get("tracks", []) + [
{
"trackId": "COLO829_somatic_sv",
"name": "COLO829 somatic SVs (nanomonsv)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829.wf-somatic-sv.vcf.gz",
"assemblyNames": [
"hg38"
]
}
],
views=[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr3:25,357,600-25,361,000",
"tracks": [
"COLO829_somatic_sv"
]
}
],
)
app # display the widgetThis view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.
import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'
const configUrl = "https://jbrowse.org/ucsc/hg38/config.json"
const configPromise = fetch(configUrl)
.then(res => res.json())
.then(config => {
addRelativeUris(config, new URL(configUrl))
return config
})
export default function Figure() {
const config = use(configPromise)
return (
<JBrowse
assemblies={config.assemblies}
tracks={[...(config.tracks ?? []), ...[
{
"trackId": "COLO829_somatic_sv",
"name": "COLO829 somatic SVs (nanomonsv)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829.wf-somatic-sv.vcf.gz",
"assemblyNames": [
"hg38"
]
}
]]}
aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
configuration={config.configuration}
views={[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr3:25,357,600-25,361,000",
"tracks": [
"COLO829_somatic_sv"
]
}
]}
/>
)
}jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.
cat > tracks.json <<'JSON'
[
{
"trackId": "COLO829_somatic_sv",
"name": "COLO829 somatic SVs (nanomonsv)",
"uri": "https://ont-open-data.s3.amazonaws.com/colo829_2024.03/wf_somatic_variation/sup/COLO829.wf-somatic-sv.vcf.gz",
"assemblyNames": [
"hg38"
]
}
]
JSON
npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
--trackConfigs tracks.json \
--assembly hg38 --loc chr3:25,357,600-25,361,000 \
--track COLO829_somatic_sv \
--out figure.svgFor a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).
Open the SV calls and the tumor and normal read tracks at
chr3:25,357,600-25,361,000. Every tumor read crossing the junction continues
on another chromosome, so its end here is soft clipping, a stretch the aligner
left unaligned. In each read track's menu:
- Show → Show soft clipping draws the clipped ends, which are off by default.
- Sort by → Split reads first lifts the reads that continue on another chromosome to the top of the pileup.
- Force load approves the download when the track asks first because the pileup is deep, and holds for the rest of the session.
Following the chain across breakpoint split view panels
A breakpoint split view stacks the loci a rearrangement visits, one panel per locus, and draws the reads that leave one panel and arrive in another. There are two ways to open one:
- Add → Breakpoint split view builds it from loci you already know, one row per panel.
- Right-click a record in the variant track and choose Open breakpoint split view. The dialog asks for the layout (two stacked panels, or one row spanning both breakends) and the window each panel opens at.
A breakend (BND) record names one partner, so opening the view from one record gives two panels. Check Follow further breakends at each end to add the rest of the chain:
- The dialog searches the callset at each end for another junction leaving from the same place and adds it when exactly one exists.
- The search stops at a locus with two candidates, or at one leading back into the chain.
- The search assumes two junctions leaving one locus belong to one molecule, and reads crossing both are the evidence.
- From the chr3 record this chain starts at, the search finds three panels: the chr10 breakend has a second junction a couple of hundred bases away, and its far end is on chr12.
To follow a single read, right-click it and choose Linear read vs ref.... JBrowse opens a synteny view with the read as an assembly along the bottom and every locus it touches along the top, the layout Ribbon (Nattestad et al. 2021) introduced.
Assembling the der(3) derivative allele and aligning it to GRCh38
The split view shows each read in pieces across three panels. Assembling the reads that span all three loci gives the der(3) allele as one contig, every base of it from those reads; the cancer SV demo config, https://jbrowse.org/demos/cancer_sv/config.json, includes the published one.
To build one from your own data, pull the reads crossing the loci with
samtools view, assemble them with
Flye,
Shasta or
hifiasm, and align the contigs to the
reference:
# asm5: same-species preset; -c: base-level CIGAR, to draw junctions at base scale
# -s 50: asm5 keeps only chains scoring 200 or more, which drops the 199 bp
# chr10 and 184 bp chr12 inserts
minimap2 -cx asm5 -s 50 GRCh38.fa contigs.fa > der3.vs_reference.paf
jbrowse make-pif der3.vs_reference.pafThe published contig aligns to the reference in these blocks:
derivative 0-32732 + -> chr3:25,326,821-25,359,568
derivative 32732-32931 + -> chr10:58,717,463-58,717,662
derivative 32932-33115 - -> chr12:72,273,111-72,273,294
derivative 33126-39549 - -> chr3:25,352,683-25,359,111The chr10 and chr12 pieces are templated insertions: stretches of other chromosomes copied in where the break was repaired.
Index the contigs, then load the contig as an assembly and the PAF as a synteny track between it and GRCh38:
samtools faidx contigs.faGoes in the assemblies array of config.json. See Assemblies.
{
"name": "der3_RARB_BICC1_TRHDE",
"uri": "contigs.fa"
}Edits config.json in the current folder, creating it if there is none. See JBrowse CLI with Desktop.
jbrowse add-assembly contigs.fa \
--name der3_RARB_BICC1_TRHDE \
--load copyIn JBrowse Desktop, Open your own genome on the start screen (or File → Open genome... in a session), then Open from a URL and paste, one per line:
contigs.fa
contigs.fa.faiJBrowse reads the format off the file name. Then fill in:
- Genome name:
der3_RARB_BICC1_TRHDE
contigs.fa is relative to a config.json. Replace it with its URL or its path on this computer.
The track lists the query assembly (the contig) first and the target (GRCh38) second, the reverse of the minimap2 argument order. Reversed, the view opens empty and reports no error:
Goes in the tracks array of config.json. See Tracks.
{
"type": "SyntenyTrack",
"trackId": "der3_vs_hg38",
"name": "der3 contig vs hg38",
"assemblyNames": ["der3_RARB_BICC1_TRHDE", "hg38"],
"adapter": {
"type": "PairwiseIndexedPAFAdapter",
"uri": "der3.vs_reference.pif.gz",
"queryAssembly": "der3_RARB_BICC1_TRHDE",
"targetAssembly": "hg38"
}
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "SyntenyTrack",
"trackId": "der3_vs_hg38",
"name": "der3 contig vs hg38",
"assemblyNames": ["der3_RARB_BICC1_TRHDE", "hg38"],
"adapter": {
"type": "PairwiseIndexedPAFAdapter",
"uri": "der3.vs_reference.pif.gz",
"queryAssembly": "der3_RARB_BICC1_TRHDE",
"targetAssembly": "hg38"
}
}'In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add track from pasted JSON, and paste:
{
"type": "SyntenyTrack",
"trackId": "der3_vs_hg38",
"name": "der3 contig vs hg38",
"assemblyNames": ["der3_RARB_BICC1_TRHDE", "hg38"],
"adapter": {
"type": "PairwiseIndexedPAFAdapter",
"uri": "der3.vs_reference.pif.gz",
"queryAssembly": "der3_RARB_BICC1_TRHDE",
"targetAssembly": "hg38"
}
}der3.vs_reference.pif.gz is relative to a config.json. Replace it with its URL or its path on this computer.
That shows it in the linear view. For the synteny view, open Add → Linear synteny view, pick the track under Quick start, and click Launch.
Add the truth set, called on five platforms before this ONT run existed, so every junction has an independent call to check against:
Goes in the tracks array of config.json. See Tracks.
{
"type": "VariantTrack",
"trackId": "COLO829_truth_set",
"name": "COLO829 validated somatic SVs (Valle-Inclán 2022)",
"assemblyNames": ["hg38"],
"adapter": {
"type": "VcfAdapter",
"uri": "https://zenodo.org/api/records/4716169/files/truthset_somaticSVs_COLO829_hg38lifted.vcf/content"
}
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "VariantTrack",
"trackId": "COLO829_truth_set",
"name": "COLO829 validated somatic SVs (Valle-Inclán 2022)",
"assemblyNames": ["hg38"],
"adapter": {
"type": "VcfAdapter",
"uri": "https://zenodo.org/api/records/4716169/files/truthset_somaticSVs_COLO829_hg38lifted.vcf/content"
}
}'In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add track from pasted JSON, and paste:
{
"type": "VariantTrack",
"trackId": "COLO829_truth_set",
"name": "COLO829 validated somatic SVs (Valle-Inclán 2022)",
"assemblyNames": ["hg38"],
"adapter": {
"type": "VcfAdapter",
"uri": "https://zenodo.org/api/records/4716169/files/truthset_somaticSVs_COLO829_hg38lifted.vcf/content"
}
}Open this track in JBrowse Web ↗
Needs JBrowse Desktop 5.0 or newer. If nothing opens, copy the link and paste it into Desktop's Open JBrowse Web link..., on the start screen or under File → Session.
https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fcancer_sv%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22VariantTrack%22%2C%22trackId%22%3A%22COLO829_truth_set%22%2C%22name%22%3A%22COLO829+validated+somatic+SVs+%28Valle-Incl%C3%A1n+2022%29%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22VcfAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fzenodo.org%2Fapi%2Frecords%2F4716169%2Ffiles%2Ftruthset_somaticSVs_COLO829_hg38lifted.vcf%2Fcontent%22%7D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr3%3A25%2C320%2C000-25%2C365%2C000%22%2C%22tracks%22%3A%5B%22COLO829_truth_set%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+COLO829+validated+somatic+SVs+%28Valle-Incl%C3%A1n+2022%29This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.
from jbrowse_anywidget import JBrowseApp, fetch_hub
config = fetch_hub("https://jbrowse.org/demos/cancer_sv/config.json")
app = JBrowseApp(
assemblies=config["assemblies"],
tracks=config.get("tracks", []) + [
{
"type": "VariantTrack",
"trackId": "COLO829_truth_set",
"name": "COLO829 validated somatic SVs (Valle-Inclán 2022)",
"assemblyNames": [
"hg38"
],
"adapter": {
"type": "VcfAdapter",
"uri": "https://zenodo.org/api/records/4716169/files/truthset_somaticSVs_COLO829_hg38lifted.vcf/content"
}
}
],
views=[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr3:25,320,000-25,365,000",
"tracks": [
"COLO829_truth_set"
]
}
],
)
app # display the widgetThis view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.
import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'
const configUrl = "https://jbrowse.org/demos/cancer_sv/config.json"
const configPromise = fetch(configUrl)
.then(res => res.json())
.then(config => {
addRelativeUris(config, new URL(configUrl))
return config
})
export default function Figure() {
const config = use(configPromise)
return (
<JBrowse
assemblies={config.assemblies}
tracks={[...(config.tracks ?? []), ...[
{
"type": "VariantTrack",
"trackId": "COLO829_truth_set",
"name": "COLO829 validated somatic SVs (Valle-Inclán 2022)",
"assemblyNames": [
"hg38"
],
"adapter": {
"type": "VcfAdapter",
"uri": "https://zenodo.org/api/records/4716169/files/truthset_somaticSVs_COLO829_hg38lifted.vcf/content"
}
}
]]}
aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
configuration={config.configuration}
views={[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr3:25,320,000-25,365,000",
"tracks": [
"COLO829_truth_set"
]
}
]}
/>
)
}jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.
cat > tracks.json <<'JSON'
[
{
"type": "VariantTrack",
"trackId": "COLO829_truth_set",
"name": "COLO829 validated somatic SVs (Valle-Inclán 2022)",
"assemblyNames": [
"hg38"
],
"adapter": {
"type": "VcfAdapter",
"uri": "https://zenodo.org/api/records/4716169/files/truthset_somaticSVs_COLO829_hg38lifted.vcf/content"
}
}
]
JSON
npx @jbrowse/img --config https://jbrowse.org/demos/cancer_sv/config.json \
--trackConfigs tracks.json \
--assembly hg38 --loc chr3:25,320,000-25,365,000 \
--track COLO829_truth_set \
--out figure.svgFor a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).
The assembly, synteny track and truth set above reproduce the ribbons and arcs on your own contig. The build script also writes a BED labelling each segment of the derivative with its reference interval, and the spanning reads realigned to it:
Goes in the tracks array of config.json. See Tracks.
{
"trackId": "der3_segments",
"name": "Where each segment came from",
"uri": "der3_RARB.derivative_segments.bed.gz",
"assemblyNames": ["der3_RARB_BICC1_TRHDE"]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track der3_RARB.derivative_segments.bed.gz \
--trackId der3_segments \
--name "Where each segment came from" \
--assemblyNames der3_RARB_BICC1_TRHDE \
--load copyIn JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:
- Main file:
der3_RARB.derivative_segments.bed.gz
JBrowse reads the adapter and track type off the file name. Then fill in:
- Track name:
Where each segment came from - Assembly:
der3_RARB_BICC1_TRHDE
Click Add.
der3_RARB.derivative_segments.bed.gz is relative to a config.json. Replace it with its URL or its path on this computer.
Goes in the tracks array of config.json. See Tracks.
{
"trackId": "reads_vs_der3",
"name": "Spanning reads realigned to the derivative",
"uri": "der3_RARB.reads_vs_derivative.bam",
"assemblyNames": ["der3_RARB_BICC1_TRHDE"]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track der3_RARB.reads_vs_derivative.bam \
--trackId reads_vs_der3 \
--name "Spanning reads realigned to the derivative" \
--assemblyNames der3_RARB_BICC1_TRHDE \
--load copyIn JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:
- Main file:
der3_RARB.reads_vs_derivative.bam
JBrowse reads the adapter and track type off the file name. Then fill in:
- Track name:
Spanning reads realigned to the derivative - Assembly:
der3_RARB_BICC1_TRHDE
Click Add.
der3_RARB.reads_vs_derivative.bam is relative to a config.json. Replace it with its URL or its path on this computer.
On the hg38 row, the figures draw UCSC's RefSeq genes:
Goes in the tracks array of config.json. See Tracks.
{
"type": "FeatureTrack",
"trackId": "ncbi_refseq_hg38",
"name": "NCBI RefSeq genes",
"assemblyNames": ["hg38"],
"adapter": {
"type": "Gff3TabixAdapter",
"gffGzLocation": {
"uri": "https://jbrowse.org/ucsc/hg38/ncbiRefSeq.gff.gz"
},
"index": {
"indexType": "CSI",
"location": {
"uri": "https://jbrowse.org/ucsc/hg38/ncbiRefSeq.gff.gz.csi"
}
}
}
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "FeatureTrack",
"trackId": "ncbi_refseq_hg38",
"name": "NCBI RefSeq genes",
"assemblyNames": ["hg38"],
"adapter": {
"type": "Gff3TabixAdapter",
"gffGzLocation": {
"uri": "https://jbrowse.org/ucsc/hg38/ncbiRefSeq.gff.gz"
},
"index": {
"indexType": "CSI",
"location": {
"uri": "https://jbrowse.org/ucsc/hg38/ncbiRefSeq.gff.gz.csi"
}
}
}
}'In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add track from pasted JSON, and paste:
{
"type": "FeatureTrack",
"trackId": "ncbi_refseq_hg38",
"name": "NCBI RefSeq genes",
"assemblyNames": ["hg38"],
"adapter": {
"type": "Gff3TabixAdapter",
"gffGzLocation": {
"uri": "https://jbrowse.org/ucsc/hg38/ncbiRefSeq.gff.gz"
},
"index": {
"indexType": "CSI",
"location": {
"uri": "https://jbrowse.org/ucsc/hg38/ncbiRefSeq.gff.gz.csi"
}
}
}
}The figures below also draw RefSeq genes projected onto the derivative, a track the demo config does not carry.
Open Add → Linear synteny view with hg38 on the top row and
der3_RARB_BICC1_TRHDE below, and pick der3 contig vs hg38 as the synteny
track. The view shows:
- ribbons colored by the reference chromosome each segment came from
- a BED track on the derivative labelling each segment with its reference interval, which the gene track cannot do because a segment usually sits inside one large intron
- the reference gene annotation projected onto the derivative: the first coding exon of RARB, a short stretch of TRHDE coding sequence in reverse, then RARB again, inverted
- the tumor's split reads under the reference row, one row per molecule, with the truth set's validated calls above them; the reads are grouped by Split reads with the unsplit section hidden, so the coverage counts the split reads alone
- each junction drawn once as an arc, with a tick at each end over the sequence retained there. Ticks pointing apart mark a deletion-type join, ticks pointing toward each other a duplication-type join, and parallel ticks an inversion.
Checking the der(3) contig against the reads and the truth set
Zoom the synteny view to the kilobase holding the junctions, where the two inserts have separate ribbons:
- Against hg38, the split reads stop at each junction, and the truth set has a validated call at each place they stop. The truth set comes from other platforms, so it is an independent check on the contig.
- Against the derivative, most of the same reads cross all three junctions in one alignment. The consensus was polished from these reads, so this shows that they agree with each other.
- The read track shows split alignments only, grouped by Split reads with the unsplit section hidden, so its coverage counts only reads that cross a junction. Each hg38 window is wider than the piece the allele uses, so that coverage steps down as each arm ends.
Reproduce it end to end
scripts/build_cancer_sv_demo.sh
builds everything above from public sources into ./cancer_sv_build/jbrowse2.
For COLO829 the script:
- Converts the coverage to bigWig as above.
- Adds the tumor and normal reads as tracks streamed from ONT's bucket.
- Downloads the published der(3) contig with its alignment to GRCh38, its segment labels and the spanning reads realigned to it.
The derivative allele shows how to assemble a contig like it from your own reads. The same run builds the K562 half of the demo, which Gene fusion calls and the DNA behind them walks through.
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_cancer_sv_demo.sh
bash build_cancer_sv_demo.sh
npx --yes serve cancer_sv_build/jbrowse2See also
- Tutorial: Gene fusion calls and the DNA behind them
- Tutorial: Reviewing a whole SV callset
- Tutorial: Structural variants from Hi-C
- Tutorial: Structural variants (Cancer GIAB) part 1: breakpoints
- User guide: SV visualization
- User guide: SV inspector view
- User guide: Linear synteny view
Citations
- Valle-Inclán et al. (2022). A multi-platform reference for somatic structural variation detection
- Nattestad et al. (2018). Complex rearrangements and oncogene amplifications revealed by long-read DNA and RNA sequencing of a breast cancer cell line
- Nattestad et al. (2021). Ribbon: intuitive visualization for complex genomic variation
Notes
-
A chain of junctions can also bring two genes together into a fusion, as in the KLHDC2-SNTB1 fusion of the SK-BR-3 breast cancer line (Nattestad et al. 2018). ↩
Feedback on this tutorial is welcome: contact us.