Skip to main content

Highlights

A highlight is a translucent band over a genomic region. Every linear genome view (LGV) and dotplot showing the region's assembly draws it, and the session saves it, so a shared link carries it. The highlight list, opened from Tools → Highlights or Open highlight list in an LGV's menu, holds every highlight with a link back to it.

Making a highlight

  • Drag across the scalebar at the top of an LGV and pick Highlight region.
  • On a dotplot, drag a rectangle and pick Highlight region: the horizontal span bands the horizontal axis and the vertical span the vertical one.
  • Press Ctrl/Cmd + Shift + D to highlight the region in view.
  • Import a BED or TSV file from the highlight list's menu.
  • Pass them in a URL, a session or code, below.
Drag across the top of an LGV and pick 'Highlight region.' 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 hg19, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add your own track: File → Open track..., then 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 (hg19)”.
  3. Type your region of interest into the location box and press Enter.This figure is at chr10:89,613,000-89,740,000.

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=test_data%2Fconfig_demo.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg19%22%2C%22loc%22%3A%22chr10%3A89%2C613%2C000-89%2C740%2C000%22%2C%22tracks%22%3A%5B%22ncbi_gff_hg19%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+highlight_list_create

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr10:89,613,000-89,740,000",
      "tracks": [
        "ncbi_gff_hg19"
      ]
    }
  ]
}

Loaded against config: test_data/config_demo.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/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg19",
            "loc": "chr10:89,613,000-89,740,000",
            "tracks": [
                "ncbi_gff_hg19"
            ]
        }
    ],
)
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": "hg19",
      "loc": "chr10:89,613,000-89,740,000",
      "tracks": [
        "ncbi_gff_hg19"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.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.

A span of PTEN selected on the scalebar and highlighted, the highlight list opened from the view menu, the row named, and the view sent elsewhere on chr10 before the row's link brings it back to the highlighted span. Open the session this video starts in ↗

Open the session the video starts in ↗, then take the steps it shows:

  1. Highlight the span on screen
  2. Open the highlight list from the view menu
  3. PTEN 5' end
  4. chr10:100,000,000-100,200,000
  5. Click the row to navigate back

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 hg19, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add your own track: File → Open track..., then 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 (hg19)”.
  3. Type your region of interest into the location box and press Enter.This figure is at chr10:89,613,000-89,740,000.

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=test_data%2Fconfig_demo.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg19%22%2C%22loc%22%3A%22chr10%3A89%2C613%2C000-89%2C740%2C000%22%2C%22tracks%22%3A%5B%22ncbi_gff_hg19%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+ui%2Fhighlight_region

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr10:89,613,000-89,740,000",
      "tracks": [
        "ncbi_gff_hg19"
      ]
    }
  ]
}

Loaded against config: test_data/config_demo.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/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg19",
            "loc": "chr10:89,613,000-89,740,000",
            "tracks": [
                "ncbi_gff_hg19"
            ]
        }
    ],
)
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": "hg19",
      "loc": "chr10:89,613,000-89,740,000",
      "tracks": [
        "ncbi_gff_hg19"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.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 highlight list

  • The link in the Location column navigates the focused LGV on that assembly, or opens one, zoomed out a little for context. Ctrl/Cmd + Shift + M navigates to the newest highlight.
  • Click a Label cell and type to name a highlight. Show… → Show highlight labels in an LGV's menu shows or hides the names on the bands.
  • The Color column sets a band's color. Tick rows to recolor or delete several at once.
  • The list shows the highlights on an assembly some open view is showing, and says how many others it is hiding.
A label typed into the highlight list names the band on the LGV. 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 hg19, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add your own track: File → Open track..., then 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 (hg19)”.
  3. Type your region of interest into the location box and press Enter.This figure is at chr1:1-20,000.

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=test_data%2Fconfig_demo.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg19%22%2C%22loc%22%3A%22chr1%3A1-20%2C000%22%2C%22tracks%22%3A%5B%22ncbi_gff_hg19%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+highlight_list_edit_label

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr1:1-20,000",
      "tracks": [
        "ncbi_gff_hg19"
      ]
    }
  ]
}

Loaded against config: test_data/config_demo.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/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg19",
            "loc": "chr1:1-20,000",
            "tracks": [
                "ncbi_gff_hg19"
            ]
        }
    ],
)
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": "hg19",
      "loc": "chr1:1-20,000",
      "tracks": [
        "ncbi_gff_hg19"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.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.

Showing, hiding and removing

Show highlights hides or shows the bands in every view at once. An LGV has it under Show…, a dotplot at the top of its menu, and the list in its own menu. Making or recoloring a highlight shows them again.

A band's chip menu has Dismiss highlight. In the list, tick rows and press the delete icon.

Export and import

Export writes the ticked highlights, or every listed one, as BED (one file per assembly, 0-based starts) or TSV (one file with an assembly_name column, 1-based starts). Import reads either and adds to the list; a BED file takes the assembly picked in the dialog.

Setting highlights in code

Each form below takes a locstring or an object; an object adds color (used as-is, alpha included) and label, and an entry without assemblyName takes the view's assembly.

In a URL, &highlight= beside &assembly= and &loc=, several separated by spaces (%20): live link.

&assembly=volvox&loc=ctgA:1-20000&highlight=ctgA:5000-8000
&highlight={"refName":"ctgA","start":5000,"end":8000,"color":"rgba(240,128,128,0.3)","label":"my region"}

In a session spec or defaultSession, as highlight on a view. The dotplot takes the same key (dotplot highlights):

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-20000",
      "highlight": ["ctgA:5000-8000"]
    }
  ]
}

In a saved session, the session's highlights list, where each entry names its assembly:

"highlights": [
  { "assemblyName": "volvox", "refName": "ctgA", "start": 5000, "end": 8000, "label": "my region" }
]

In an embedded LGV or from a plugin, highlight in createViewState at launch (Embedded components); after that, session.addHighlight takes an object like the one above, session.setHighlights replaces the list ([] clears it), and removeHighlight and updateHighlight take an entry of session.highlights. A view's highlights lists the ones on its own assemblies. The BaseSessionModel reference has the rest.