Mutation cohort (TCGA)
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.
Breast tumors of one subtype tend to have point mutations in the same genes. The copy-number cohort sorts the TCGA breast tumors by amplification; their point mutations separate the groups the segments cannot. We turn the project's somatic mutation calls into one matrix, each column a distinct mutation and each row a tumor, and read it at CDH1 and PIK3CA. We:
- load the cohort VCF, merged from the GDC's mutation files, as a multi-sample variant track in matrix layout
- facet the rows by histology over CDH1's exons, with introns collapsed from the gene's menu
- facet the rows by receptor subtype over PIK3CA
- add a multi-row quantitative track of mutation frequency per gene and subtype
Prerequisites
- A JBrowse 2 instance to add tracks to (see the web quickstart or the desktop quickstart) and the JBrowse CLI
# Debian/Ubuntu
sudo apt install tabix nodejs
# or conda, which has every tool above
conda install -c bioconda -c conda-forge htslib nodejs
# any platform
npm install -g @jbrowse/cli@nextThe data
TCGA-BRCA open-access somatic mutation calls from the GDC (TCGA 2012).
You don't need these files to follow the page: the track configs below read the hosted results. The build script fetches them to rebuild those results. Use your own cohort covers your own calls.
| What it is | File |
|---|---|
| Primary-tumor Masked Somatic Mutation MAFs (mutation annotation format), queried and downloaded through the GDC API | files |
| Per-tumor clinical annotation, from harmonized case fields and each case's clinical XML | cases |
The cohort VCF and the clinical table
The VCF is the GDC's per-tumor Masked Somatic Mutation calls merged into one multi-sample file, one column per tumor:
#CHROM POS ID REF ALT INFO FORMAT TCGA-A2-A0T2-01A TCGA-A8-A07C-01A
chr3 179234297 . A G GENE=PIK3CA;HGVSP=p.H1047R... GT:AD:DP 0/1:81,29:110 0/0Three conventions affect how to read the matrix:
0/0marks a site the caller did not call, since a MAF has no coverage record for one- every somatic call is written het, because a MAF gives no ploidy
- the GDC's open mutation calls cover the exome only, so the matrix reads at gene scale
Read counts are kept in AD/DP. INFO/CSQ re-encodes the VEP columns from
the MAF (Consequence, IMPACT, HGVSp_Short, SIFT, PolyPhen), so the track
can color cells by consequence impact without running an annotator.
The clinical TSV is one row per tumor barcode and one column per attribute:
name histology er pr her2 subtype stage
TCGA-3C-AAAU-01A lobular positive positive negative HR+/HER2- XIts columns come from three places:
histologyandstageare the GDC's harmonized case fieldser/pr/her2are read from each case's clinical XML, with in-situ hybridization taking precedence over immunohistochemistry for HER2subtypeis derived from those three; a tumor whose receptor calls do not resolve it staysunknown
The table lists more tumors than the mutation track draws.1
Load the cohort VCF into JBrowse
Add the assembly first. The hosted FASTA calls its contigs bare (1) while the
VCF uses chr1, so pass the alias file and both resolve.
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
The figures put NCBI's MANE transcripts above the matrix, one per gene, labelled by gene symbol:
Goes in the tracks array of config.json. See Tracks.
{
"trackId": "MANE.GRCh38.v1.4.refseq",
"name": "MANE 1.4 (w/ RefSeq IDs)",
"uri": "https://ftp.ncbi.nlm.nih.gov/refseq/MANE/trackhub/data/release_1.4/MANE.GRCh38.v1.4.refseq.bb",
"assemblyNames": ["hg38"],
"displayDefaults": {
"labels": { "description": "geneSymbol" }
}
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track https://ftp.ncbi.nlm.nih.gov/refseq/MANE/trackhub/data/release_1.4/MANE.GRCh38.v1.4.refseq.bb \
--trackId MANE.GRCh38.v1.4.refseq \
--name "MANE 1.4 (w/ RefSeq IDs)" \
--assemblyNames hg38 \
--displayDefaults '{"labels":{"description":"geneSymbol"}}'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:
{
"trackId": "MANE.GRCh38.v1.4.refseq",
"name": "MANE 1.4 (w/ RefSeq IDs)",
"uri": "https://ftp.ncbi.nlm.nih.gov/refseq/MANE/trackhub/data/release_1.4/MANE.GRCh38.v1.4.refseq.bb",
"assemblyNames": ["hg38"],
"displayDefaults": {
"labels": { "description": "geneSymbol" }
}
}The cohort is a VariantTrack whose adapter reads the clinical TSV, shown in
the multi-sample matrix display:
Goes in the tracks array of config.json. See Tracks.
{
"type": "VariantTrack",
"trackId": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 1010,
"encoding": { "color": "impact" }
}
]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "VariantTrack",
"trackId": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 1010,
"encoding": { "color": "impact" }
}
]
}'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": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 1010,
"encoding": { "color": "impact" }
}
]
}The track config sets three things:
variantLayout: 'columns'uses one column per mutation, so a gene's mutations pack together however far apart they sit, with a connector band from each column to its positionencoding.coloris a color scale, and itsfieldset toimpactcolors each cell by its VEP impact tier fromCSQ, the same as Color by → Consequence impact in the track menusamplesTsvLocationmakes the clinical columns available to facet and color rows by
The display divides height
among the rows, so each row is about a pixel tall and a band's mutation density
shows as its darkness.
Facet the rows by clinical annotation
In grammar-of-graphics terms,
facet splits the display into
stacked sections, one per value of a samples TSV column, sorted, and
facet.sort pins the sections you want first.
rows.color is a color scale on each
row's label bar, so it puts the matching color strip in the gutter.
Group by and Color by → Samples in the track menu set the same two keys.
Goes in the tracks array of config.json. See Tracks.
{
"type": "VariantTrack",
"trackId": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": { "height": 130 },
"encoding": { "color": "impact" },
"facet": { "field": "histology", "sort": ["ductal", "lobular"] },
"rows": { "color": "histology" }
}
]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "VariantTrack",
"trackId": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": { "height": 130 },
"encoding": { "color": "impact" },
"facet": { "field": "histology", "sort": ["ductal", "lobular"] },
"rows": { "color": "histology" }
}
]
}'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": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": { "height": 130 },
"encoding": { "color": "impact" },
"facet": { "field": "histology", "sort": ["ductal", "lobular"] },
"rows": { "color": "histology" }
}
]
}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%22type%22%3A%22VariantTrack%22%2C%22trackId%22%3A%22tcga_brca_mutations%22%2C%22name%22%3A%22TCGA-BRCA+somatic+mutations+%28979+primary+tumors%29%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22category%22%3A%5B%22TCGA%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22VcfTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Ftcga%2Ftcga_brca_mutations.vcf.gz%22%2C%22csi%22%3Atrue%2C%22samplesTsvLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Ftcga%2Ftcga_brca_clinical.tsv%22%7D%7D%2C%22displays%22%3A%5B%7B%22type%22%3A%22LinearVariantDisplay%22%2C%22variantLayout%22%3A%22columns%22%2C%22height%22%3A450%2C%22connectors%22%3A%7B%22height%22%3A130%7D%2C%22encoding%22%3A%7B%22color%22%3A%22impact%22%7D%2C%22facet%22%3A%7B%22field%22%3A%22histology%22%2C%22sort%22%3A%5B%22ductal%22%2C%22lobular%22%5D%7D%2C%22rows%22%3A%7B%22color%22%3A%22histology%22%7D%7D%5D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr16%3A68%2C730%2C000-68%2C842%2C000%22%2C%22tracks%22%3A%5B%22tcga_brca_mutations%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+TCGA-BRCA+somatic+mutations+%28979+primary+tumors%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", []) + [
{
"type": "VariantTrack",
"trackId": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": [
"hg38"
],
"category": [
"TCGA"
],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": True,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": {
"height": 130
},
"encoding": {
"color": "impact"
},
"facet": {
"field": "histology",
"sort": [
"ductal",
"lobular"
]
},
"rows": {
"color": "histology"
}
}
]
}
],
views=[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr16:68,730,000-68,842,000",
"tracks": [
"tcga_brca_mutations"
]
}
],
)
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 ?? []), ...[
{
"type": "VariantTrack",
"trackId": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": [
"hg38"
],
"category": [
"TCGA"
],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": {
"height": 130
},
"encoding": {
"color": "impact"
},
"facet": {
"field": "histology",
"sort": [
"ductal",
"lobular"
]
},
"rows": {
"color": "histology"
}
}
]
}
]]}
aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
configuration={config.configuration}
views={[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr16:68,730,000-68,842,000",
"tracks": [
"tcga_brca_mutations"
]
}
]}
/>
)
}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": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": [
"hg38"
],
"category": [
"TCGA"
],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": {
"height": 130
},
"encoding": {
"color": "impact"
},
"facet": {
"field": "histology",
"sort": [
"ductal",
"lobular"
]
},
"rows": {
"color": "histology"
}
}
]
}
]
JSON
npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
--trackConfigs tracks.json \
--assembly hg38 --loc chr16:68,730,000-68,842,000 \
--track tcga_brca_mutations \
--out figure.svgFor a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).
We open the matrix over CDH1's exons (see Gene track):
- Right-click CDH1 in the MANE track.
- Choose Collapse introns..., then Replace current view.
Loss of E-cadherin, the protein CDH1 encodes, is the defining lesion of lobular breast cancer (Ciriello et al. 2015).
Facet rows by receptor subtype
Setting facet and rows.color to subtype instead bands the rows by receptor
status (TCGA 2012), with the HR+/HER2-
band first in sort:
Goes in the tracks array of config.json. See Tracks.
{
"type": "VariantTrack",
"trackId": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": { "height": 130 },
"encoding": { "color": "impact" },
"facet": {
"field": "subtype",
"sort": ["HR+/HER2-", "HER2+", "triple-negative"]
},
"rows": { "color": "subtype" }
}
]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "VariantTrack",
"trackId": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": { "height": 130 },
"encoding": { "color": "impact" },
"facet": {
"field": "subtype",
"sort": ["HR+/HER2-", "HER2+", "triple-negative"]
},
"rows": { "color": "subtype" }
}
]
}'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": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": { "height": 130 },
"encoding": { "color": "impact" },
"facet": {
"field": "subtype",
"sort": ["HR+/HER2-", "HER2+", "triple-negative"]
},
"rows": { "color": "subtype" }
}
]
}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%22type%22%3A%22VariantTrack%22%2C%22trackId%22%3A%22tcga_brca_mutations%22%2C%22name%22%3A%22TCGA-BRCA+somatic+mutations+%28979+primary+tumors%29%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22category%22%3A%5B%22TCGA%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22VcfTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Ftcga%2Ftcga_brca_mutations.vcf.gz%22%2C%22csi%22%3Atrue%2C%22samplesTsvLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Ftcga%2Ftcga_brca_clinical.tsv%22%7D%7D%2C%22displays%22%3A%5B%7B%22type%22%3A%22LinearVariantDisplay%22%2C%22variantLayout%22%3A%22columns%22%2C%22height%22%3A450%2C%22connectors%22%3A%7B%22height%22%3A130%7D%2C%22encoding%22%3A%7B%22color%22%3A%22impact%22%7D%2C%22facet%22%3A%7B%22field%22%3A%22subtype%22%2C%22sort%22%3A%5B%22HR%2B%2FHER2-%22%2C%22HER2%2B%22%2C%22triple-negative%22%5D%7D%2C%22rows%22%3A%7B%22color%22%3A%22subtype%22%7D%7D%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%3A179%2C148%2C000-179%2C240%2C500%22%2C%22tracks%22%3A%5B%22tcga_brca_mutations%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+TCGA-BRCA+somatic+mutations+%28979+primary+tumors%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", []) + [
{
"type": "VariantTrack",
"trackId": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": [
"hg38"
],
"category": [
"TCGA"
],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": True,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": {
"height": 130
},
"encoding": {
"color": "impact"
},
"facet": {
"field": "subtype",
"sort": [
"HR+/HER2-",
"HER2+",
"triple-negative"
]
},
"rows": {
"color": "subtype"
}
}
]
}
],
views=[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr3:179,148,000-179,240,500",
"tracks": [
"tcga_brca_mutations"
]
}
],
)
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 ?? []), ...[
{
"type": "VariantTrack",
"trackId": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": [
"hg38"
],
"category": [
"TCGA"
],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": {
"height": 130
},
"encoding": {
"color": "impact"
},
"facet": {
"field": "subtype",
"sort": [
"HR+/HER2-",
"HER2+",
"triple-negative"
]
},
"rows": {
"color": "subtype"
}
}
]
}
]]}
aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
configuration={config.configuration}
views={[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr3:179,148,000-179,240,500",
"tracks": [
"tcga_brca_mutations"
]
}
]}
/>
)
}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": "tcga_brca_mutations",
"name": "TCGA-BRCA somatic mutations (979 primary tumors)",
"assemblyNames": [
"hg38"
],
"category": [
"TCGA"
],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutations.vcf.gz",
"csi": true,
"samplesTsvLocation": {
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_clinical.tsv"
}
},
"displays": [
{
"type": "LinearVariantDisplay",
"variantLayout": "columns",
"height": 450,
"connectors": {
"height": 130
},
"encoding": {
"color": "impact"
},
"facet": {
"field": "subtype",
"sort": [
"HR+/HER2-",
"HER2+",
"triple-negative"
]
},
"rows": {
"color": "subtype"
}
}
]
}
]
JSON
npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
--trackConfigs tracks.json \
--assembly hg38 --loc chr3:179,148,000-179,240,500 \
--track tcga_brca_mutations \
--out figure.svgFor a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).
The bottom band is the tumors whose receptor calls do not resolve a subtype.
With its introns collapsed the same way, PIK3CA shows its calls piled on three columns: H1047R in the kinase domain, and E542K and E545K side by side in the helical domain. All three run through every band, densest in HR+/HER2-.
Add a track of mutation frequency per gene
The bands above differ in height, so their darkness does not compare as a rate.
mutation_recurrence.py
writes one interval per gene, valued as the percent of each group with a
mutation. It takes the same SAMPLES.tsv:COLUMN group spec as the copy-number
cohort's
cnv_recurrence.py:
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/mutation_recurrence.py
python3 mutation_recurrence.py tcga_brca_mutations.vcf.gz by_subtype.bedGraph \
--groups tcga_brca_clinical.tsv:subtype#chrom start end HR+/HER2- HER2+ triple-negative unknown
chr3 179199065 179234302 40.56 30.18 11.19 30.71
chr17 7670683 7676564 19.44 39.64 80.42 32.28BedGraphTabixAdapter takes every column past end as a separate signal, and a
MultiQuantitativeTrack draws one row
per group.
Goes in the tracks array of config.json. See Tracks.
{
"type": "MultiQuantitativeTrack",
"trackId": "tcga_brca_mutation_recurrence_by_subtype",
"name": "TCGA-BRCA mutation recurrence by receptor subtype",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "BedGraphTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutation_recurrence_by_subtype.bedGraph.gz",
"csi": true
},
"displayDefaults": {
"height": 260,
"encoding": { "y": { "scale": { "domainMin": 0, "domainMax": 100 } } },
"rows": { "axis": { "grid": true } }
}
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "MultiQuantitativeTrack",
"trackId": "tcga_brca_mutation_recurrence_by_subtype",
"name": "TCGA-BRCA mutation recurrence by receptor subtype",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "BedGraphTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutation_recurrence_by_subtype.bedGraph.gz",
"csi": true
},
"displayDefaults": {
"height": 260,
"encoding": { "y": { "scale": { "domainMin": 0, "domainMax": 100 } } },
"rows": { "axis": { "grid": true } }
}
}'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": "MultiQuantitativeTrack",
"trackId": "tcga_brca_mutation_recurrence_by_subtype",
"name": "TCGA-BRCA mutation recurrence by receptor subtype",
"assemblyNames": ["hg38"],
"category": ["TCGA"],
"adapter": {
"type": "BedGraphTabixAdapter",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_mutation_recurrence_by_subtype.bedGraph.gz",
"csi": true
},
"displayDefaults": {
"height": 260,
"encoding": { "y": { "scale": { "domainMin": 0, "domainMax": 100 } } },
"rows": { "axis": { "grid": true } }
}
}Across the genome, each row's spikes are the genes mutated most often in that subtype.
Open the track above the matrix to read each band's rate over it.
--impact sets what counts as a hit, defaulting to the HIGH and MODERATE tiers
of the consequence impact that colors the matrix. The rate has no background
model, and gene length enters directly: TTN, a very long gene, ranks near the
top on passenger mutations alone.
On the matrix:
- Clustering → Cluster rows by genotype... gathers every mutated sample into one block (see Clustering rows).
- Filter by → Minor allele frequency keeps the recurrent mutations (see filtering by allele frequency and missingness).
Use your own cohort
maf_to_vcf.py
merges a directory of MAFs (vcf2maf output,
cBioPortal study downloads, your own caller) into the cohort VCF:
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/maf_to_vcf.py
# --sample-types 01: keep primary tumors, read off each Tumor_Sample_Barcode
python3 maf_to_vcf.py mafs/ cohort.vcf --sample-types 01
bgzip cohort.vcf && tabix -f -C -p vcf cohort.vcf.gzEach MAF row needs Chromosome, Start_Position, the two allele columns,
Tumor_Sample_Barcode and CONTEXT. The script reads Tumor_Sample_Barcode as
a TCGA sample barcode, whose 14th and 15th characters give the sample type that
--sample-types keeps, so name your tumors in that form. A cohort that never
passed through a MAF needs a multi-sample somatic VCF. For faceting, any TSV
whose first column matches the VCF's sample names works as samplesTsvLocation.
Reproduce it end to end
One script builds every file above for any project id,
build_tcga_cohort_mutations.sh:
- It downloads every open-access Masked Somatic Mutation MAF in the project, the GDC's aliquot-merged ensemble calls with germline sites masked out, which need no dbGaP application.
maf_to_vcf.pymerges them into one VCF, a column per tumor. A GDC file query also returns metastasis MAFs, so the merge keeps primary tumors (sample-type code01in each MAF's barcode), the tumors the copy-number cohort draws. It keeps one aliquot per tumor, names each column by sample barcode as the copy-number rows are named, and reads each deletion's anchor base from the MAF'sCONTEXTcolumn, so it needs no reference FASTA.tcga_clinical_tsv.pybuilds the clinical table.mutation_recurrence.pywrites, per gene and group, the share of tumors with at least one call in the--impacttiers. A tumor counts once however many calls it has in the gene.
The scripts need curl, python3, and bgzip + tabix from
htslib, which on Debian/Ubuntu is
apt install curl python3 tabix.
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_tcga_cohort_mutations.sh
bash build_tcga_cohort_mutations.sh TCGA-BRCA 20 # 20 tumors, to test the pipeline
bash build_tcga_cohort_mutations.sh TCGA-BRCA # the full cohort, ~10 minutes
npx --yes serve jbrowse2 # then open the printed URLThe script writes a jbrowse2/ opening on PIK3CA with the recurrence rows
over the matrix.
Swap in any other project id (TCGA-LUAD, TCGA-COAD, ...) for a different
cohort, with --no-receptors to tcga_clinical_tsv.py for a non-breast
project. A third argument names the clinical column the recurrence track splits
on; subtype is breast only, while histology and stage work for any
project.
See also
- Tutorial: CNV cohort (TCGA)
- Tutorial: A selected haplotype (Dog10K)
- User guide: Variant sample rows
- User guide: Clustering rows
- Config guide: Variant track
- Config guide: Using jexl callbacks
External links
Notes
-
A case with no mutation calls still has receptor status. JBrowse reports the unmatched tumors when the track loads. ↩
Feedback on this tutorial is welcome: contact us.