Skip to main content

Display settings

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.

Every setting in a track menu has a name you can type into a config. We change three settings on one CRAM track by clicking, read their names back out of the session JSON, and use those names in a shareable link, a saved session file and config.json.

Prerequisites

  • JBrowse Web or JBrowse Desktop. The steps follow JBrowse Web, and a collapsed In JBrowse Desktop note covers each step that differs.

Open the volvox structural-variant CRAM track

volvox-sv (cram) is the structural-variant CRAM in volvox, the small demo dataset the JBrowse test builds ship. Open volvox at ctgA:1-10,000. The track opens as a pileup of short reads at the default height, in the default gray.

In JBrowse Desktop

Choose File → Session → Open JBrowse Web link... and paste the link above, or File → Session → Open config.json or .jbrowse file... and give it https://jbrowse.org/code/jb2/main/test_data/volvox/config.json. Desktop leaves a config you open unchanged and saves your edits to a separate session file.

Change height, color and read pairing from the track menu

Open the track's menu from the track label, then:

  • Choose Color by... → Paired end → Insert size and orientation, which leaves normally-paired reads gray and colors the rest by how they disagree with the reference.
  • Choose Read connections → View as pairs / link supplementary alignments, which puts each read on the same row as its mate.
  • Drag the bottom edge of the track down to about 250px, so the deeper stack of paired rows fits.

Advanced → Edit plot... is a second route to the color and unit: it shows them as text and applies edits live.

The volvox-sv (cram) track at ctgA:1-10,000 as a 250px-tall pileup, reads viewed as pairs and colored by insert size and orientation. The colored cluster at the left flags a structural variant.
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=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-10000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22volvox_sv_cram%22%2C%22height%22%3A250%2C%22unit%22%3A%22chain%22%2C%22color%22%3A%7B%22field%22%3A%22insertSizeAndOrientation%22%7D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+display_settings_url_snapshot

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 volvox, loaded from a .2bit genome.
  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 CRAM file (.cram + .crai).This figure uses “volvox-sv (cram)”.
    1. Track menu → Read connections → View as pairs / link supplementary alignments (checked)
    2. Track menu → Color by... → Paired end → Insert size and orientation
  3. Type your region of interest into the location box and press Enter.This figure is at ctgA:1-10000.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-10000",
      "tracks": [
        {
          "trackId": "volvox_sv_cram",
          "height": 250,
          "unit": "chain",
          "color": {
            "field": "insertSizeAndOrientation"
          }
        }
      ]
    }
  ]
}

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/volvox/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:1-10000",
            "tracks": [
                {
                    "trackId": "volvox_sv_cram",
                    "height": 250,
                    "unit": "chain",
                    "color": {
                        "field": "insertSizeAndOrientation"
                    }
                }
            ]
        }
    ],
)
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/code/jb2/main/test_data/volvox/config.json \
  --assembly volvox --loc ctgA:1-10000 \
  --track volvox_sv_cram '{"height":250,"unit":"chain","color":{"field":"insertSizeAndOrientation"}}' \
  --width 1500 --out figure.svg

--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": "volvox",
      "loc": "ctgA:1-10000",
      "tracks": [
        {
          "trackId": "volvox_sv_cram",
          "height": 250,
          "unit": "chain",
          "color": {
            "field": "insertSizeAndOrientation"
          }
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --width 1500 --height 540 \
  --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.

Read the setting names back out of the session JSON

Click Share and tick the Show readable JSON box below the link.

Two settings chosen from the volvox-sv (cram) track menu, then the share dialog with Show readable JSON ticked to display the session.

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

  1. From the track menu, color the reads by insert size and orientation
  2. Then link each read to its mate
  3. Share the session, and show it as readable JSON
  4. The whole session as JSON; the settings sit under trackConfigDeltas

Open this view in JBrowse Web ↗ · Open this view 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=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-10000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22volvox_sv_cram%22%2C%22height%22%3A250%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+config%2Fsettings_to_json

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 volvox, loaded from a .2bit genome.
  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 CRAM file (.cram + .crai).This figure uses “volvox-sv (cram)”.
  3. Type your region of interest into the location box and press Enter.This figure is at ctgA:1-10000.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-10000",
      "tracks": [
        {
          "trackId": "volvox_sv_cram",
          "height": 250
        }
      ]
    }
  ]
}

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/volvox/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:1-10000",
            "tracks": [
                {
                    "trackId": "volvox_sv_cram",
                    "height": 250
                }
            ]
        }
    ],
)
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/code/jb2/main/test_data/volvox/config.json \
  --assembly volvox --loc ctgA:1-10000 \
  --track volvox_sv_cram '{"height":250}' \
  --width 1920 --out figure.svg

--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": "volvox",
      "loc": "ctgA:1-10000",
      "tracks": [
        {
          "trackId": "volvox_sv_cram",
          "height": 250
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --width 1920 --height 860 \
  --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.

JBrowse Web saves an edit to a configured track as the settings that changed, so the session JSON lists the three settings under trackConfigDeltas, keyed by the id of the track you edited:

"trackConfigDeltas": {
  "volvox_sv_cram": {
    "displays": [
      {
        "displayId": "volvox_sv_cram-LinearAlignmentsDisplay",
        "height": 250,
        "unit": "chain",
        "color": { "field": "insertSizeAndOrientation" }
      }
    ]
  }
}
In JBrowse Desktop

Choose File → Session → Save session as..., save a volvox.jbrowse file, and open it in a text editor. A .jbrowse file is a whole config with the session under defaultSession, and Desktop writes a track edit into it, so the three keys appear in the volvox_sv_cram entry of its tracks array. Desktop autosaves the open session to the file about a second after each edit, and reopening the file restores every setting.

height, unit and color are the setting names in both apps. In grammar-of-graphics terms, color is a color scale, a field mapped to colors, and unit is the observation unit, a read or a chain. The config schema docs list the names and values each display takes (e.g. LinearAlignmentsDisplay, LinearWiggleDisplay).

Reading the JSON back finds the key for any setting on any track: change it in the menu, share, and read the new key.

Put the three settings in a track's displayDefaults

Settings saved in a session apply when that session opens. The same keys in a track's displayDefaults apply every time the track loads, and in a served config.json they apply for every visitor:

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

{
  "trackId": "volvox_sv_cram",
  "name": "volvox-sv (cram)",
  "uri": "volvox-sv.cram",
  "assemblyNames": ["volvox"],
  "displayDefaults": {
    "height": 250,
    "unit": "chain",
    "color": { "field": "insertSizeAndOrientation" }
  }
}
jbrowse add-track volvox-sv.cram \
  --trackId volvox_sv_cram \
  --name "volvox-sv (cram)" \
  --assemblyNames volvox \
  --displayDefaults '{"height":250,"unit":"chain","color":{"field":"insertSizeAndOrientation"}}' \
  --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": "volvox_sv_cram",
  "name": "volvox-sv (cram)",
  "uri": "volvox-sv.cram",
  "assemblyNames": ["volvox"],
  "displayDefaults": {
    "height": 250,
    "unit": "chain",
    "color": { "field": "insertSizeAndOrientation" }
  }
}

volvox-sv.cram is relative to a config.json. Replace it with its URL or its path on this computer.

The track opens paired and colored. To select a non-default display type, write a displays array; configuring tracks covers both forms.

When a session and the track config set the same setting

A session value overrides a track's displayDefaults one key at a time. The volvox config ships a gene track, gff3tabix_genes_shorthand_jexl, whose displayDefaults set color, a jexl expression that draws plus-strand features blue and minus-strand ones red, and labels, which names each feature with its type in brackets. This session sets color on that track and nothing else:

{
  "views": [
    {
      "assembly": "volvox",
      "loc": "ctgA:1-25000",
      "type": "LinearGenomeView",
      "tracks": [
        {
          "trackId": "gff3tabix_genes_shorthand_jexl",
          "color": "#8c8c8c"
        }
      ]
    }
  ]
}

Try this example live ↗ · Open it in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)

The session's color replaces the config's, so the features draw grey, and their labels still read seg04 [match] from displayDefaults.1

RouteKept inApplies to
Share link (?session=)the URLwhoever opens that link
Save session as... (Desktop)the .jbrowse filewhoever opens that file
displayDefaults in config.jsonthe config fileeveryone, every session
In JBrowse Desktop

Desktop has no address bar to paste a ?session= URL into. File → Session → Export session to web... uploads the session and gives you a JBrowse Web link with the settings encoded in it.

Pass the same settings to an embedded component

The embedded React components take the same keys through the view prop:

view: {
  loc: 'ctgA:1-10000',
  tracks: [
    {
      trackId: 'volvox_sv_cram',
      type: 'LinearAlignmentsDisplay',
      height: 250,
      unit: 'chain',
      color: { field: 'insertSizeAndOrientation' },
    },
  ],
}

See embedding the linear genome view for the surrounding setup.

See also

Notes

  1. Each entry in a view's tracks array is a plain trackId string or an object with trackId and settings written beside it. The inline settings are shorthand for a displaySnapshot key ({ "trackId": "...", "displaySnapshot": { "height": 100 } }); write the explicit form when you also need trackSnapshot for track-config fields. ↩