Display settings
The tutorials target the JBrowse v5 beta, and the v4.3.0 release
on the download page lacks some of what they show. To install the
beta of JBrowse Web, run npm install -g @jbrowse/cli@next, then
jbrowse create jbrowse2 --branch v5.0.0-beta.22. Desktop beta builds for Linux and
macOS are on the releases page;
the Windows build waits on code signing.
A change made from a track's menu lasts as long as the session that holds it. To make the same change for everyone who opens a track, you need the setting's name, and every setting in a track menu has one you can type into a config. On one CRAM track we:
- change three settings from the track menu and read their names back out of the session JSON in the Share dialog
- write those names into the track's
displayDefaultsinconfig.json - check which wins when a session and the track config set the same setting, and
where a link, a session file and
config.jsoneach keep it - pass the same settings to an embedded component through its
viewprop
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 change three settings:
- Choose Color by → 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 encoding.color and
unit: it shows them as text and applies edits live.
Read the setting names back out of the session JSON
Click Share, then the gear icon in the share dialog, then View session JSON.
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",
"encoding": { "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 encoding.color are the setting names in both apps. In
grammar-of-graphics terms, encoding.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).
To find the key for any setting on any track, change it in the menu, share, and read the new key from the JSON.
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",
"encoding": { "color": "insertSizeAndOrientation" }
}
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track volvox-sv.cram \
--trackId volvox_sv_cram \
--name "volvox-sv (cram)" \
--assemblyNames volvox \
--displayDefaults '{"height":250,"unit":"chain","encoding":{"color":"insertSizeAndOrientation"}}' \
--load copyIn 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",
"encoding": { "color": "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
With the CRAM track now set in two places, a session and config.json, the
session wins, one key at a time. The CRAM track in the shipped volvox config has
no displayDefaults to show that against, so this step uses a volvox gene
track, gff3tabix_genes_shorthand_jexl, whose displayDefaults set
encoding.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 encoding.color on that track and nothing else:
{
"views": [
{
"assembly": "volvox",
"loc": "ctgA:1-25000",
"type": "LinearGenomeView",
"tracks": [
{
"trackId": "gff3tabix_genes_shorthand_jexl",
"encoding": { "color": { "value": "#8c8c8c" } }
}
]
}
]
}Open this view in JBrowse Web ↗
Needs JBrowse Desktop 5.0 or newer. If nothing opens, copy the link and paste it into Desktop's Open JBrowse Web link..., on the start screen or under File → Session.
https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-25000%22%2C%22type%22%3A%22LinearGenomeView%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22gff3tabix_genes_shorthand_jexl%22%2C%22encoding%22%3A%7B%22color%22%3A%7B%22value%22%3A%22%238c8c8c%22%7D%7D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs+exampleQuickest: open the view, then File → Open track... for your files.
From scratch:
- Open your genome: Open your own genome in JBrowse Desktop, or
jbrowse add-assemblyfor JBrowse Web.This figure uses volvox, loaded from a .2bit genome. - Add your track: File → Open track..., or check it in the track selector. Needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “GFF3Tabix genes (shorthand jexl color + label)”.
- Track menu → Color by → Solid color... → #8c8c8c
- Go to your region in the location box.This figure is at ctgA:1-25000.
Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).
jbrowse add-track-json '{
"type": "FeatureTrack",
"trackId": "gff3tabix_genes_shorthand_jexl",
"name": "GFF3Tabix genes (shorthand jexl color + label)",
"assemblyNames": [
"volvox"
],
"adapter": {
"type": "Gff3TabixAdapter",
"uri": "YOUR_FILE"
},
"displayDefaults": {
"encoding": {
"color": {
"value": "#8c8c8c"
}
}
}
}'Run beside config.json, or add --out <dir>. Needs volvox in the config (jbrowse add-assembly).
This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.
from jbrowse_anywidget import JBrowseApp, fetch_hub
config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/volvox/config.json")
app = JBrowseApp(
assemblies=config["assemblies"],
tracks=config.get("tracks", []),
views=[
{
"assembly": "volvox",
"loc": "ctgA:1-25000",
"type": "LinearGenomeView",
"tracks": [
{
"trackId": "gff3tabix_genes_shorthand_jexl",
"encoding": {
"color": {
"value": "#8c8c8c"
}
}
}
]
}
],
)
app # display the widgetThis view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.
import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'
const configUrl = "https://jbrowse.org/code/jb2/main/test_data/volvox/config.json"
const configPromise = fetch(configUrl)
.then(res => res.json())
.then(config => {
addRelativeUris(config, new URL(configUrl))
return config
})
export default function Figure() {
const config = use(configPromise)
return (
<JBrowse
assemblies={config.assemblies}
tracks={config.tracks}
aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
configuration={config.configuration}
views={[
{
"assembly": "volvox",
"loc": "ctgA:1-25000",
"type": "LinearGenomeView",
"tracks": [
{
"trackId": "gff3tabix_genes_shorthand_jexl",
"encoding": {
"color": {
"value": "#8c8c8c"
}
}
}
]
}
]}
/>
)
}jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.
npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
--assembly volvox --loc ctgA:1-25000 \
--track gff3tabix_genes_shorthand_jexl '{"encoding":{"color":{"value":"#8c8c8c"}}}' \
--out figure.svgFor a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).
The session's encoding.color replaces the config's, so the features are drawn
grey, and their labels still read seg04 [match] from
displayDefaults.1
Where each route keeps a setting (link, session file or config)
| Route | Kept in | Applies to |
|---|---|---|
Share link (?session=) |
the URL | whoever opens that link |
| Save session as... (Desktop) | the .jbrowse file |
whoever opens that file |
displayDefaults in config.json |
the config file | everyone, 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 three keys through the view prop,
written beside the trackId in the view's tracks list:
view: {
loc: 'ctgA:1-10000',
tracks: [
{
trackId: 'volvox_sv_cram',
type: 'LinearAlignmentsDisplay',
height: 250,
unit: 'chain',
encoding: { color: 'insertSizeAndOrientation' },
},
],
}See embedding the linear genome view for the surrounding setup.
See also
- Tutorial: JBrowse CLI with Desktop
- Tutorial: Embedding JBrowse
- Config guide: Tracks
- Docs: URL query parameter API
- Docs: Config guide
Notes
-
Each entry in a view's
tracksarray is a plaintrackIdstring or an object withtrackIdand settings written beside it. The inline settings are shorthand for adisplaySnapshotkey ({ "trackId": "...", "displaySnapshot": { "height": 100 } }); write the explicit form when you also needtrackSnapshotfor track-config fields. ↩
Feedback on this tutorial is welcome: contact us.