Controlling JBrowse with the URL Query String

Overview of URL Query String params

List of default available JBrowse URL params, more details below

Option	Value
data	Set the data directory being used. If you have multiple data directories, then you can select the active one using http://mysite/jbrowse/?data=rice or http://mysite/jbrowse/?loc=soybean (also see Configuration_loading_details and Multiple_genomes)
loc	A location, specified as "chr:start..end" or gene identifier (which is searched from a name store generated by generate-names.pl) e.g. http://mysite/jbrowse/?loc=chr1:0..1000
highres	A configuration for highResolutionMode. Available since JBrowse 1.12.3. Can be auto,disabled, or a specific scaling ratio such as 2,3
fullviewlink,menu,nav,overview,tracklist	Boolean to add or remove different components of the UI. Can be set to false to remove
tracks	Set a list of active tracks, comma separated list of track labels e.g. http://mysite/jbrowse/?tracks=DNA,GeneTrack
highlight	Set a highlighted genomic region, specified as "chr:start..end"
addFeatures,addStores,addTracks,addBookmarks	A JSON configuration for extra track info. See below for detailed descriptions

JBrowse's default index.html file provides a number of options for changing the current view in the browser by adding query parameters to the URL. Developers' note: these URL parameters are handled only in the default index.html that ships with JBrowse; the JBrowse code itself does not pay attention to URL parameters.

Basic syntax:

http://<server>/<path to jbrowse>?loc=<location string>&tracks=<tracks to show>

data

Optional relative (or absolute) URL of the base directory from which JBrowse will load data. Defaults to 'data'.

loc

The initial genomic position which will be visible in the viewing field. Possible input strings are:

"Chromosome"+":"+ start point + ".." + end point

A chromosome name/ID followed by “:”, starting position, “..” and end position of the genome to be viewed in the browser is used as an input. Chromosome ID can be either a string or a mix of string and numbers. “CHR” to indicate chromosome may or may not be used. Strings are not case-sensitive. If the chromosome ID is found in the database reference sequence (RefSeq), the chromosome will be shown from the starting position to the end position given in URL.

example) ctgA:100..200 Chromosome ctgA will be displayed from position 100 to 200.

OR start point + ".." + end point

A string of numerical value, “..” and another numerical value is given with the loc option. JBrowse navigates through the currently selected chromosome from the first numerical value, start point, to the second numerical value, end point.

example) 200..600

OR center base

If only one numerical value is given as an input, JBrowse treats the input as the center position. Then an arbitrary region of the currently selected gene is displayed in the viewing field with the given input position as basepair position on which to center the view.

OR feature name/ID

If a string or a mix of string and numbers are entered as an input, JBrowser treats the input as a feature name/ID of a gene. If the ID exists in the database RefSeq, JBrowser displays an arbitrary region of the feature from the the position 0, starting position of the gene, to a certain end point.

example) ctgA

tracks

parameters are comma-delimited strings containing track names, each of which should correspond to the "label" element of the track information dictionaries that are currently viewed in the viewing field. Names for the tracks can be found in data/trackInfo.js in jbrowse-1.2.1 folder.

Example:

tracks=DNA,knownGene,ccdsGene,snp131,pgWatson,simpleRepeat

highlight

Location string that specifies the genomic position to highlight. The location string must follow the format of chromosome name/ID followed by “:”, starting position, “..” and end position.

[chromosome]:[start]..[end]

Example:

highlight=ctgA:100..200

This is the only format that is currently supported.

addFeatures

Available in JBrowse 1.10.0 and above. This variable accepts feature data in JSON format in the form:

[{ "seq_id":"ctgA", "start": 123, "end": 456, "name": "MyBLASTHit"},...}]

which, when URI-escaped and put in the query string, looks like:

addFeatures=%5B%7B%20%22seq_id%22%3A%22ctgA%22%2C%20%22start%22%3A%20123%2C%20%22end%22%3A%20456%2C%20%22name%22%3A%20%22MyBLASTHit%22%7D%5D

in dot-notation, the second number is the order of the feature object in the JSONArray:

addFeatures.<featurenumber>.<values>

e.g.

addFeatures.1.seq_id=ctgA&addFeatures.1.start=123&addFeatures.1.start=456&addFeatures.1.name=MyBLASTHit&addFeatures.2.seq_id=...

Developers integrating JBrowse into larger project may find this feature useful for displaying results from other non-JavaScript-based applications (such as web BLAST tools) in JBrowse.

Features added to JBrowse in this way are available in a special data store named url, which can be specified in a track configuration by adding "store":"url".

addTracks

This variable accepts track configurations in JSON format to be added to the tracks already in the JBrowse configuration, in the form:

[{"label":"mytrack","type":"JBrowse/View/Track/HTMLFeatures","store":"myUniqueStore"}]

which, when URI-escaped and put in the query string, looks like:

addTracks=%5B%7B%22label%22%3A%22mytrack%22%2C%22type%22%3A%22JBrowse%2FView%2FTrack%2FHTMLFeatures%22%2C%22store%22%3A%22myUniqueStore%22%7D%5D

using dot notation. See release-notes.txt for more details:

addTracks.myUniqueStore.label=mytrack&addTracks.myUniqueStore.myUniqueStore.type=JBrowse/View/Track/HTMLFeatures

If you are not adding a store, make the store name 'none' (addTracks.none.label).

addStores

This variable accepts store configurations in JSON format to be added to the stores already in the JBrowse configuration, in the form:

   { "uniqueStoreName": {
         "type":"JBrowse/Store/SeqFeature/GFF3",
         "urlTemplate": "url/of/my/file.gff3"
     }
   }

which, when URI-escaped and put in the query string, looks like:

addStores=%7B%22uniqueStoreName%22%3A%7B%22type%22%3A%22JBrowse%2FStore%2FSeqFeature%2FGFF3%22%2C%22urlTemplate%22%3A%22url%2Fof%2Fmy%2Ffile.gff3%22%7D%7D

using dot notation. See release-notes.txt for more details:

addStores.uniqueStoreName.type=JBrowse/Store/SeqFeature/GFF3&addStores.uniqueStoreName.urlTemplate=url/of/my/file.gff3

One example is to use addStores combined with addTracks to dynamically load a remote file. Thanks to vkrishna for the example

addStores={"url":{"type":"JBrowse/Store/SeqFeature/GFF3","urlTemplate":"http://host/genes.gff"}}&addTracks=[{"label":"genes","type":"JBrowse/View/Track/CanvasFeatures","store":"url"}]

Another example if you want to not provide the entire URL to the store (e.g. provide a path relative to data directory instead of http://host/genes.gff) is to use a combination of the baseUrl and the {dataRoot} variables. This example adds a VCF track:

addStores={"mystore":{"type":"JBrowse/Store/SeqFeature/VCFTabix","baseUrl":".","urlTemplate":"{dataRoot}/combined.vcf.gz"}}&addTracks=[{"label":"variants","type":"JBrowse/View/Track/CanvasVariants","store":"mystore"}]

In dot-notation:

addStores.mystore.type=JBrowse/Store/SeqFeature/VCFTabix&addStores.mystore.baseUrl=.&addStores.mystore.urlTemplate="{dataRoot}/combined.vcf.gz"&addTracks.mystore.label=variants&addTracks.mystore.type=Browse/View/Track/CanvasVariants

Thanks to biojiangke for inquiring about the above example.

addBookmarks

Bookmarks are available in JBrowse starting in 1.12.2, which allows you to add static coloured overlays to specific regions of the genome.

This variable accepts track bookmarks (similar to highlights) in JSON format to be added to the tracks already in the JBrowse configuration, in the form:

[{"start":5500,"end":6000,"color": "rgba(190,50,50,0.5)","ref": "ctgB"}]

which, when URI-escaped and put in the query string, looks like:

addBookmarks=%5B%7B%22start%22%3A5500%2C%22end%22%3A6000%2C%22color%22%3A%20%22rgba(190%2C50%2C50%2C0.5)%22%2C%22ref%22%3A%20%22ctgB%22%7D%5D

using dot notation. See release-notes.txt for more details:

addBookmarks.start=5500&addBookmarks.end=6000&addBookmarks.color="rgba(190,50,50,0.5)"&addBookmarks.ref=ctgB

Bookmarks can also be manually added to the configuration, e.g. tracks.conf:

   [ bookmarks ]
   features+= json:{"start":5000,"end":5750,"color": "rgba(190,50,50,0.5)","ref": "ctgB"}
   features+= json:{"start":5500,"end":6000,"color": "rgba(190,50,50,0.5)","ref": "ctgB"}

They can also be retrieved from a remote "bookmark API", which receives a query parameter "sequence" for the current refseq and returns data in the JSON format similar to above

bookmarkService=http://yourbookmarkservice.com/jbrowseBookmark

An example appears in the Volvox example, on ctgB.

JBrowse_bookmarks_example_a.png>

Embedded mode

JBrowse's included index.html file supports three URL query arguments that can turn off the JBrowse track list, navigation bar, and overview bar, respectively. When all three of these are turned off, the only thing visible are the displayed tracks themselves, and JBrowse could be said to be running in a kind of "embedded mode".

The three parameters used for this are nav, tracklist, menu and overview. If any of these are set to 0, that part of the JBrowse interface is hidden.

For example, you could put the embedded-mode JBrowse in an iframe, like this:

<html>
<head>
<title>
JBrowse Embedded

</title>
</head>
<body>
<h1>
Embedded Volvox JBrowse

</h1>
<div style="width: 400px; margin: 0 auto;">
       <iframe style="border: 1px solid black" src="../../index.html?data=sample_data/json/volvox&tracklist=0&nav=0&overview=0&tracks=DNA%2CExampleFeatures%2CNameTest%2CMotifs%2CAlignments%2CGenes%2CReadingFrame%2CCDS%2CTranscript%2CClones%2CEST" width="300" height="300">
       </iframe>

</div>
</body>
</html>

Note that if you are embedding with an iframe, it can be useful to keep the functionality that jbrowse has to update the URL bar in the parent frame. See this FAQ entry for details http://gmod.org/wiki/JBrowse_FAQ#How_can_I_get_jbrowse_to_update_the_URL_of_a_parent_page_when_jbrowse_is_inside_of_an_iframe