URL query parameter API

JBrowse Web reads its launch state from the URL. Embedded components such as @jbrowse/react-linear-genome-view2 leave URL handling to the host app.

Query string or hash fragment#

• Every parameter works in either place: ?config=…&loc=… or #config=…&loc=….
• A fragment is never sent to the server, so a long value (an encoded- or json- session, a whole session spec, a big &sessionTracks=) cannot trip the request-line limit that answers a long query string with HTTP 414. The Share button writes every link as a hash URL, which also keeps a short link's key out of the web server's logs.
• If the fragment contains an =, JBrowse reads its parameters only from there and ignores the query string. A link must therefore put every parameter in the fragment: ?config=my.json#session=spec-{…} loads the default config.json, not my.json.

Linear genome view (simple)#

One linear genome view, from a handful of parameters:

http://host/jbrowse2/?config=test_data/config.json&loc=chr1:6000-7000&assembly=hg19&tracks=gene_track,vcf_track

• &assembly=, &loc=, &regions=, &nav=, &tracks=, &tracklist=, &highlight=, &sessionTracks= and &extendSession= apply only to this launch. Every other launch type holds the same settings inside the session it loads.
• ?config=, &sessionName=, &hubURL=, &renderer= and &session= work for any launch type.
• &password= holds an older &session=share- link's key, and &adminKey= belongs to JBrowse CLI admin server.

?config=#

?config=test_data/volvox/config.json

• A path to a config file, relative to the current folder, fetched by the client. Omitted, JBrowse loads config.json from the current folder, which @jbrowse/cli sets up.
• ?config=none skips the config entirely, for a &hubURL= whose hub supplies the assemblies and tracks.
• To change the default without putting ?config= in every link, set window.__jbrowseConfigPath in the <head> of index.html (Avoiding stale config). An explicit ?config= still wins.

&assembly=#

&assembly=hg19, the name of an entry in the config's assemblies array.

&loc=#

&loc=chr1:6000-7000, navigated to on load. Accepted forms:

&loc=chr1:6000-7000 // using - notation for range
&loc=chr1:6000..7000 // using .. notation for range
&loc=chr1:7000 // centered on this position
&loc=chr1 // the whole of one chromosome
&loc=chr1%206000%207000 // refName, start and end, whitespace separated
&loc=chr1:34M-35M // coordinates abbreviated with a unit suffix
&loc=GENEID // if you have used `jbrowse text-index`

• A coordinate takes a k, M or G suffix, optionally followed by b or bp, and is expanded to whole base pairs on load.
• A gene name needs a text index: one built with jbrowse text-index, or a hub track's own searchIndex (track hubs).
• Several whitespace-separated locstrings (%20 in a URL) open a discontinuous view showing each region in turn: a gene and its fusion partner, an allele beside the sequences it derives from. The location box displays the same form once a view holds more than one region, so what you copy out of it pastes back into a URL.
• &loc= and &assembly= start a fresh session, ignoring the config's defaultSession; &extendSession=true navigates that session instead.

&regions=#

&assembly=hg38&regions=chr1,chr2,chr3

Restricts the whole-genome overview to this subset of the assembly's chromosomes, in this order, for dropping unplaced contigs or reordering. Names resolve through the assembly's aliases and take globs. It requires &assembly=, is ignored when &loc= is set, and is the simple-URL form of the spec's displayedRegionNames.

&highlight=#

&highlight=chr1:6000-7000, a band over the region on every track, with &assembly= and &loc=.

• Several regions are space-separated (%20).
• Always pass &assembly=. A highlight is stored with an assembly name, and every view of that assembly draws it; a saved session keeps them in its highlights list, where each entry takes assemblyName.
• The highlight list shows them, with links back to each.
• A URL-encoded JSON object in place of a locstring adds color (used as-is, alpha included) and label (shown beside the chip icon): &highlight={"refName":"11","start":32200274,"end":32203877,"color":"rgba(240,128,128,0.3)","label":"R2_intron"}. Locstrings and JSON objects can be mixed in one value.
• To box one feature by name and sort it to the top of its track, see featureHighlights.

&tracklist=#

&tracklist=true opens the track selector on load. Default false.

&nav=#

&nav=false hides the linear genome view's navigation bar. Default true.

&tracks=#

&tracks=gene_track,vcf_track, a comma-separated list of trackIds from the config. A trackId added by &sessionTracks= can be named here too.

&sessionTracks=#

Adds track configs to the session from the URL. A track over a data file needs no type or adapter, since the extension gives both, but nothing implies its assembly, so name it (the shortest track):

&sessionTracks=[{"trackId":"reads","uri":"https://example.com/sample.bam","assemblyNames":["hg38"]}]

A track with no data file, such as BLAST hits included inline as a FromConfigAdapter, takes the full form. Live link, whose value pretty-printed is:

[
  {
    "type": "FeatureTrack",
    "trackId": "url_track",
    "name": "URL track",
    "assemblyNames": ["volvox"],
    "adapter": {
      "type": "FromConfigAdapter",
      "features": [
        {
          "uniqueId": "one",
          "refName": "ctgA",
          "start": 100,
          "end": 200,
          "name": "Boris"
        }
      ]
    }
  }
]

&sessionName=#

&sessionName=My%20Custom%20Session names the session in the header bar, for any launch type. Without it the name is generated with a timestamp.

&hubURL=#

&hubURL=https://example.com/hub.txt&config=none

• Loads one or more UCSC track hubs (comma-separated) as a session, usually with ?config=none since the hub supplies the assemblies and tracks.
• &assembly= and &loc= open the hub at a place; &assembly= is required, since it names the hub genome &loc= resolves against: ?config=none&hubURL=https://example.com/hub.txt&assembly=GCF_019202715.1&loc=chr1:1-100000.
• &sessionTracks= registers into the hub session, so &tracks= can name one of them beside the hub's own.
• Each hub opens with a single linear genome view. For several views, a workspace layout or a dotplot, put the hub in a session spec's sessionConnections.
• Opening track hubs by URL is the full workflow.

&renderer=#

&renderer=webgl pins the drawing backend, overriding detection: webgpu, webgl, or canvas2d (alias canvas). A pin never falls through, so a backend that cannot start shows an error on every track. It is a debugging aid (my tracks are blank), and JBrowse Desktop takes the same choice as --renderer.

&safeMode#

&safeMode, bare, loads without the plugins this browser keeps for this configuration, for one load only. Use it when a plugin crashes the app before any menu is on screen; the fatal error dialog offers the same thing as a button.

Navigating within the default session#

&extendSession=true beside &loc= navigates a curated defaultSession instead of replacing it:

?loc=chr1:100000-200000&extendSession=true

&loc=, &tracks=, &highlight=, &nav= and &tracklist= then apply to the first linear genome view of that session, whose assembly is used, so &assembly= is not needed. &sessionTracks= is not layered on; a session spec is the way to add a track config to a curated session.

Which parameter decides the launch#

A link can contain several of these at once, and they do not combine: one decides what opens and the rest are layered onto it or dropped. Highest first:

• &session=, in any form (spec-, share-, encoded-, json-, local-). A value matching none of those prefixes is an error.
• &extendSession=true beside &loc=/&assembly=, which navigates the config's defaultSession. It outranks a hub, which would otherwise replace that session.
• &hubURL=. A link with both a hub and &loc= navigates inside the hub.
• &loc=/&assembly= alone open a fresh single linear genome view.
• A link with none of these opens the config's defaultSession.

?config=, &sessionName= and &renderer= sit outside the ranking and apply to whichever launch wins. &sessionTracks= applies to the hub launch and to the bare shorthand. A default session or &session= lists its tracks itself, so &sessionTracks= adds none there.

Session spec#

A session spec is the session as JSON in the URL, the value of &session= prefixed spec-:

&session=spec-{"views":[{"type":"LinearGenomeView","assembly":"volvox","loc":"ctgA:1-5100"}]}

{
  "views": [
    {
      "assembly": "volvox",
      "loc": "ctgA:1-5100",
      "type": "LinearGenomeView",
      "tracks": [
        "gff3tabix_genes",
        "volvox_filtered_vcf",
        "volvox_microarray",
        "volvox_cram"
      ]
    }
  ]
}

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-5100%22%2C%22type%22%3A%22LinearGenomeView%22%2C%22tracks%22%3A%5B%22gff3tabix_genes%22%2C%22volvox_filtered_vcf%22%2C%22volvox_microarray%22%2C%22volvox_cram%22%5D%7D%5D%7D&sessionName=JBrowse+docs+example

• Each view object lists the keys it launches with, written directly on the view. A defaultSession in a config uses the same object (Config and session JSON), so a view moves between a spec, a config and an addView call unchanged.
• views takes several views, opened together. loc is optional; omitting it shows the whole genome. Other view types take other keys: a dotplot takes two assemblies.
• Each view's type dispatches to a LaunchView-<type> extension point, which is how plugins add launchable view types.

Session-wide fields#

Four top-level arrays furnish the session the views open into, applied in this order so each can name what the ones before it registered:

• sessionAssemblies registers assemblies. With ?config=none a spec is then fully self-contained: a novel assembly, its tracks, and the views over them.
• sessionConnections attaches connections, UCSC track hubs or JBrowse hubs, and waits for each to finish fetching before launching the views, so a view can name an assembly or trackId the connection supplies. A spec with no views leaves the connection to open a view. &hubURL= relies on exactly this.
• sessionTracks registers track configs, the spec form of &sessionTracks=.
• views, then a layout that tiles them into a workspace.

Everything a session holds this way stays with the session: opening the link never writes into the config.json the instance serves.

{
  "sessionAssemblies": [
    {
      "name": "my_assembly",
      "uri": "https://example.com/my_assembly.2bit"
    }
  ],
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "my_track",
      "name": "My track",
      "assemblyNames": ["my_assembly"],
      "adapter": { "type": "FromConfigAdapter", "features": [] }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "my_assembly",
      "tracks": ["my_track"]
    }
  ]
}

{
  "sessionConnections": [
    {
      "type": "UCSCTrackHubConnection",
      "connectionId": "my_hub",
      "name": "My hub",
      "hubTxtLocation": { "uri": "https://example.com/hub.txt" }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "GCF_019202715.1",
      "loc": "chr1:1-100000"
    }
  ]
}

&sessionName= names a spec's session the same as any other launch.

Fields every view takes#

• id pins the created view's id so another view in the same spec can point at it (an MsaView's connectedViewId). It is the one key the launcher reserves; the rest of what every view takes comes from BaseViewModel and appears in each view's table below, displayName among them.
• displayedRegionNames is the spec form of &regions=: with no loc, it restricts the whole-genome overview to these chromosomes, in this order. It works on the linear genome view, the circular view, each axis of a dotplot and each row of a synteny view. Volvox showing its two contigs, order reversed:

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "displayedRegionNames": ["ctgB", "ctgA"],
      "tracks": ["gff3tabix_genes"]
    }
  ]
}

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%22displayedRegionNames%22%3A%5B%22ctgB%22%2C%22ctgA%22%5D%2C%22tracks%22%3A%5B%22gff3tabix_genes%22%5D%7D%5D%7D&sessionName=JBrowse+docs+example

Glob region names#

An entry containing * is a glob matched against the refName, so ["*_hap1"] covers sixteen scaffolds in one entry and survives the assembly being rebuilt.

• * is the only metacharacter; regex punctuation in a refName (chr1.1, scaffold[2]) matches literally.
• A glob contributes its matches in the assembly's order; exact names contribute in the order written, and entries already taken are skipped, so ["chr1_hap1", "*_hap1"] reads as "chr1 first, then the rest of hap1".
• Globs match aliases and match case-insensitively, the same as an exact entry. A name matching nothing is dropped, and a list matching nothing at all is reported.
• There is no negation, and on a UCSC-style assembly chr* also takes chrUn_GL000195v1 and chr1_KI270706v1_random, while chr1* takes chr10 through chr19. Globs suit name families an assembly separates (*_hap1, *_MATERNAL, *_alt); a main-chromosome subset is best written as a list.
• The dotplot and synteny import forms put the same syntax in a text box beside each assembly.

Advanced track configuration#

A tracks entry is a trackId string, or an object with initial display state:

{
  "views": [
    {
      "assembly": "volvox",
      "loc": "ctgA:1-5100",
      "type": "LinearGenomeView",
      "tracks": [
        "simple_track_id",
        {
          "trackId": "my_bam_track",
          "displaySnapshot": {
            "type": "LinearAlignmentsDisplay",
            "height": 300
          }
        },
        {
          "trackId": "my_wiggle_track",
          "displaySnapshot": {
            "encoding": {
              "y": { "scale": { "domainMin": 0, "domainMax": 100 } }
            }
          }
        }
      ]
    }
  ]
}

• displaySnapshot takes anything the display's menu offers: type to pick a display, height, encoding.color (a field, or a value holding a CSS color or a jexl: expression), encoding.y on a quantitative track (YChannel), forceLoad to render past the "too much data" gate (BaseLinearDisplay).
• trackSnapshot sets track state such as pinned: true.
• Any other key on the object is a display setting, so { "trackId": "my_bam_track", "type": "LinearAlignmentsDisplay", "height": 300 } is the shorthand for the nested form. Use the explicit form when you also pass trackSnapshot.
• modifiers takes the jb2export command line's track options, such as ["color:strand", "sort:base", "encoding.color.field=tags.HP"]. A linear genome view applies them over the entry's other settings once it has navigated, so sort: pivots at the view's center.

Linear genome view#

A LinearGenomeView object takes the simple params plus grow, which pads loc by that fraction on each side (0.2 pads 20%), and showHitTrack, which sets whether a loc that is a gene name also opens the track the name was found in (by default, only when the view lists no tracks). Beyond those it takes any property the state model declares.

Linear genome view properties#

Launch keys, resolved once on attach and then discarded, because they have no direct representation in the view's state — assembly, displayedRegionNames, grow, highlight, loc, nav, showHitTrack, tracklist. There are no others; a key outside this set and the table below is a typo, and the launcher names it in a console warning.

Properties, which are whatever the state model declares and the view restores natively:

• bpPerPx and offsetPx are the zoom and the horizontal scroll, and they are the exception to the typo rule above: the view stores its viewport as a genomic window now, so neither is a declared property, but the view still accepts and converts both. loc survives an assembly whose regions were rebuilt; use these two only to reproduce a viewport to the pixel. The conversion stores the old zoom, until the view's first width measure, as legacyBpPerPx, a declared property for saved sessions. Write the window fields above (or loc) rather than setting it yourself.
• displayedRegions gives the regions the view lays out as full {refName, start, end, assemblyName} objects, which is the form for showing part of a chromosome; displayedRegionNames names whole ones.
• showCytobands and showTrackOutlines default to the visitor's stored preference, so set them explicitly in a link that has to look the same for everyone.
• showCytobandsSetting is the old name of showCytobands. It is not a declared property, but the view converts it on the way in, so a v4 link or saved spec naming it still works; write showCytobands in a new one.
• colorByCDS is the old name of colorByFrame, converted the same way.

Live example: alignments display settings#

An alignments track colored by pair orientation, with soft-clipped bases shown and an enlarged height. Swapping pileup.softClips for pileup.connectors draws a connector between the mates of each aberrant pair and across split-read junctions:

{
  "views": [
    {
      "assembly": "volvox",
      "loc": "ctgA:1-10000",
      "type": "LinearGenomeView",
      "tracks": [
        {
          "trackId": "volvox_sv_cram",
          "displaySnapshot": {
            "height": 250,
            "pileup": { "softClips": { "show": true } },
            "encoding": { "color": "pairOrientation" }
          }
        }
      ]
    }
  ]
}

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-10000%22%2C%22type%22%3A%22LinearGenomeView%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22volvox_sv_cram%22%2C%22displaySnapshot%22%3A%7B%22height%22%3A250%2C%22pileup%22%3A%7B%22softClips%22%3A%7B%22show%22%3Atrue%7D%7D%2C%22encoding%22%3A%7B%22color%22%3A%22pairOrientation%22%7D%7D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs+example

Live example: feature track color#

encoding.color on a feature track's display takes a value holding a CSS color, or a jexl: expression such as "jexl:get(feature,'type')=='gene'?'blue':'gray'" to color per feature:

{
  "views": [
    {
      "assembly": "volvox",
      "loc": "ctgA:1-50000",
      "type": "LinearGenomeView",
      "tracks": [
        {
          "trackId": "gff3tabix_genes",
          "displaySnapshot": {
            "encoding": { "color": { "value": "green" } }
          }
        }
      ]
    }
  ]
}

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-50000%22%2C%22type%22%3A%22LinearGenomeView%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22gff3tabix_genes%22%2C%22displaySnapshot%22%3A%7B%22encoding%22%3A%7B%22color%22%3A%7B%22value%22%3A%22green%22%7D%7D%7D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs+example

Live example: highlight a feature, and sort it to the top#

&highlight= paints a band over a region across every track. To box one feature at whatever row the track's layout puts it, set featureHighlights on the display, the same state the right-click "Highlight feature" item and a feature search write (LinearBasicDisplay, LinearVariantDisplay, and every other canvas display):

{
  "views": [
    {
      "assembly": "volvox",
      "loc": "ctgA:1-50000",
      "type": "LinearGenomeView",
      "tracks": [
        {
          "trackId": "gff3tabix_genes",
          "displaySnapshot": {
            "height": 200,
            "featureHighlights": [{ "refName": "ctgA", "name": "EDEN" }]
          }
        }
      ]
    }
  ]
}

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-50000%22%2C%22type%22%3A%22LinearGenomeView%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22gff3tabix_genes%22%2C%22displaySnapshot%22%3A%7B%22height%22%3A200%2C%22featureHighlights%22%3A%5B%7B%22refName%22%3A%22ctgA%22%2C%22name%22%3A%22EDEN%22%7D%5D%7D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs+example

• A declarative highlight also sorts its feature to a top row of the track, ahead of the row packer's order, and holds it there across pan and zoom.
• By name, {"refName": "ctgA", "name": "EDEN"}, matched exactly and case-insensitively within that refName. Prefer this. A name that is ambiguous (a gene and its same-named transcript) boxes both.
• By span, {"refName": "ctgA", "start": 1049, "end": 9000}, in interbase coordinates, matched within one base of the track's record. A location box reads the same feature as ctgA:1,050-9,000, so coordinates copied off the screen are a base short at the start. An entry with both forms falls back to name when the span misses.
• A span that resolves to nothing logs a console warning once data covering it has loaded; a name that resolves to nothing logs no warning. The clear-highlights button in the view header removes them.

Circular view#

The circular view shows the whole genome, so there is no loc. It takes assembly, tracks, displayedRegionNames (which chromosomes get an arc, in that order, globs allowed) and height, which sizes the drawing since the circle auto-fits its container.

{
  "views": [
    {
      "assembly": "volvox",
      "type": "CircularView",
      "tracks": ["volvox_sv_test"]
    }
  ]
}

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%22type%22%3A%22CircularView%22%2C%22tracks%22%3A%5B%22volvox_sv_test%22%5D%7D%5D%7D&sessionName=JBrowse+docs+example

Circular view properties#

Launch keys, which name something to do on load rather than state the view holds:

Properties, which are whatever the state model declares and the view restores natively:

bpPerPx and offsetRadians are the circle's zoom and rotation; pairing them with autoFit: false stops the first resize refitting over them.

Dotplot view#

{
  "views": [
    {
      "type": "DotplotView",
      "views": [
        {
          "assembly": "volvox"
        },
        {
          "assembly": "volvox"
        }
      ],
      "tracks": ["volvox_fake_synteny"]
    }
  ]
}

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig_main_thread.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22DotplotView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22volvox%22%7D%2C%7B%22assembly%22%3A%22volvox%22%7D%5D%2C%22tracks%22%3A%5B%22volvox_fake_synteny%22%5D%7D%5D%7D&sessionName=JBrowse+docs+example

• views[0] is the horizontal axis and views[1] the vertical. Each takes an optional loc to navigate that axis; omit it for a whole-genome overview.
• Each also takes displayedRegionNames, which changes what the axis displays at all where loc navigates within it. A haplotype-resolved assembly shown whole interleaves both haplotypes, and ["*_hap1"] on one axis plots one haplotype against the reference. It is applied before autoDiagonalize.

Dotplot view properties#

Launch keys, which name something to do on load rather than state the view holds:

Properties, which are whatever the state model declares and the view restores natively:

Dotplot highlights#

highlight works as it does on the linear genome view. A region draws as a vertical band when its assembly matches the horizontal axis and a horizontal band when it matches the vertical one, so on a self-vs-self plot it appears on both. Include assemblyName to tie a band to one axis of a non-self plot.

{
  "views": [
    {
      "type": "DotplotView",
      "views": [
        { "assembly": "volvox", "loc": "ctgA:1-50000" },
        { "assembly": "volvox", "loc": "ctgA:1-50000" }
      ],
      "tracks": ["volvox_fake_synteny"],
      "highlight": ["ctgA:5000-15000"]
    }
  ]
}

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig_main_thread.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22DotplotView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-50000%22%7D%2C%7B%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-50000%22%7D%5D%2C%22tracks%22%3A%5B%22volvox_fake_synteny%22%5D%2C%22highlight%22%3A%5B%22ctgA%3A5000-15000%22%5D%7D%5D%7D&sessionName=JBrowse+docs+example

Linear synteny view#

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "tracks": ["volvox_fake_synteny"],
      "views": [
        {
          "loc": "ctgA:1-30000",
          "assembly": "volvox"
        },
        {
          "loc": "ctgA:1000-31000",
          "assembly": "volvox"
        }
      ]
    }
  ]
}

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22tracks%22%3A%5B%22volvox_fake_synteny%22%5D%2C%22views%22%3A%5B%7B%22loc%22%3A%22ctgA%3A1-30000%22%2C%22assembly%22%3A%22volvox%22%7D%2C%7B%22loc%22%3A%22ctgA%3A1000-31000%22%2C%22assembly%22%3A%22volvox%22%7D%5D%7D%5D%7D&sessionName=JBrowse+docs+example

• Each entry in views is one genome row, a linear genome view, so it takes the LGV's keys and launch props (trackLabels, colorByFrame, showAminoAcids), and its tracks entries take inline display options.
• displayedRegionNames restricts a row to a subset of its assembly, with globs, so a whole-genome view can put one haplotype on each row (["*_MATERNAL"] above ["*_PATERNAL"]). loc navigates within what a row displays and takes precedence.
• A self-self alignment is allowed.

Linear synteny view properties#

Top-level fields set the view's initial display state. The same view colored by strand, with curved ribbons and stronger opacity:

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "tracks": ["volvox_fake_synteny"],
      "encoding": { "color": "strand", "opacity": 0.8 },
      "mark": { "interpolate": "bump" },
      "views": [
        { "loc": "ctgA:1-30000", "assembly": "volvox" },
        { "loc": "ctgA:1000-31000", "assembly": "volvox" }
      ]
    }
  ]
}

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22tracks%22%3A%5B%22volvox_fake_synteny%22%5D%2C%22encoding%22%3A%7B%22color%22%3A%22strand%22%2C%22opacity%22%3A0.8%7D%2C%22mark%22%3A%7B%22interpolate%22%3A%22bump%22%7D%2C%22views%22%3A%5B%7B%22loc%22%3A%22ctgA%3A1-30000%22%2C%22assembly%22%3A%22volvox%22%7D%2C%7B%22loc%22%3A%22ctgA%3A1000-31000%22%2C%22assembly%22%3A%22volvox%22%7D%5D%7D%5D%7D&sessionName=JBrowse+docs+example

The v4 spellings colorBy and alpha still open, as encoding.color and encoding.opacity, and the betas' cigarMode and drawCigar as indels.

Launch keys, which name something to do on load rather than state the view holds:

Properties, which are whatever the state model declares and the view restores natively:

levels is accepted because the view declares it; tracks fills it and levelHeights sizes them, so use levels only to author a band's full state.

Linear synteny view (multi-way)#

With three or more rows, each track in a flat tracks list goes on every band whose two rows its assemblyNames cover. A pairwise track goes on its one band, and one multi-genome track covers the whole stack:

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "tracks": ["volvox_ins.paf", "volvox_del.paf"],
      "views": [
        { "loc": "ctgA:1-50000", "assembly": "volvox_ins" },
        { "loc": "ctgA:1000-50000", "assembly": "volvox" },
        { "loc": "ctgA:1000-44000", "assembly": "volvox_del" }
      ]
    }
  ]
}

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22tracks%22%3A%5B%22volvox_ins.paf%22%2C%22volvox_del.paf%22%5D%2C%22views%22%3A%5B%7B%22loc%22%3A%22ctgA%3A1-50000%22%2C%22assembly%22%3A%22volvox_ins%22%7D%2C%7B%22loc%22%3A%22ctgA%3A1000-50000%22%2C%22assembly%22%3A%22volvox%22%7D%2C%7B%22loc%22%3A%22ctgA%3A1000-44000%22%2C%22assembly%22%3A%22volvox_del%22%7D%5D%7D%5D%7D&sessionName=JBrowse+docs+example

• A track that covers no band, or whose config names no assemblyNames, is reported and not drawn.
• A list of lists names each band's tracks instead, tracks[i] between rows i and i + 1. Use it to give a band a different track than its coverage picks, or none.

Breakpoint split view#

{
  "views": [
    {
      "type": "BreakpointSplitView",
      "views": [
        {
          "loc": "ctgA:1-5000",
          "assembly": "volvox",
          "tracks": ["volvox_cram"]
        },
        {
          "loc": "ctgB:1-5000",
          "assembly": "volvox",
          "tracks": ["volvox_cram"]
        }
      ]
    }
  ]
}

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22BreakpointSplitView%22%2C%22views%22%3A%5B%7B%22loc%22%3A%22ctgA%3A1-5000%22%2C%22assembly%22%3A%22volvox%22%2C%22tracks%22%3A%5B%22volvox_cram%22%5D%7D%2C%7B%22loc%22%3A%22ctgB%3A1-5000%22%2C%22assembly%22%3A%22volvox%22%2C%22tracks%22%3A%5B%22volvox_cram%22%5D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs+example

views lists the two or more linear genome views that make up the split view, each with a location, an assembly and tracks. Beside views, the spec accepts every setting the view's menu offers:

Spreadsheet view#

{
  "views": [
    {
      "type": "SpreadsheetView",
      "uri": "test_data/volvox/volvox.filtered.vcf.gz",
      "assembly": "volvox"
    }
  ]
}

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22SpreadsheetView%22%2C%22uri%22%3A%22test_data%2Fvolvox%2Fvolvox.filtered.vcf.gz%22%2C%22assembly%22%3A%22volvox%22%7D%5D%7D&sessionName=JBrowse+docs+example

Launch keys, which name something to do on load rather than state the view holds:

Properties, which are whatever the state model declares and the view restores natively:

fileType is one of VCF, BED, BEDPE or STAR-Fusion, for a URL with no extension or a STAR-Fusion file, which has no extension.

SV inspector#

{
  "views": [
    {
      "type": "SvInspectorView",
      "uri": "test_data/volvox/volvox.dup.vcf.gz",
      "assembly": "volvox"
    }
  ]
}

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22SvInspectorView%22%2C%22uri%22%3A%22test_data%2Fvolvox%2Fvolvox.dup.vcf.gz%22%2C%22assembly%22%3A%22volvox%22%7D%5D%7D&sessionName=JBrowse+docs+example

The circular half draws the rows the spreadsheet half's filter leaves, so filterText makes a chord subset reachable from a link.

Launch keys, which name something to do on load rather than state the view holds:

Properties, which are whatever the state model declares and the view restores natively:

Plugin-provided view types#

A plugin makes its view launchable by registering a LaunchView-<type> extension point. Once the plugin is loaded, through the config's plugins, a hosted config, or a session's sessionPlugins, a spec launches its view by type. Each plugin's launch-parameters page lists its fields:

• ProteinView from jbrowse-plugin-protein3d (uniprotId, pdbId, url, structures, transcriptId, connectedView). Every link in the TP53 structures tutorial is one of these specs.
• MsaView from jbrowse-plugin-msaview (msa, tree, msaFileLocation, connectedViewId, connectedTranscript).

Tiled views / Workspaces#

A spec's layout arranges its views into a tiled workspace. It is a tree of two kinds of node:

• a panel, with a views array of indices into the spec's views, stacked vertically. An index names every view that entry created: a ProteinView with a connectedView opens its genome view and then the structure, and its index is the pair, stacked. An entry may also be a view id the spec pinned with id, to place one of those views alone
• a container, with children and a direction: "horizontal", "vertical" or "tabs" (one tab group, one child visible at a time)

Containers nest arbitrarily deep. An index past the end, or an id no view in the spec has, is reported and left out of the layout. The live session takes the same layout tree: session.applyLayoutSpec(layout) (see the live model guide) counts a panel's indices into session.views instead, and refuses a panel spelled any other way.

Views 0 and 1 stacked in a left panel taking 70% of the width, view 2 alone on the right:

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-5000",
      "tracks": ["gff3tabix_genes"]
    },
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:5000-10000",
      "tracks": ["gff3tabix_genes"]
    },
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgB:1-5000",
      "tracks": ["gff3tabix_genes"]
    }
  ],
  "layout": {
    "direction": "horizontal",
    "children": [
      { "views": [0, 1], "size": 70 },
      { "views": [2], "size": 30 }
    ]
  }
}

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-5000%22%2C%22tracks%22%3A%5B%22gff3tabix_genes%22%5D%7D%2C%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A5000-10000%22%2C%22tracks%22%3A%5B%22gff3tabix_genes%22%5D%7D%2C%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgB%3A1-5000%22%2C%22tracks%22%3A%5B%22gff3tabix_genes%22%5D%7D%5D%2C%22layout%22%3A%7B%22direction%22%3A%22horizontal%22%2C%22children%22%3A%5B%7B%22views%22%3A%5B0%2C1%5D%2C%22size%22%3A70%7D%2C%7B%22views%22%3A%5B2%5D%2C%22size%22%3A30%7D%5D%7D%7D&sessionName=JBrowse+docs+example

• size is a panel's proportion of the split, at any depth: a nested container sizes its children as well as taking a share of its parent.
• Size every sibling and the numbers are proportions, so 7 and 3 lay out the same as 70 and 30. Leave one bare and they are read as percentages, the bare panel taking what the sized ones leave: 70 beside a bare panel is 70/30, and 7 beside a bare panel is 7/93.
• Dragging the divider adjusts from there, and the position is saved with the session.

A fixed reference panel on the left, and a set of tabs to page through on the right:

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-5000",
      "tracks": ["gff3tabix_genes"]
    },
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-5000",
      "tracks": ["volvox_sv_test"]
    },
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgB:1-5000",
      "tracks": ["gff3tabix_genes"]
    }
  ],
  "layout": {
    "direction": "horizontal",
    "children": [
      { "views": [0] },
      {
        "direction": "tabs",
        "children": [{ "views": [1] }, { "views": [2] }]
      }
    ]
  }
}

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-5000%22%2C%22tracks%22%3A%5B%22gff3tabix_genes%22%5D%7D%2C%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-5000%22%2C%22tracks%22%3A%5B%22volvox_sv_test%22%5D%7D%2C%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgB%3A1-5000%22%2C%22tracks%22%3A%5B%22gff3tabix_genes%22%5D%7D%5D%2C%22layout%22%3A%7B%22direction%22%3A%22horizontal%22%2C%22children%22%3A%5B%7B%22views%22%3A%5B0%5D%7D%2C%7B%22direction%22%3A%22tabs%22%2C%22children%22%3A%5B%7B%22views%22%3A%5B1%5D%7D%2C%7B%22views%22%3A%5B2%5D%7D%5D%7D%5D%7D%7D&sessionName=JBrowse+docs+example

• The first child of a tabs node is the tab shown. Tabs can be renamed by double-clicking and dragged out into a split.
• A tabs node is the one container whose size does not divide space, so a size on its children has no effect, and a container nested inside it has its views gathered into a single tab. The session shows a notification when a spec does either.

Other session formats#

Besides spec-, &session= takes four formats that contain a session snapshot rather than instructions for building one.

&session=json-#

A plain JSON snapshot, the shape "Export session..." produces, and the Share button's "Plaintext JSON" option: the longest format, and the one to read.

&session=json-{"session":{"id":"xSHu7qGJN","name":"test","sessionPlugins":[{"name":"MsaView","url":"https://unpkg.com/jbrowse-plugin-msaview/dist/jbrowse-plugin-msaview.umd.production.min.js"}]}}

&session=encoded-#

The JSON snapshot as base64 plus gzip is the Share button's "Long URL" option. It works without the session-sharing server, and because it is long the Share button puts it in the fragment.

https://jbrowse.org/code/jb2/latest/#session=encoded-eJyNU2FzmkAQ_SvOfaaNIKDyLbFN0xlrTWRqnU4mc8ACm8BB7k6Ndfj...

&session=local-#

https://host/jbrowse2/?session=local-Fjphq8kjY. A loaded session is stored in sessionStorage and IndexedDB and the URL bar switches to this form. The same tab restores from sessionStorage; a new tab on the same machine restores from IndexedDB.

&session=share-#

https://host/jbrowse2/#session=share-Xb3_kPq9LmZ, from the Share button.

• The client mints a random key, encrypts the session and uploads the blob without the key to a DynamoDB store, under a hash of the key. The link carries only the key, and the recipient's browser sends the store only the hash and decrypts the session itself, so the store's contents cannot be read even by JBrowse administrators.
• A share service that names its own ids puts the id in the link before the key.
• A link from before JBrowse 5 carries its key as &password=, and still opens.
• Behind a firewall that cannot reach the shortener, the Share dialog's gear icon switches to "Long URL". shareURL in the config points at a shortener of your own.

Are share links reproducible#

• The short link is not reproducible: each click mints a new key and uploads a new blob, so the same view gives a new key every time.
• "Long URL" is reproducible: it contains the whole session in the link, so the same view and config produce the same link, and it survives moving the instance.
• The config can still break either link: a restored session names tracks by trackId, so a redeploy that regenerates config.json with different ids leaves the link unable to find them (keeping trackIds stable).

Loading a plugin from a URL#

A snapshot's sessionPlugins array is the only way to name a plugin in the URL itself. The array takes the same definitions as a config's plugins array and works in all four snapshot formats. The plugin belongs to that session and is not installed for the user.

• name is required for a UMD bundle, the .umd.production.min.js builds the plugin store publishes. The loader resolves the bundle as the global JBrowsePlugin<Name>, so a definition with only a url loads the script but does not find the global.
• An unrecognized plugin prompts the visitor. Anything not served from https://jbrowse.org/plugins/ and not in the plugin store opens an "unknown plugins" dialog before the session loads, since a plugin is arbitrary JavaScript running with the page's privileges. A config's plugins are gated the same way, but only when the config is cross-origin.
• A JSON session bypasses the launcher. A plugin's view type opened this way is instantiated straight from the snapshot, so anything its launcher would have resolved has to be written out. Build the session in the app and copy it out of Share, gear, "Plaintext JSON".
• These URLs get long. Put the session in the fragment, and config= with it, since a fragment containing = makes JBrowse ignore the query string.

For everyone opening a config to have the plugin, put it in that config's plugins array.

See also#

• Tutorial: Embedding JBrowse
• Config guide: Default session
• Developer guide: Extension points
• Docs: Config and session JSON