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

A fusion caller outputs a table of gene pairs and a junction coordinate, and nothing about the DNA event underneath. Load STAR-Fusion's short-read calls beside long RNA reads from the same cell line, count the molecules that cross each junction, then find where the chromosome broke: K562's BCR-ABL1 breaks 122 kb before the junction the caller reports, inside ABL1's first intron, and the DNA break under the amplicon's other junction, NUP214-XKR3, sits at the junction the caller reports.

Prerequisites

  • nothing to read along. Everything below is for rebuilding the data
  • a JBrowse to open them in: Desktop takes a local file by path, Web through Add track
  • Command line tools (JBrowse CLI)
  • samtools, to sort and merge the four Iso-Seq runs
  • bedGraphToBigWig and liftOver, both from the UCSC utilities
  • python3, for depmap_to_jbrowse.py and lift_bnd_vcf.py

The two python helpers are one file each:

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:

K562

K562 is a chronic myeloid leukemia line carrying the Philadelphia chromosome, the t(9;22) that fuses BCR to ABL1. Its transcripts here are long RNA reads, its fusion calls come from DepMap's short-read pipeline, and its DNA breakpoints from a linked-read run.

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 carries a second coordinate inside its ALT string, so a plain liftOver of the POS column produces a valid VCF whose partner coordinates still point at 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

The script's five arguments are the input VCF, the chain, the liftOver binary, the output VCF and a scratch directory.

Triaging the calls

The SV inspector opens the STAR-Fusion table beside a circular view of it, one chord per row. Add → SV inspector, then the file: the import form reads the File Type off a STAR-Fusion filename or the table's own header line, and the menu sets it by hand for a file named some other way.

Searching the table narrows both halves. chrM collects the rows that pair a gene with a mitochondrial transcript, the usual chimeric-read artefacts, and Mitelman leaves the two rows the fusion databases already know. chr9 leaves the same two, BCR--ABL1 and NUP214--XKR3: two junctions between chr9 and chr22 whose chr22 partners are 6.5 Mb apart, which the rest of the page shows to be the two ends of one amplified segment.

Each 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 turned so the fusion transcript reads left to right across the join. XKR3 is on the minus strand, so its region arrives reversed ([rev]). Turn on Read connections → View as pairs / link supplementary alignments to merge 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 green and each line is one Iso-Seq molecule running from NUP214 into XKR3. Open in JBrowse: Import form ↗ · All 44 calls ↗ · Searched for chr9 ↗ · Linked reads ↗ (large dataset — this session takes a while to load)

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38.
  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).

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? 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

This session spec pastes after &session=spec- on any JBrowse Web instance.

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

Loaded against config: https://jbrowse.org/demos/cancer_sv/config.json

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 — swap an adapter uri for your own file 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 \
  --session 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.

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38.
  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).

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? 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

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "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
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/cancer_sv/config.json

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 — swap an adapter uri for your own file 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 \
  --session 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.

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38.
  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).

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? 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

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "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
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/cancer_sv/config.json

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 — swap an adapter uri for your own file 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 \
  --session 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.

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “ncbi_refseq_hg38” track.
  3. Track menu → Gene glyph → Representative transcript“ncbi_refseq_hg38”.
  4. Drag the bar at the bottom edge of the track to resize it.“ncbi_refseq_hg38”.
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “K562_star_fusion” track.
  6. Track menu → Set feature height → Collapsed“K562_star_fusion”.
  7. Drag the bar at the bottom edge of the track to resize it.“K562_star_fusion”.
  8. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “K562_isoseq” track.
  9. Drag the bar at the bottom edge of the track to resize it.“K562_isoseq”.
  10. Drag the bottom edge of the coverage band to resize it.“K562_isoseq”.
  11. Track menu → Sashimi arcs → Show sashimi arcs (unchecked)Hides the splice-junction arcs and keeps the coverage band underneath them.“K562_isoseq”.
  12. 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.“K562_isoseq”.
  13. Track menu → Read connections → View as pairs / link supplementary alignments (checked)“K562_isoseq”.
  14. Track menu → Show... → Show legend (checked)“K562_isoseq”.
  15. 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.“K562_isoseq”.
  16. Track menu → Read connections → Read arcs“K562_isoseq”.
  17. 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.“K562_isoseq”.
  18. 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.“K562_isoseq”.
  19. Track menu → Read height → Custom... → 4px“K562_isoseq”.
  20. 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].
  21. 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.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? 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%22linkedReads%22%3A%22normal%22%2C%22showLegend%22%3Atrue%2C%22showBezierConnections%22%3Atrue%2C%22readConnections%22%3A%22arc%22%2C%22drawLongRange%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 spec pastes after &session=spec- on any JBrowse Web instance.

{
  "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"
          },
          "linkedReads": "normal",
          "showLegend": true,
          "showBezierConnections": true,
          "readConnections": "arc",
          "drawLongRange": false,
          "readConnectionsHeight": 90,
          "featureHeight": 4
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/cancer_sv/config.json

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"
                    },
                    "linkedReads": "normal",
                    "showLegend": True,
                    "showBezierConnections": True,
                    "readConnections": "arc",
                    "drawLongRange": False,
                    "readConnectionsHeight": 90,
                    "featureHeight": 4
                }
            ]
        }
    ],
)
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 — swap an adapter uri for your own file 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"
          },
          "linkedReads": "normal",
          "showLegend": true,
          "showBezierConnections": true,
          "readConnections": "arc",
          "drawLongRange": false,
          "readConnectionsHeight": 90,
          "featureHeight": 4
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --session 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.

BCR--ABL1 takes the rest of this page in the same layout. The build script adds the STAR-Fusion calls as this track:

{
  "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.

BCR-ABL1 across three regions

Right-click a read that crosses the junction and choose Split current view to show split alignments, or type the locations into the location box separated by spaces. The transcript reaches ABL1 at more than one place, so this view uses three regions, the BCR donor and two acceptor windows.

A read crossing the junction is one alignment on chr22 and a supplementary alignment on chr9. Read connections → Use curved connectors draws a curve between the two across the region divider. Filter by... → Split alignments → Only split alignments drops every read that stays on one chromosome.

Near-identical curves stack into one line. Read connections → Read arcs adds a band under the coverage where each junction is drawn once, thickened by the reads behind it. An arc needs both ends in view, and each acceptor window receives one. The vertical at the BCR donor stands for the 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 one counted arc from the BCR donor into each ABL1 window, and only the right-hand window carries a STAR-Fusion band. Open this view in JBrowse ↗

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “ncbi_refseq_hg38” track.
  3. Track menu → Gene glyph → Representative transcript“ncbi_refseq_hg38”.
  4. Drag the bar at the bottom edge of the track to resize it.“ncbi_refseq_hg38”.
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “K562_isoseq” track.
  6. Drag the bar at the bottom edge of the track to resize it.“K562_isoseq”.
  7. Drag the bottom edge of the coverage band to resize it.“K562_isoseq”.
  8. Track menu → Sashimi arcs → Show sashimi arcs (unchecked)Hides the splice-junction arcs and keeps the coverage band underneath them.“K562_isoseq”.
  9. 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.“K562_isoseq”.
  10. Track menu → Read connections → View as pairs / link supplementary alignments (checked)“K562_isoseq”.
  11. 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.“K562_isoseq”.
  12. Track menu → Read connections → Read arcs“K562_isoseq”.
  13. 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.“K562_isoseq”.
  14. Track menu → Show... → Show legend (checked)“K562_isoseq”.
  15. Track menu → Read height → Custom... → 4px“K562_isoseq”.
  16. 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.
  17. 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.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? 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%22linkedReads%22%3A%22normal%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

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "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"
          },
          "linkedReads": "normal",
          "showBezierConnections": true,
          "readConnections": "arc",
          "readConnectionsHeight": 90,
          "showLegend": true,
          "featureHeight": 4
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/cancer_sv/config.json

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"
                    },
                    "linkedReads": "normal",
                    "showBezierConnections": True,
                    "readConnections": "arc",
                    "readConnectionsHeight": 90,
                    "showLegend": True,
                    "featureHeight": 4
                }
            ]
        }
    ],
)
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 — swap an adapter uri for your own file 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"
          },
          "linkedReads": "normal",
          "showBezierConnections": true,
          "readConnections": "arc",
          "readConnectionsHeight": 90,
          "showLegend": true,
          "featureHeight": 4
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --session 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.

Where the DNA broke

A fusion caller only reports transcribed junctions, so both of its breakpoints sit on exon edges and mark neither where the chromosome broke nor how much of it is amplified. Two DNA assays on the same cells answer that: ENCODE's 10X Chromium linked-read run on K562 (ENCSR053AXS, Zhou et al. 2019) called the breakends, and DepMap's WGS segmentation gives the copy number. The build script lifts the breakends to hg38 and adds both as 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.

{
  "type": "QuantitativeTrack",
  "trackId": "K562_cn",
  "name": "K562 copy-number segments (DepMap WGS)",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "K562_cn.bw"
  }
}
jbrowse add-track K562_cn.bw \
  --trackId K562_cn \
  --name "K562 copy-number segments (DepMap WGS)" \
  --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..., choose Add track from pasted JSON, and paste:

{
  "type": "QuantitativeTrack",
  "trackId": "K562_cn",
  "name": "K562 copy-number segments (DepMap WGS)",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "K562_cn.bw"
  }
}

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, each switched to Display types → Variant display arcs. A call whose partner is on another chromosome draws a stem at its breakpoint with a tick toward the sequence it keeps.

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 this view in JBrowse ↗ (large dataset — this session takes a while to load)

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “ncbi_refseq_hg38” track.
  3. Track menu → Gene glyph → Representative transcript“ncbi_refseq_hg38”.
  4. Drag the bar at the bottom edge of the track to resize it.“ncbi_refseq_hg38”.
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “K562_star_fusion” track.
  6. Drag the bar at the bottom edge of the track to resize it.“K562_star_fusion”.
  7. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “K562_10x_sv” track.
  8. Drag the bar at the bottom edge of the track to resize it.“K562_10x_sv”.
  9. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “K562_cn” track.
  10. Drag the bar at the bottom edge of the track to resize it.“K562_cn”.
  11. Track menu → Score → Set min/max score...Pins the score axis: minimum 0 and maximum 8. An end left blank autoscales.“K562_cn”.
  12. Type your region of interest into the location box and press Enter.This figure is at chr9:130,690,000-131,320,000.
  13. 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.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? 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%22LinearPairedArcDisplay%22%2C%22height%22%3A50%7D%2C%7B%22trackId%22%3A%22K562_10x_sv%22%2C%22type%22%3A%22LinearPairedArcDisplay%22%2C%22height%22%3A50%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%7D%7D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+cancer_sv%2Fk562_amplicon_dna

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "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": "LinearPairedArcDisplay",
          "height": 50
        },
        {
          "trackId": "K562_10x_sv",
          "type": "LinearPairedArcDisplay",
          "height": 50
        },
        {
          "trackId": "K562_cn",
          "height": 130,
          "scales": {
            "y": {
              "domainMin": 0,
              "domainMax": 8
            }
          }
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/cancer_sv/config.json

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": "LinearPairedArcDisplay",
                    "height": 50
                },
                {
                    "trackId": "K562_10x_sv",
                    "type": "LinearPairedArcDisplay",
                    "height": 50
                },
                {
                    "trackId": "K562_cn",
                    "height": 130,
                    "scales": {
                        "y": {
                            "domainMin": 0,
                            "domainMax": 8
                        }
                    }
                }
            ]
        }
    ],
)
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 — swap an adapter uri for your own file 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": "LinearPairedArcDisplay",
          "height": 50
        },
        {
          "trackId": "K562_10x_sv",
          "type": "LinearPairedArcDisplay",
          "height": 50
        },
        {
          "trackId": "K562_cn",
          "height": 130,
          "scales": {
            "y": {
              "domainMin": 0,
              "domainMax": 8
            }
          }
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/cancer_sv/config.json \
  --session 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.

Both donors break a few hundred bases into the intron after their last retained exon. Both acceptors break upstream of the exon the transcript lands on, and the transcript is spliced from the break to that exon: a short hop for XKR3, a long one across ABL1's first intron.

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, and the right-hand break, whose partner on chr13 is not inside any gene, is the one a fusion caller cannot see. DepMap's segmentation covers no interval over BCR itself, so the donor's own window shows an arc but no copy-number step. SplitThreader applied the same reasoning to the ERBB2 amplicon in SK-BR-3 (Nattestad et al. 2018): copy-number steps and breakpoints describing the same interval are evidence of one event.

Reproduce it end to end

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

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

The script merges the four ENCODE Iso-Seq alignments, converts the DepMap release into a STAR-Fusion TSV and a copy-number bigWig, and lifts the ENCODE linked-read breakpoints onto hg38. The same run builds the COLO829 half of the demo, which Complex rearrangements and derivative alleles walks through.

See also

References

  • 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