Skip to main content

Gene fusion calls and the DNA behind them

JBrowse v5 beta

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.13. Desktop beta builds are coming soon.

A fusion caller writes a table of gene pairs, each with the coordinate of the transcript junction where the RNA joins the two genes. We load STAR-Fusion's short-read calls beside long RNA reads from the same cell line and count the molecules crossing each junction. Then we find where the chromosome broke. In K562, the BCR-ABL1 DNA break lies in the first intron of ABL1, well before the junction the caller reports. The break under NUP214-XKR3, another junction on the same amplified segment, sits at the reported junction.

Prerequisites

Each python helper is a single file:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/depmap_to_jbrowse.py
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/lift_bnd_vcf.py

Where the data comes from

Four PacBio Iso-Seq runs from ENCODE, two tables out of DepMap's 24Q4 release, and the DNA breakpoints on hg19.

The build script takes these files from their URLs, so there is nothing to download by hand.

Cutting K562 out of DepMap and lifting its breakpoints to hg38

K562 is a chronic myeloid leukemia line with the Philadelphia chromosome, the t(9;22) translocation between chr9 and chr22 that fuses BCR to ABL1.

The fusion and copy-number tables both cover every line in the release. depmap_to_jbrowse.py filters to one line and writes a STAR-Fusion TSV from the fusion table and a bedGraph from the copy-number segments. K562 is model ACH-000551, and its WGS copy-number profile is PR-aheaZL:

python3 depmap_to_jbrowse.py fusions OmicsFusionFiltered.csv ACH-000551 K562.star-fusion.tsv
python3 depmap_to_jbrowse.py segments OmicsCNSegmentsProfile.csv PR-aheaZL K562_cn.bedGraph
sort -k1,1 -k2,2n K562_cn.bedGraph |
  awk 'NR==FNR{ok[$1];next} ($1 in ok)' hg38.chrom.sizes - > K562_cn.sorted.bedGraph
bedGraphToBigWig K562_cn.sorted.bedGraph hg38.chrom.sizes K562_cn.bw

The DNA breakpoints arrive on hg19. A breakend record has a second coordinate inside its ALT string, so a plain liftOver of the POS column leaves the partner coordinates on hg19. lift_bnd_vcf.py moves both:

python3 lift_bnd_vcf.py calls.hg19.vcf.gz hg19ToHg38.over.chain.gz \
  ./liftOver calls.hg38.vcf liftwork
bgzip calls.hg38.vcf && tabix -p vcf calls.hg38.vcf.gz

Loading hg38 and the merged Iso-Seq reads

The lifted DNA breakpoints and the Iso-Seq molecules are on hg38, so we load that assembly first.

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"
}
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 Show all available genomes and pick it. To load the files of this config instead:

In JBrowse Desktop, Open new 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.gzi

JBrowse 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

ENCODE releases each Iso-Seq alignment unsorted. Sort each run, merge them into one BAM and index it:

samtools sort -o s_run1.bam run1.bam
samtools sort -o s_run2.bam run2.bam
samtools sort -o s_run3.bam run3.bam
samtools sort -o s_run4.bam run4.bam
samtools merge -f K562_isoseq.bam s_run1.bam s_run2.bam s_run3.bam s_run4.bam
samtools index K562_isoseq.bam

The merged BAM loads as one read track. For your own long RNA reads, swap uri for a BAM aligned to the same assembly, with its .bai beside it:

Goes in the tracks array of config.json. See Tracks.

{
  "trackId": "K562_isoseq",
  "name": "K562 PacBio Iso-Seq (ENCODE)",
  "uri": "K562_isoseq.bam",
  "assemblyNames": ["hg38"]
}
jbrowse add-track K562_isoseq.bam \
  --trackId K562_isoseq \
  --name "K562 PacBio Iso-Seq (ENCODE)" \
  --assemblyNames hg38 \
  --load copy

In 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: K562_isoseq.bam

Click Next. JBrowse reads the adapter and track type off the file name. Then fill in:

  • Track name: K562 PacBio Iso-Seq (ENCODE)
  • Assembly: hg38

Click Add.

K562_isoseq.bam is relative to a config.json. Replace it with its URL or its path on this computer.

Triaging the STAR-Fusion calls in the SV inspector

Add → SV inspector, then the file, opens the STAR-Fusion table beside a circular view of it, one chord per row. The import form reads the File Type from the filename or the table's header line, and its menu sets the type by hand.

Searching the SV inspector's table filters the table and the circular view together:

  • chrM keeps the rows that pair a gene with a mitochondrial transcript, the usual chimeric-read artefacts.
  • Mitelman keeps the two rows listed in the fusion databases.
  • chr9 keeps the same two, BCR--ABL1 and NUP214--XKR3: junctions between chr9 and chr22 whose chr22 partners lie megabases apart.

Each table row's caret menu has Open in linear genome view, which puts the row's two breakpoints side by side as two regions of one view:

  • Each region is oriented so the fusion transcript reads left to right across the join. XKR3 is on the minus strand, so its region arrives reversed ([rev]).
  • Read connections → View as pairs / link supplementary alignments merges each molecule's two alignments onto one row.
NUP214--XKR3 as two regions of one view with reads linked, opened from its row in the SV inspector. The breakpoints are banded and each line is one Iso-Seq molecule running from NUP214 into XKR3.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fcancer_sv%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22SvInspectorView%22%2C%22displayName%22%3A%22Add+%E2%86%92+SV+inspector%2C+File+Type+%E2%86%92+STAR-Fusion%22%2C%22assembly%22%3A%22hg38%22%2C%22fileType%22%3A%22STAR-Fusion%22%2C%22height%22%3A620%7D%5D%7D&sessionName=JBrowse+docs%3A+cancer_sv%2Fk562_fusion_inspector_form

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Click the view's title in its header and enter "Add → SV inspector, File Type → STAR-Fusion"
  3. Import form → File Type → STAR-FusionOnly needed when the filename does not end in the type, which is why a STAR-Fusion .tsv has to be named and a .vcf.gz does not.
  4. Drag the bar at the bottom edge of the view to resize it (620px here).

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/cancer_sv/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "SvInspectorView",
      "displayName": "Add → SV inspector, File Type → STAR-Fusion",
      "assembly": "hg38",
      "fileType": "STAR-Fusion",
      "height": 620
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own 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", []),
    views=[
        {
            "type": "SvInspectorView",
            "displayName": "Add → SV inspector, File Type → STAR-Fusion",
            "assembly": "hg38",
            "fileType": "STAR-Fusion",
            "height": 620
        }
    ],
)
app  # display the widget

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.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "SvInspectorView",
      "displayName": "Add → SV inspector, File Type → STAR-Fusion",
      "assembly": "hg38",
      "fileType": "STAR-Fusion",
      "height": 620
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --width 1500 --height 390 \
  --spec session.json -o figure.png

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.

Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fcancer_sv%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22SvInspectorView%22%2C%22displayName%22%3A%22All+44+STAR-Fusion+calls%22%2C%22assembly%22%3A%22hg38%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fcancer_sv%2FK562.star-fusion.tsv%22%2C%22fileType%22%3A%22STAR-Fusion%22%2C%22height%22%3A620%7D%5D%7D&sessionName=JBrowse+docs%3A+cancer_sv%2Fk562_fusion_inspector_all

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Click the view's title in its header and enter "All 44 STAR-Fusion calls"
  3. Import form → Open file from URL or local computer → URL → Enter URL → OpenOpen the form with Add → SV inspector (or Add → Spreadsheet view); set File Type and Assembly in the same form before clicking Open.
  4. Import form → File Type → STAR-FusionOnly needed when the filename does not end in the type, which is why a STAR-Fusion .tsv has to be named and a .vcf.gz does not.
  5. Drag the bar at the bottom edge of the view to resize it (620px here).

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/cancer_sv/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "SvInspectorView",
      "displayName": "All 44 STAR-Fusion calls",
      "assembly": "hg38",
      "uri": "https://jbrowse.org/demos/cancer_sv/K562.star-fusion.tsv",
      "fileType": "STAR-Fusion",
      "height": 620
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own 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", []),
    views=[
        {
            "type": "SvInspectorView",
            "displayName": "All 44 STAR-Fusion calls",
            "assembly": "hg38",
            "uri": "https://jbrowse.org/demos/cancer_sv/K562.star-fusion.tsv",
            "fileType": "STAR-Fusion",
            "height": 620
        }
    ],
)
app  # display the widget

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.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "SvInspectorView",
      "displayName": "All 44 STAR-Fusion calls",
      "assembly": "hg38",
      "uri": "https://jbrowse.org/demos/cancer_sv/K562.star-fusion.tsv",
      "fileType": "STAR-Fusion",
      "height": 620
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --width 1500 --height 700 \
  --spec session.json -o figure.png

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.

Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fcancer_sv%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22SvInspectorView%22%2C%22displayName%22%3A%22Search+%5C%22chr9%5C%22%3A+two+chr9-chr22+junctions%22%2C%22assembly%22%3A%22hg38%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fcancer_sv%2FK562.star-fusion.tsv%22%2C%22fileType%22%3A%22STAR-Fusion%22%2C%22filterText%22%3A%22chr9%22%2C%22height%22%3A620%7D%5D%7D&sessionName=JBrowse+docs%3A+cancer_sv%2Fk562_fusion_inspector_pair

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Click the view's title in its header and enter "Search "chr9": two chr9-chr22 junctions"
  3. Import form → Open file from URL or local computer → URL → Enter URL → OpenOpen the form with Add → SV inspector (or Add → Spreadsheet view); set File Type and Assembly in the same form before clicking Open.
  4. Import form → File Type → STAR-FusionOnly needed when the filename does not end in the type, which is why a STAR-Fusion .tsv has to be named and a .vcf.gz does not.
  5. Type "chr9" into the table's search box (the magnifier above the grid)In the SV inspector the circular view draws only the rows the search leaves, so this narrows the chords too — it does not change which regions the circle shows, which is the 'show only regions with data' checkbox beside it.
  6. Drag the bar at the bottom edge of the view to resize it (620px here).

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/cancer_sv/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "SvInspectorView",
      "displayName": "Search \"chr9\": two chr9-chr22 junctions",
      "assembly": "hg38",
      "uri": "https://jbrowse.org/demos/cancer_sv/K562.star-fusion.tsv",
      "fileType": "STAR-Fusion",
      "filterText": "chr9",
      "height": 620
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own 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", []),
    views=[
        {
            "type": "SvInspectorView",
            "displayName": "Search \"chr9\": two chr9-chr22 junctions",
            "assembly": "hg38",
            "uri": "https://jbrowse.org/demos/cancer_sv/K562.star-fusion.tsv",
            "fileType": "STAR-Fusion",
            "filterText": "chr9",
            "height": 620
        }
    ],
)
app  # display the widget

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.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "SvInspectorView",
      "displayName": "Search \"chr9\": two chr9-chr22 junctions",
      "assembly": "hg38",
      "uri": "https://jbrowse.org/demos/cancer_sv/K562.star-fusion.tsv",
      "fileType": "STAR-Fusion",
      "filterText": "chr9",
      "height": 620
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --width 1500 --height 700 \
  --spec session.json -o figure.png

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.

Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fcancer_sv%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr9%3A131%2C183%2C000-131%2C199%2C515+chr22%3A16%2C792%2C068-16%2C808%2C583%5Brev%5D%22%2C%22highlight%22%3A%5B%7B%22refName%22%3A%22chr9%22%2C%22start%22%3A131198915%2C%22end%22%3A131199115%7D%2C%7B%22refName%22%3A%22chr22%22%2C%22start%22%3A16807983%2C%22end%22%3A16808183%7D%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22ncbi_refseq_hg38%22%2C%22geneGlyphMode%22%3A%22longestCoding%22%2C%22height%22%3A60%7D%2C%7B%22trackId%22%3A%22K562_star_fusion%22%2C%22type%22%3A%22LinearVariantDisplay%22%2C%22displayMode%22%3A%22collapsed%22%2C%22height%22%3A30%7D%2C%7B%22trackId%22%3A%22K562_isoseq%22%2C%22type%22%3A%22LinearAlignmentsDisplay%22%2C%22height%22%3A450%2C%22coverageHeight%22%3A90%2C%22showSashimiArcs%22%3Afalse%2C%22filterBy%22%3A%7B%22split%22%3A%22only%22%7D%2C%22unit%22%3A%22chain%22%2C%22color%22%3A%7B%22field%22%3A%22pairOrientation%22%7D%2C%22showLegend%22%3Atrue%2C%22showBezierConnections%22%3Atrue%2C%22readConnections%22%3A%22arc%22%2C%22showLongRange%22%3Afalse%2C%22readConnectionsHeight%22%3A90%2C%22featureHeight%22%3A4%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+cancer_sv%2Fk562_fusion_inspector_reads

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes”.
    1. Track menu → Gene glyph → Representative transcript
  3. Add the next track the same way.This figure uses “K562 STAR-Fusion calls (DepMap 24Q4)”.
    1. Track menu → Feature height → Collapsed
  4. Add the next track the same way. This one needs a BAM file (.bam + .bai).This figure uses “K562 PacBio Iso-Seq (ENCODE)”.
    1. Drag the bottom edge of the coverage band to resize it.
    2. Track menu → Sashimi arcs → Show sashimi arcs (unchecked)Hides the splice-junction arcs and keeps the coverage band underneath them.
    3. Track menu → Filter by... → Split alignments → Only split alignmentsA read filter drops reads in the worker before layout, so it thins the coverage histogram along with the pileup.
    4. Track menu → Read connections → View as pairs / link supplementary alignments (checked)
    5. Track menu → Color by... → Paired end → Pair orientation
    6. Track menu → Show... → Show legend (checked)
    7. Track menu → Read connections → Use curved connectors (checked)Draws a read's alignments joined by a curve rather than a straight line. Worth it when the two ends sit in different displayed regions, where the curve reads as one read crossing the gap.
    8. Track menu → Read connections → Read arcs
    9. Track menu → Read connections → Arc / read cloud band options → Show off-screen mate connections (unchecked)That submenu stays greyed out until an arc or read-cloud overlay is on.
    10. Drag the handle at the edge of the arc band to resize it (90px here).Its tooltip reads "Drag to resize arcs area"; there is no menu entry for the height.
    11. Track menu → Read height → Custom... → 4px
  5. Type your region of interest into the location box and press Enter.This figure is at chr9:131,183,000-131,199,515 chr22:16,792,068-16,808,583[rev].
  6. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 2 regions; highlights can also be set with the &highlight= URL parameter.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/cancer_sv/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr9:131,183,000-131,199,515 chr22:16,792,068-16,808,583[rev]",
      "highlight": [
        {
          "refName": "chr9",
          "start": 131198915,
          "end": 131199115
        },
        {
          "refName": "chr22",
          "start": 16807983,
          "end": 16808183
        }
      ],
      "tracks": [
        {
          "trackId": "ncbi_refseq_hg38",
          "geneGlyphMode": "longestCoding",
          "height": 60
        },
        {
          "trackId": "K562_star_fusion",
          "type": "LinearVariantDisplay",
          "displayMode": "collapsed",
          "height": 30
        },
        {
          "trackId": "K562_isoseq",
          "type": "LinearAlignmentsDisplay",
          "height": 450,
          "coverageHeight": 90,
          "showSashimiArcs": false,
          "filterBy": {
            "split": "only"
          },
          "unit": "chain",
          "color": {
            "field": "pairOrientation"
          },
          "showLegend": true,
          "showBezierConnections": true,
          "readConnections": "arc",
          "showLongRange": false,
          "readConnectionsHeight": 90,
          "featureHeight": 4
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own 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", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr9:131,183,000-131,199,515 chr22:16,792,068-16,808,583[rev]",
            "highlight": [
                {
                    "refName": "chr9",
                    "start": 131198915,
                    "end": 131199115
                },
                {
                    "refName": "chr22",
                    "start": 16807983,
                    "end": 16808183
                }
            ],
            "tracks": [
                {
                    "trackId": "ncbi_refseq_hg38",
                    "geneGlyphMode": "longestCoding",
                    "height": 60
                },
                {
                    "trackId": "K562_star_fusion",
                    "type": "LinearVariantDisplay",
                    "displayMode": "collapsed",
                    "height": 30
                },
                {
                    "trackId": "K562_isoseq",
                    "type": "LinearAlignmentsDisplay",
                    "height": 450,
                    "coverageHeight": 90,
                    "showSashimiArcs": False,
                    "filterBy": {
                        "split": "only"
                    },
                    "unit": "chain",
                    "color": {
                        "field": "pairOrientation"
                    },
                    "showLegend": True,
                    "showBezierConnections": True,
                    "readConnections": "arc",
                    "showLongRange": False,
                    "readConnectionsHeight": 90,
                    "featureHeight": 4
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 --loc 'chr9:131,183,000-131,199,515 chr22:16,792,068-16,808,583[rev]' \
  --track ncbi_refseq_hg38 '{"geneGlyphMode":"longestCoding","height":60}' \
  --track K562_star_fusion display:LinearVariantDisplay '{"displayMode":"collapsed","height":30}' \
  --track K562_isoseq display:LinearAlignmentsDisplay '{"height":450,"coverageHeight":90,"showSashimiArcs":false,"filterBy":{"split":"only"},"unit":"chain","color":{"field":"pairOrientation"},"showLegend":true,"showBezierConnections":true,"readConnections":"arc","showLongRange":false,"readConnectionsHeight":90,"featureHeight":4}' \
  --width 1500 --out figure.svg

It has no flag for this figure's highlight, so its picture can differ there.

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

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.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr9:131,183,000-131,199,515 chr22:16,792,068-16,808,583[rev]",
      "highlight": [
        {
          "refName": "chr9",
          "start": 131198915,
          "end": 131199115
        },
        {
          "refName": "chr22",
          "start": 16807983,
          "end": 16808183
        }
      ],
      "tracks": [
        {
          "trackId": "ncbi_refseq_hg38",
          "geneGlyphMode": "longestCoding",
          "height": 60
        },
        {
          "trackId": "K562_star_fusion",
          "type": "LinearVariantDisplay",
          "displayMode": "collapsed",
          "height": 30
        },
        {
          "trackId": "K562_isoseq",
          "type": "LinearAlignmentsDisplay",
          "height": 450,
          "coverageHeight": 90,
          "showSashimiArcs": false,
          "filterBy": {
            "split": "only"
          },
          "unit": "chain",
          "color": {
            "field": "pairOrientation"
          },
          "showLegend": true,
          "showBezierConnections": true,
          "readConnections": "arc",
          "showLongRange": false,
          "readConnectionsHeight": 90,
          "featureHeight": 4
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "each line is one molecule, NUP214 into XKR3",
    "fontSize": 18,
    "maxWidth": 250,
    "anchor": {
      "trackId": "K562_isoseq",
      "loc": "chr9:131,195,200",
      "fracY": 0.55,
      "alignX": "left",
      "dx": 20
    }
  },
  {
    "type": "text",
    "text": "chr22 is flipped: its coordinates run right to left",
    "fontSize": 17,
    "maxWidth": 330,
    "anchor": {
      "trackId": "ncbi_refseq_hg38",
      "loc": "chr22:16,805,600",
      "fracY": 0.5,
      "alignX": "left"
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --width 1500 --height 880 \
  --timeout 120000 \
  --spec session.json --annotations callouts.json -o figure.png

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 build script adds the STAR-Fusion calls as a track:

Goes in the tracks array of config.json. See Tracks.

{
  "type": "VariantTrack",
  "trackId": "K562_star_fusion",
  "name": "K562 STAR-Fusion calls (DepMap 24Q4)",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "StarFusionAdapter",
    "starFusionLocation": { "uri": "K562.star-fusion.tsv" }
  }
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "K562_star_fusion",
  "name": "K562 STAR-Fusion calls (DepMap 24Q4)",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "StarFusionAdapter",
    "starFusionLocation": { "uri": "K562.star-fusion.tsv" }
  }
}'

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": "K562_star_fusion",
  "name": "K562 STAR-Fusion calls (DepMap 24Q4)",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "StarFusionAdapter",
    "starFusionLocation": { "uri": "K562.star-fusion.tsv" }
  }
}

K562.star-fusion.tsv is relative to a config.json. Replace it with its URL or its path on this computer.

Split RNA reads at BCR-ABL1 across three regions

The transcript reaches ABL1 at more than one place, so the view uses three regions: the BCR donor, where the transcript starts, and two ABL1 acceptor windows. Right-click a read that crosses the junction and choose Split current view to show split alignments, or type the three locations into the location box separated by spaces: chr22:23,286,000-23,293,000 chr9:130,778,000-130,785,000 chr9:130,851,000-130,858,000.

A read crossing the junction is one alignment on chr22 and a supplementary alignment (the second piece of the split read) on chr9. In the track menu:

  • Read connections → Use curved connectors joins the two across the region divider.
  • Filter by... → Split alignments → Only split alignments drops every read that stays on one chromosome.
  • Read connections → Read arcs adds a band under the coverage with one arc per junction, thicker where more reads support it. An arc needs both ends in view: the right-hand window gets one arc and the intron 1 window two, one at each place the reads enter it.

A vertical line at the BCR donor marks molecules whose ABL1 alignment lands in neither window.

BCR on chr22 beside two ABL1 windows on chr9 as three regions of one view, showing only split reads with supplementary alignments linked. The arc band draws counted arcs from the BCR donor into both ABL1 windows, and only the right-hand window has a STAR-Fusion band.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fcancer_sv%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr22%3A23%2C286%2C000-23%2C293%2C000+chr9%3A130%2C778%2C000-130%2C785%2C000+chr9%3A130%2C851%2C000-130%2C858%2C000%22%2C%22highlight%22%3A%5B%7B%22refName%22%3A%22chr22%22%2C%22start%22%3A23290313%2C%22end%22%3A23290513%7D%2C%7B%22refName%22%3A%22chr9%22%2C%22start%22%3A130853964%2C%22end%22%3A130854164%7D%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22ncbi_refseq_hg38%22%2C%22geneGlyphMode%22%3A%22longestCoding%22%2C%22height%22%3A90%7D%2C%7B%22trackId%22%3A%22K562_isoseq%22%2C%22type%22%3A%22LinearAlignmentsDisplay%22%2C%22height%22%3A800%2C%22coverageHeight%22%3A110%2C%22showSashimiArcs%22%3Afalse%2C%22filterBy%22%3A%7B%22split%22%3A%22only%22%7D%2C%22unit%22%3A%22chain%22%2C%22showBezierConnections%22%3Atrue%2C%22readConnections%22%3A%22arc%22%2C%22readConnectionsHeight%22%3A90%2C%22showLegend%22%3Atrue%2C%22featureHeight%22%3A4%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+cancer_sv%2Fk562_bcr_abl_split

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes”.
    1. Track menu → Gene glyph → Representative transcript
  3. Add the next track the same way. This one needs a BAM file (.bam + .bai).This figure uses “K562 PacBio Iso-Seq (ENCODE)”.
    1. Drag the bottom edge of the coverage band to resize it.
    2. Track menu → Sashimi arcs → Show sashimi arcs (unchecked)Hides the splice-junction arcs and keeps the coverage band underneath them.
    3. Track menu → Filter by... → Split alignments → Only split alignmentsA read filter drops reads in the worker before layout, so it thins the coverage histogram along with the pileup.
    4. Track menu → Read connections → View as pairs / link supplementary alignments (checked)
    5. Track menu → Read connections → Use curved connectors (checked)Draws a read's alignments joined by a curve rather than a straight line. Worth it when the two ends sit in different displayed regions, where the curve reads as one read crossing the gap.
    6. Track menu → Read connections → Read arcs
    7. Drag the handle at the edge of the arc band to resize it (90px here).Its tooltip reads "Drag to resize arcs area"; there is no menu entry for the height.
    8. Track menu → Show... → Show legend (checked)
    9. Track menu → Read height → Custom... → 4px
  4. Type your region of interest into the location box and press Enter.This figure is at chr22:23,286,000-23,293,000 chr9:130,778,000-130,785,000 chr9:130,851,000-130,858,000.
  5. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 2 regions; highlights can also be set with the &highlight= URL parameter.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/cancer_sv/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr22:23,286,000-23,293,000 chr9:130,778,000-130,785,000 chr9:130,851,000-130,858,000",
      "highlight": [
        {
          "refName": "chr22",
          "start": 23290313,
          "end": 23290513
        },
        {
          "refName": "chr9",
          "start": 130853964,
          "end": 130854164
        }
      ],
      "tracks": [
        {
          "trackId": "ncbi_refseq_hg38",
          "geneGlyphMode": "longestCoding",
          "height": 90
        },
        {
          "trackId": "K562_isoseq",
          "type": "LinearAlignmentsDisplay",
          "height": 800,
          "coverageHeight": 110,
          "showSashimiArcs": false,
          "filterBy": {
            "split": "only"
          },
          "unit": "chain",
          "showBezierConnections": true,
          "readConnections": "arc",
          "readConnectionsHeight": 90,
          "showLegend": true,
          "featureHeight": 4
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own 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", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr22:23,286,000-23,293,000 chr9:130,778,000-130,785,000 chr9:130,851,000-130,858,000",
            "highlight": [
                {
                    "refName": "chr22",
                    "start": 23290313,
                    "end": 23290513
                },
                {
                    "refName": "chr9",
                    "start": 130853964,
                    "end": 130854164
                }
            ],
            "tracks": [
                {
                    "trackId": "ncbi_refseq_hg38",
                    "geneGlyphMode": "longestCoding",
                    "height": 90
                },
                {
                    "trackId": "K562_isoseq",
                    "type": "LinearAlignmentsDisplay",
                    "height": 800,
                    "coverageHeight": 110,
                    "showSashimiArcs": False,
                    "filterBy": {
                        "split": "only"
                    },
                    "unit": "chain",
                    "showBezierConnections": True,
                    "readConnections": "arc",
                    "readConnectionsHeight": 90,
                    "showLegend": True,
                    "featureHeight": 4
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 --loc 'chr22:23,286,000-23,293,000 chr9:130,778,000-130,785,000 chr9:130,851,000-130,858,000' \
  --track ncbi_refseq_hg38 '{"geneGlyphMode":"longestCoding","height":90}' \
  --track K562_isoseq display:LinearAlignmentsDisplay '{"height":800,"coverageHeight":110,"showSashimiArcs":false,"filterBy":{"split":"only"},"unit":"chain","showBezierConnections":true,"readConnections":"arc","readConnectionsHeight":90,"showLegend":true,"featureHeight":4}' \
  --width 1500 --out figure.svg

It has no flag for this figure's highlight, so its picture can differ there.

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

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.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr22:23,286,000-23,293,000 chr9:130,778,000-130,785,000 chr9:130,851,000-130,858,000",
      "highlight": [
        {
          "refName": "chr22",
          "start": 23290313,
          "end": 23290513
        },
        {
          "refName": "chr9",
          "start": 130853964,
          "end": 130854164
        }
      ],
      "tracks": [
        {
          "trackId": "ncbi_refseq_hg38",
          "geneGlyphMode": "longestCoding",
          "height": 90
        },
        {
          "trackId": "K562_isoseq",
          "type": "LinearAlignmentsDisplay",
          "height": 800,
          "coverageHeight": 110,
          "showSashimiArcs": false,
          "filterBy": {
            "split": "only"
          },
          "unit": "chain",
          "showBezierConnections": true,
          "readConnections": "arc",
          "readConnectionsHeight": 90,
          "showLegend": true,
          "featureHeight": 4
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "each line is one molecule, BCR into ABL1",
    "fontSize": 18,
    "maxWidth": 250,
    "anchor": {
      "trackId": "K562_isoseq",
      "loc": "chr9:130,851,100",
      "fracY": 0.32,
      "alignX": "left",
      "dx": 20
    }
  },
  {
    "type": "text",
    "text": "ABL1 intron 1: coverage, no annotated exon",
    "fontSize": 18,
    "maxWidth": 560,
    "anchor": {
      "trackId": "K562_isoseq",
      "loc": "chr9:130,778,200",
      "fracY": 0,
      "dy": 230,
      "alignX": "left",
      "dx": 6
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --width 1500 --height 1140 \
  --spec session.json --annotations callouts.json -o figure.png

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.

Where the DNA broke under BCR-ABL1 and NUP214-XKR3

A fusion caller reports transcribed junctions, which sit on exon edges. Two DNA assays on the same cells show where the chromosome broke and how much of it is amplified:

  • 10X Chromium linked reads from ENCODE (ENCSR053AXS, Zhou et al. 2019) call the breakends, the two ends of each junction.
  • DepMap WGS segmentation gives the copy number.

The build script lifts the breakends to hg38 and adds both as tracks:

Goes in the tracks array of config.json. See Tracks.

{
  "type": "VariantTrack",
  "trackId": "K562_10x_sv",
  "name": "K562 DNA breakpoints (10X linked reads, lifted to hg38)",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "vcfGzLocation": { "uri": "K562.10x-large-sv.vcf.gz" },
    "index": { "location": { "uri": "K562.10x-large-sv.vcf.gz.tbi" } }
  }
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "K562_10x_sv",
  "name": "K562 DNA breakpoints (10X linked reads, lifted to hg38)",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "vcfGzLocation": { "uri": "K562.10x-large-sv.vcf.gz" },
    "index": { "location": { "uri": "K562.10x-large-sv.vcf.gz.tbi" } }
  }
}'

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": "K562_10x_sv",
  "name": "K562 DNA breakpoints (10X linked reads, lifted to hg38)",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "vcfGzLocation": { "uri": "K562.10x-large-sv.vcf.gz" },
    "index": { "location": { "uri": "K562.10x-large-sv.vcf.gz.tbi" } }
  }
}

K562.10x-large-sv.vcf.gz, K562.10x-large-sv.vcf.gz.tbi are relative to a config.json. Replace each with its URL or its path on this computer.

Goes in the tracks array of config.json. See Tracks.

{
  "trackId": "K562_cn",
  "name": "K562 copy-number segments (DepMap WGS)",
  "uri": "K562_cn.bw",
  "assemblyNames": ["hg38"],
  "displayDefaults": {
    "scales": {
      "y": { "domainMin": 0, "domainMax": 8, "title": "copy ratio (DepMap)" }
    }
  }
}
jbrowse add-track K562_cn.bw \
  --trackId K562_cn \
  --name "K562 copy-number segments (DepMap WGS)" \
  --assemblyNames hg38 \
  --displayDefaults '{"scales":{"y":{"domainMin":0,"domainMax":8,"title":"copy ratio (DepMap)"}}}' \
  --load copy

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": "K562_cn",
  "name": "K562 copy-number segments (DepMap WGS)",
  "uri": "K562_cn.bw",
  "assemblyNames": ["hg38"],
  "displayDefaults": {
    "scales": {
      "y": { "domainMin": 0, "domainMax": 8, "title": "copy ratio (DepMap)" }
    }
  }
}

K562_cn.bw is relative to a config.json. Replace it with its URL or its path on this computer.

Open chr9 from ABL1 to past NUP214 with the copy-number track under both call tracks, and pick Display types → Marks from each call track's menu. In grammar-of-graphics terms, a mark is the shape drawn per record. A record that names its partner breakend draws as a link with nothing configured (mark display), and a call whose partner is on another chromosome draws a stem at its breakpoint.

chr9 from ABL1 to past NUP214: STAR-Fusion junctions from RNA-seq, 10X DNA breakends and DepMap copy number, with the three DNA breaks banded. Copy number steps at the outer two breaks. The BCR-ABL1 junction sits well right of its break, the NUP214-XKR3 junction on top of its break, and the right-hand break reaches chr13, where nothing is transcribed.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fcancer_sv%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr9%3A130%2C690%2C000-131%2C320%2C000%22%2C%22highlight%22%3A%5B%7B%22refName%22%3A%22chr9%22%2C%22start%22%3A130729760%2C%22end%22%3A130733760%7D%2C%7B%22refName%22%3A%22chr9%22%2C%22start%22%3A131197198%2C%22end%22%3A131201198%7D%2C%7B%22refName%22%3A%22chr9%22%2C%22start%22%3A131278138%2C%22end%22%3A131282138%7D%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22ncbi_refseq_hg38%22%2C%22geneGlyphMode%22%3A%22longestCoding%22%2C%22height%22%3A60%7D%2C%7B%22trackId%22%3A%22K562_star_fusion%22%2C%22type%22%3A%22LinearMarkDisplay%22%2C%22height%22%3A50%2C%22marks%22%3A%5B%7B%22mark%22%3A%22link%22%2C%22encoding%22%3A%7B%22x2%22%3A%7B%22chrom%22%3A%22mate.refName%22%2C%22pos%22%3A%22mate.start%22%7D%2C%22color%22%3A%7B%22value%22%3A%22%23a65628%22%7D%2C%22size%22%3A2%7D%2C%22transform%22%3A%5B%7B%22type%22%3A%22mate%22%7D%5D%7D%5D%7D%2C%7B%22trackId%22%3A%22K562_10x_sv%22%2C%22type%22%3A%22LinearMarkDisplay%22%2C%22height%22%3A50%2C%22marks%22%3A%5B%7B%22mark%22%3A%22link%22%2C%22encoding%22%3A%7B%22x2%22%3A%7B%22chrom%22%3A%22mate.refName%22%2C%22pos%22%3A%22mate.start%22%7D%2C%22color%22%3A%7B%22value%22%3A%22%23a65628%22%7D%2C%22size%22%3A2%7D%2C%22transform%22%3A%5B%7B%22type%22%3A%22mate%22%7D%5D%7D%5D%7D%2C%7B%22trackId%22%3A%22K562_cn%22%2C%22height%22%3A130%2C%22scales%22%3A%7B%22y%22%3A%7B%22domainMin%22%3A0%2C%22domainMax%22%3A8%2C%22title%22%3A%22copy+ratio+%28DepMap%29%22%7D%7D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+cancer_sv%2Fk562_amplicon_dna

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes”.
    1. Track menu → Gene glyph → Representative transcript
  3. Add the next track the same way.This figure uses “K562 STAR-Fusion calls (DepMap 24Q4)”.
    1. Track menu → Edit plot... → Add markThis figure draws link marks. The form picks a mark's type and maps its channels to fields.
  4. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “K562 DNA breakpoints (10X linked reads, lifted to hg38)”.
    1. Track menu → Edit plot... → Add markThis figure draws link marks. The form picks a mark's type and maps its channels to fields.
  5. Add the next track the same way. This one needs a BigWig file (.bw).This figure uses “K562 copy-number segments (DepMap WGS)”.
    1. Track menu → Y axis... → RangePins the axis: Min 0 and Max 8. A field left empty follows the data in view.
  6. Type your region of interest into the location box and press Enter.This figure is at chr9:130,690,000-131,320,000.
  7. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 3 regions; highlights can also be set with the &highlight= URL parameter.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/cancer_sv/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr9:130,690,000-131,320,000",
      "highlight": [
        {
          "refName": "chr9",
          "start": 130729760,
          "end": 130733760
        },
        {
          "refName": "chr9",
          "start": 131197198,
          "end": 131201198
        },
        {
          "refName": "chr9",
          "start": 131278138,
          "end": 131282138
        }
      ],
      "tracks": [
        {
          "trackId": "ncbi_refseq_hg38",
          "geneGlyphMode": "longestCoding",
          "height": 60
        },
        {
          "trackId": "K562_star_fusion",
          "type": "LinearMarkDisplay",
          "height": 50,
          "marks": [
            {
              "mark": "link",
              "encoding": {
                "x2": {
                  "chrom": "mate.refName",
                  "pos": "mate.start"
                },
                "color": {
                  "value": "#a65628"
                },
                "size": 2
              },
              "transform": [
                {
                  "type": "mate"
                }
              ]
            }
          ]
        },
        {
          "trackId": "K562_10x_sv",
          "type": "LinearMarkDisplay",
          "height": 50,
          "marks": [
            {
              "mark": "link",
              "encoding": {
                "x2": {
                  "chrom": "mate.refName",
                  "pos": "mate.start"
                },
                "color": {
                  "value": "#a65628"
                },
                "size": 2
              },
              "transform": [
                {
                  "type": "mate"
                }
              ]
            }
          ]
        },
        {
          "trackId": "K562_cn",
          "height": 130,
          "scales": {
            "y": {
              "domainMin": 0,
              "domainMax": 8,
              "title": "copy ratio (DepMap)"
            }
          }
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own 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", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr9:130,690,000-131,320,000",
            "highlight": [
                {
                    "refName": "chr9",
                    "start": 130729760,
                    "end": 130733760
                },
                {
                    "refName": "chr9",
                    "start": 131197198,
                    "end": 131201198
                },
                {
                    "refName": "chr9",
                    "start": 131278138,
                    "end": 131282138
                }
            ],
            "tracks": [
                {
                    "trackId": "ncbi_refseq_hg38",
                    "geneGlyphMode": "longestCoding",
                    "height": 60
                },
                {
                    "trackId": "K562_star_fusion",
                    "type": "LinearMarkDisplay",
                    "height": 50,
                    "marks": [
                        {
                            "mark": "link",
                            "encoding": {
                                "x2": {
                                    "chrom": "mate.refName",
                                    "pos": "mate.start"
                                },
                                "color": {
                                    "value": "#a65628"
                                },
                                "size": 2
                            },
                            "transform": [
                                {
                                    "type": "mate"
                                }
                            ]
                        }
                    ]
                },
                {
                    "trackId": "K562_10x_sv",
                    "type": "LinearMarkDisplay",
                    "height": 50,
                    "marks": [
                        {
                            "mark": "link",
                            "encoding": {
                                "x2": {
                                    "chrom": "mate.refName",
                                    "pos": "mate.start"
                                },
                                "color": {
                                    "value": "#a65628"
                                },
                                "size": 2
                            },
                            "transform": [
                                {
                                    "type": "mate"
                                }
                            ]
                        }
                    ]
                },
                {
                    "trackId": "K562_cn",
                    "height": 130,
                    "scales": {
                        "y": {
                            "domainMin": 0,
                            "domainMax": 8,
                            "title": "copy ratio (DepMap)"
                        }
                    }
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 --loc chr9:130,690,000-131,320,000 \
  --track ncbi_refseq_hg38 '{"geneGlyphMode":"longestCoding","height":60}' \
  --track K562_star_fusion display:LinearMarkDisplay '{"height":50,"marks":[{"mark":"link","encoding":{"x2":{"chrom":"mate.refName","pos":"mate.start"},"color":{"value":"#a65628"},"size":2},"transform":[{"type":"mate"}]}]}' \
  --track K562_10x_sv display:LinearMarkDisplay '{"height":50,"marks":[{"mark":"link","encoding":{"x2":{"chrom":"mate.refName","pos":"mate.start"},"color":{"value":"#a65628"},"size":2},"transform":[{"type":"mate"}]}]}' \
  --track K562_cn '{"height":130,"scales":{"y":{"domainMin":0,"domainMax":8,"title":"copy ratio (DepMap)"}}}' \
  --width 1600 --out figure.svg

It has no flag for this figure's highlight, so its picture can differ there.

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

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.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr9:130,690,000-131,320,000",
      "highlight": [
        {
          "refName": "chr9",
          "start": 130729760,
          "end": 130733760
        },
        {
          "refName": "chr9",
          "start": 131197198,
          "end": 131201198
        },
        {
          "refName": "chr9",
          "start": 131278138,
          "end": 131282138
        }
      ],
      "tracks": [
        {
          "trackId": "ncbi_refseq_hg38",
          "geneGlyphMode": "longestCoding",
          "height": 60
        },
        {
          "trackId": "K562_star_fusion",
          "type": "LinearMarkDisplay",
          "height": 50,
          "marks": [
            {
              "mark": "link",
              "encoding": {
                "x2": {
                  "chrom": "mate.refName",
                  "pos": "mate.start"
                },
                "color": {
                  "value": "#a65628"
                },
                "size": 2
              },
              "transform": [
                {
                  "type": "mate"
                }
              ]
            }
          ]
        },
        {
          "trackId": "K562_10x_sv",
          "type": "LinearMarkDisplay",
          "height": 50,
          "marks": [
            {
              "mark": "link",
              "encoding": {
                "x2": {
                  "chrom": "mate.refName",
                  "pos": "mate.start"
                },
                "color": {
                  "value": "#a65628"
                },
                "size": 2
              },
              "transform": [
                {
                  "type": "mate"
                }
              ]
            }
          ]
        },
        {
          "trackId": "K562_cn",
          "height": 130,
          "scales": {
            "y": {
              "domainMin": 0,
              "domainMax": 8,
              "title": "copy ratio (DepMap)"
            }
          }
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "BCR-ABL1 junction, called by STAR-Fusion from RNA-seq",
    "maxWidth": 600,
    "fontSize": 17,
    "leader": true,
    "anchor": {
      "trackId": "K562_star_fusion",
      "loc": "chr9:130,854,064",
      "fracY": 0.3
    },
    "dx": 60,
    "dy": 12
  },
  {
    "type": "text",
    "text": "DNA break: copy number steps up",
    "fontSize": 17,
    "leader": true,
    "anchor": {
      "trackId": "K562_10x_sv",
      "loc": "chr9:130,731,760",
      "fracY": 0.3
    },
    "dx": 60,
    "dy": 12
  },
  {
    "type": "text",
    "text": "break to chr13, no fusion call",
    "fontSize": 17,
    "leader": true,
    "anchor": {
      "trackId": "K562_10x_sv",
      "loc": "chr9:131,280,138",
      "fracY": 0.3
    },
    "dx": -90,
    "dy": 80
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --width 1600 --height 620 \
  --timeout 120000 \
  --spec session.json --annotations callouts.json -o figure.png

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.

JunctionRNA junction (STAR-Fusion)DNA break (10X)Apart
BCR donorchr22:23,290,413, end of exon 14chr22:23,290,556143 bp into intron 14
ABL1 acceptorchr9:130,854,064, start of exon 2chr9:130,731,760122 kb, in intron 1
NUP214 donorchr9:131,199,015, end of exon 29chr9:131,199,198183 bp into intron 29
XKR3 acceptorchr22:16,808,083, start of exon 3chr22:16,819,35011 kb, in intron 2
noneno callchr9:131,280,138 to chr13no gene at either end

The amplified block on chr9 ends where the DNA breaks do. A Hi-C scan also pairs the ABL1 intron 1 break with BCR. DepMap's segmentation has no interval over BCR, so the donor window shows an arc and no copy-number step. SplitThreader matched copy-number steps to breakpoints the same way in the SK-BR-3 ERBB2 amplicon (Nattestad et al. 2018).

Reproduce it end to end

scripts/build_cancer_sv_demo.sh builds everything above from public sources. For K562 it:

  1. sorts the four ENCODE Iso-Seq runs, which ENCODE releases unsorted, and merges them into the one read track the junction counts come from
  2. cuts K562's rows out of DepMap's fusion and copy-number tables, with the fusion calls ordered by FFPM (fusion fragments per million RNA-seq fragments), best-supported first
  3. lifts the 10X breakends to hg38 as above, and drops a junction whole when either end fails to lift or lands reversed in hg38, where its orientation would come out wrong

The same run builds the COLO829 half of the demo, which Complex rearrangements and derivative alleles walks through.

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_cancer_sv_demo.sh
bash build_cancer_sv_demo.sh    # builds ./cancer_sv_build/jbrowse2
npx --yes serve cancer_sv_build/jbrowse2

See also

Citations

  • Nattestad M, et al. Complex rearrangements and oncogene amplifications revealed by long-read DNA and RNA sequencing of a breast cancer cell line. Genome Research (2018). https://doi.org/10.1101/gr.231100.117
  • Zhou B, et al. Comprehensive, integrated, and phased whole-genome analysis of the primary ENCODE cell line K562. Genome Research (2019). https://doi.org/10.1101/gr.234948.118