Skip to content

Commit

Permalink
Breakup config guide more
Browse files Browse the repository at this point in the history
  • Loading branch information
@cmdcolin
cmdcolin committed Aug 13, 2018
1 parent d7b9f8b commit 1d86463
Show file tree
Hide file tree
Showing 6 changed files with 291 additions and 305 deletions.
9 changes: 5 additions & 4 deletions docs/site/name_indexing.md → docs/site/command_line.md
View file
@@ -1,7 +1,8 @@
---
id: name_indexing
title: Name Searching and Autocompletion
---
# Removing Tracks

JBrowse has a script to remove individual tracks: `remove-track.pl`. Run it with the `--help` option to see a comprehensive usage message:

`  bin/remove-track.pl --help`


# Name Searching and Autocompletion
Expand Down
303 changes: 2 additions & 301 deletions docs/site/configuration_guide.md
View file
@@ -1,25 +1,8 @@
---
id: configuration_guide
title: JBrowse Configuration Guide
id: url_strings
title: JBrowse URL parameters
---

# Introduction

This page provides a comprehensive reference guide for configuring JBrowse. If you find something that is missing or inaccurate, please feel very free to edit it!

Note: this is a **reference guide**. It is not meant to be read from beginning to end. If this is your first time setting up JBrowse, you probably want to read the [Quick-start tutorial](http://jbrowse.org/code/latest-release/docs/tutorial/index.html) first, and then consult this guide when you need information on specific things you want to do with your JBrowse.

Check out the new [JBrowse FAQ](faq.html) page for more tips on setup and configuration.

Also see the [JBrowse Desktop](jbrowse_desktop.html) guide here.

# Removing Tracks

JBrowse has a script to remove individual tracks: `remove-track.pl`. Run it with the `--help` option to see a comprehensive usage message:

`  bin/remove-track.pl --help`


# Controlling JBrowse with the URL Query String

## Overview of URL Query String params
Expand Down Expand Up @@ -218,288 +201,6 @@ Embedded Volvox JBrowse
</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>

# Data Export

Starting with version 1.7.0, JBrowse users can export track data in a variety of formats for either specific regions, or for entire reference sequences. Export functionality can also be limited and disabled on a per-track basis using the configuration variables listed below.

## Data Formats

Current supported export data formats are:

- FASTA (sequence tracks)
- GFF3 (all tracks)
- bed (feature and alignment tracks)
- bedGraph (wiggle tracks)
- Wiggle (wiggle tracks)

## Export Configuration

Each track in JBrowse that can export data supports the following configuration variables.

|Option|Value|
|------|-----|
|`noExport`|If true, disable all data export functionality for this track. Default false.|
|`maxExportSpan`|Maximum size of the a region, in bp, that can be exported from this track. Default 500 Kb.|
|`maxExportFeatures`|Maximum number of features that can be exported from this track. If "Save track" is unexpectedly greyed out, inspect this setting. Default: 50000|
|`maxFeatureSizeForUnderlyingRefSeq`|Maximum length of sequence to be displayed in the popup boxes. Default: 250kb|

# Data from a SPARQL Endpoint

Starting with version 1.10.0, JBrowse can display feature or quantitative data directly from a SPARQL endpoint. The SPARQL data adaptor can be used with any of the JBrowse track types.

To display annotations from a SPARQL endpoint, first write a SPARQL query that fetches features for a given reference sequence region, given the reference sequence name and the start and end coordinates of the region of interest, with one feature returned per output row. JBrowse will run this query every time it fetches features for a certain region. The reference sequence name, start, and end, are interpolated into the query at every occurrance of "{ref}", "{start}", or "{end}", respectively. This is the same variable interpolation syntax used in other parts of the JBrowse configuration.

Queries used with JBrowse can have any number of output columns, but are required to have at least 4: ?start, ?end, ?strand, and ?uniqueID (usually just the URI of the feature). If the data includes subfeatures, a ?parentUniqueID column can be added to the SPARQL query, and features will be attached as subfeatures to any feature in the query with that ?uniqueID. Any number of additional columns can be added, as well. Their contents will just be attached to each feature as attributes, which will be visible in the default feature detail dialog. If available, it's a good idea to add a ?name column, which would be the feature's displayed name, and maybe a ?description column, which can be a longer text description of the feature.

## Example SPARQL Configuration

The example configuration below displays complete gene models (with locations represented using [FALDO](https://github.com/JervenBolleman/FALDO)) contained in a SPARQL endpoint located at `/sparql` on the same server as JBrowse.

[tracks.genes]
label = genes
key = SPARQL Genes
storeClass = JBrowse/Store/SeqFeature/SPARQL
type = JBrowse/View/Track/CanvasFeatures
urlTemplate = /sparql
queryTemplate =
DEFINE sql:select-option "order"
prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
prefix xsd: <http://www.w3.org/2001/XMLSchema#>
prefix obo: <http://purl.obolibrary.org/obo/>
prefix faldo: <http://biohackathon.org/resource/faldo#>
prefix idorg: <http://rdf.identifiers.org/database/>
prefix insdc: <http://insdc.org/owl/>
select ?start,
?end,
IF( ?faldo_type = faldo:ForwardStrandPosition,
1,
IF( ?faldo_type = faldo:ReverseStrandPosition,
-1,
0
)
) as ?strand,
str(?obj_type_name) as ?type,
str(?label) as ?name,
str(?obj_name) as ?description,
?obj as ?uniqueID,
?parent as ?parentUniqueID
from <http://togogenome.org/refseq/>
from <http://togogenome.org/so/>
from <http://togogenome.org/faldo/>
where {
values ?faldo_type { faldo:ForwardStrandPosition faldo:ReverseStrandPosition faldo:BothStrandsPosition }
values ?refseq_label { "{ref}" }
#values ?obj_type { obo:SO_0000704 }
?obj obo:so_part_of ?parent . filter( ?obj_type = obo:SO_0000704 || ?parent != ?seq )
# on reference sequence
?obj obo:so_part_of+ ?seq .
?seq a ?seq_type.
?seq_type rdfs:label ?seq_type_label.
?seq rdfs:seeAlso ?refseq .
?refseq a idorg:RefSeq .
?refseq rdfs:label ?refseq_label .
# get faldo begin and end
?obj faldo:location ?faldo .
?faldo faldo:begin/rdf:type ?faldo_type .
?faldo faldo:begin/faldo:position ?start .
?faldo faldo:end/faldo:position ?end .
filter ( !(?start > {end} || ?end < {start}) )
# feature type
?obj rdf:type ?obj_type .
?obj_type rdfs:label ?obj_type_name .
optional {
?obj insdc:feature_locus_tag ?label .
}
# feature name is the feature product
optional {
?obj insdc:feature_product ?obj_name .
}
#optional {
# ?obj rdfs:seeAlso ?obj_seealso .
#}
}

## Variable Interpolation

By default, only "{ref}", "{start}", and "{end}" are available for interpolating into your query. However, starting with JBrowse 1.10.3, you can add additional variables in the configuration by including a `variables` key containing additional values. For example, you could add an "{organism_uri}" in your queryTemplate that was set from the `variables` stanza, which would look like:

~~~~ {.javascript}
{
"label": 'genes',
"key": "SPARQL Genes",
"storeClass": "JBrowse/Store/SeqFeature/SPARQL",
"type": 'JBrowse/View/Track/HTMLFeatures',
"urlTemplate": "/sparql",
"style": { "className": "transcript" },
"queryTemplate": "... {organism_uri} ...",
"variables": {
"organism_uri": "<http://my.organism.authority/tyrannosaurus_rex>"
}
}
~~~~

The variable interpolation can also be used to refer to functions that are defined in external files (see [Including external files and functions](#including-external-files-and-functions-in-tracklistjson "wikilink")).

# Track Metadata

JBrowse supports two ways to add data that describes tracks (track metadata): it can either be embedded directly in the track's configuration stanza, or it can come from a separate file that JBrowse loads. Track metadata is shown both when a user clicks "About this track" from a track's menu, and in the faceted track selector if it is in use.

## Embedding Track Metadata in JBrowse Configuration

Each track configuration stanza can include a `metadata` item that contains items of data that describe the track. For example, to describe a BAM track containing alignments of RNA-seq reads from Volvox carteri under conditions of caffeine starvation, a track configuration might contain:

~~~~ {.javascript}
{
"storeClass" : "JBrowse/Store/SeqFeature/BAM",
"urlTemplate" : "../../raw/volvox/volvox-sorted.bam",
"style" : {
"className" : "alignment",
"arrowheadClass" : "arrowhead",
"labelScale" : 100
},
"label" : "volvox-sorted.bam",
"type" : "JBrowse/View/Track/Alignments",
"key" : "volvox-sorted.bam",
"metadata": {
"Description": "RNA-seq",
"Conditions": "caffeine starvation",
"Species": "Volvox carteri",
"Data Provider": "Robert Buels Institute for Example Data"
}
}
~~~~

### Loading Track Metadata from Files

To add track metadata from an external file to JBrowse, add a `trackMetadata` section to the JBrowse configuration.

JBrowse currently supports track metadata that in Excel-compatible comma-separated-value (CSV) format, but additional track metadata backends are relatively easy to add. Write the JBrowse mailing list if you have a strong need to use another format.

|Option|Value|
|------|-----|
|`trackMetadata.sources`|Array of source definitions, each of which takes the form `{ type: 'csv', url: '/path/to/file' }`. The url is interpreted as relative to the url of the page containing JBrowse (index.html in default installations). Source definitions can also contain a `class` to explicitly specify the JavaScript backend used to handle this source.|
|`trackMetadata.indexFacets`|Optional array of facet names that should be the only ones made searchable. This can be used improve the speed and memory footprint of JBrowse on the client by not indexing unused metadata facets.|

Hint: to convert JBrowse JSON files to a csv, try using jq <https://stedolan.github.io/jq>

Example:

`cat trackList.json| jq -r '.tracks[] | [.label,.key] | @csv'`

Will produce a CSV with the label and key of each track in your trackList.json

Another for thing you can do with jq is add config variables directly to your trackList, for example

`cat trackList.json| jq -r '.tracks[].maxExportSpan=50000'`

### Example

Configuration:

~~~~ {.javascript}
"trackMetadata": {
"indexFacets": [ "category","organism","target","technique","principal_investigator",
"factor","developmental-stage","strain","cell-line","tissue","compound",
"temperature"
],
"sources": [
{ "type": "csv", "url": "myTrackMetaData.csv" }
]
}
~~~~

Note: use lower case values for the facet names / column names in the CSV. Use renameFacets to give them other names. See \#Faceted_track_selector for details.

Track metadata CSV:

|label|technique|factor|target|principal_investigator|submission|category|type|Developmental-Stage|
|-----|---------|------|------|-----------------------|----------|--------|----|-------------------|
|fly/White_INSULATORS_WIG/BEAF32|ChIP-chip|BEAF-32|Non TF Chromatin binding factor|White, K.|21|Other chromatin binding sites|data set|Embryos 0-12 hr|
|fly/White_INSULATORS_WIG/CP190|ChIP-chip|CP190|Non TF Chromatin binding factor|White, K.|22|Other chromatin binding sites|data set|Embryos 0-12 hr|
|fly/White_INSULATORS_WIG/GAF|ChIP-chip|GAF|Non TF Chromatin binding factor|White, K.|23|Other chromatin binding sites|data set|Embryos 0-12 hr|
|...|...|...|...|...|...|...|...|...|

Note that the **label** for each track metadata row must correspond to the `label` in the track configuration for the track it describes.

Hint to set track key from metadata: if a track has no `key` set in its track configuration, JBrowse will look for a `key` in its track metadata, and use that if it is present.

### Track metadata options

trackMetadata.sources - array of metadata source objects

Each source can have

-url - a URL (relative to JBrowse root directory, or absolute URL)
-type - can be CSV, JSON or something else. inferred from the filename of the URL if none specified
-storeClass - can be any store class, defaults to 'dojox/data/CsvStore' for CSV type and 'dojox/data/JsonRestStore' for JSON type

Example:
```
 "trackMetadata": {
     "sources": [
          { "type": "csv", "url":  "data/myTrackMetaData.csv" }
     ]
 }
```
This would load data/myTrackMetaData.csv, e.g. from your data folder. Note trackMetadata blocks can be specified in the trackList.json or a global config file

# Faceted Track Selector

Starting with version 1.4.0, JBrowse has an optional "faceted" track selector designed for sites with hundreds or even thousands of tracks in a single JBrowse instance. This track selector allows users to interactively search for the tracks they are interested in based on the metadata for each track.

An example of a faceted track selector in action with about 1,800 tracks can be seen [here](http://jbrowse.org/code/JBrowse-1.4.0-full/index.html?data=sample_data/json/modencode). This is an example installation containing a snapshot of modENCODE track metadata. Note that the track data and reference sequences in this example are not real (they are actually all just copies of the same volvox test track), this is just an example of the faceted track selector in action.

The `Faceted` track selector takes all sources of track metadata, aggregates them, and makes the tracks searchable using this metadata. By default, tracks only have a few default metadata facets that come from the track configuration itself. After initially turning on the faceted track selector, most users will want to add their own metadata for the tracks: see [Defining Track Metadata](#defining-track-metadata "wikilink") below. To enable the faceted track selector in the JBrowse configuration, set `trackSelector→type` to `Faceted`.

There are some other configuration variables that can be used to customize the display of the track selector. Most users will want to set both of these variables to customize the columns and facets shown in the track selector.

|Option|Value|
|------|-----|
|`trackSelector→displayColumns`|Array of which facets should be displayed as columns in the track list. Columns are displayed in the order given. If not provided, all facets will be displayed as columns, in lexical order.|
|`trackSelector→renameFacets`|Object containing "display names" for some or all of the facet names. For example, setting this to `{ "developmental-stage": "Dev. Stage" }` would display "Dev. Stage" as the name of the `developmental-stage` facet.|
|`trackSelector→escapeHTMLInData`|Beginning in JBrowse 1.6.5, if this is set to `true` or `1` prevents HTML code that may be present in the track metadata from being rendered. Instead, the HTML code itself will be shown.|
|`trackSelector→selectableFacets`|Optional array of which facets should be displayed as facet selectors. The selectors for these appear in the order in which they are specified here. \*Note: the names of the facets are required to be in all lower case for selectableFacets to work\*|
|`trackSelector→initialSortColumn`|A column specifying how the faceted selector is initially sorted. This parameter should be the name used in the displayColumns array and not the "renamed" facet column name.|

![800px|center|thumb|The JBrowse faceted track selector.](http://gmod.org/mediawiki/images/6/68/JBrowseFacetedBrowsing.png)

## Example Faceted Track Selector Configuration

~~~~ {.javascript}
"trackSelector": {
"type": "Faceted",
"displayColumns": [
"key",
"organism",
"technique",
"target",
"factor",
"developmental-stage",
"principal_investigator",
"submission"
],
"renameFacets": { "developmental-stage": "Conditions", "submission": "Submission ID" },
"selectableFacets": ["organism","technique","developmental-stage","factor"]
}
~~~~

# Hierarchical Track Selector

Starting with version 1.11.0, JBrowse uses a "Hierarchical" track selector by default that is designed to allow grouping of tracks and easy checkbox selection choices. The Hierarchical track selector is like the old Simple track selector (which was the default), except it pays attention to the “category” key in a track’s metadata, and if it is present, it organizes the tracks into nested, collapsible panes based on that. Also, instead of the drag-and-drop paradigm used by the Simple track selector, the Hierarchical track selector turns tracks on and off by just checking and unchecking the box next to each track. For more information, see [1](http://jbrowse.org/jbrowse-1-11-0/)

To assign categories and subcategories to your tracks, set category or metadata.category attributes on each configured tracks in your trackList.json. Starting in JBrowse 1.11.5, the category can also be read from a trackMetadata.csv category columns.

There are some other configuration variables that can be used to customize the display of the Hierarchical track selector.

|Option|Value|
|------|-----|
|`trackSelector→sortHierarchical`|Can be true or false. If true, categories and tracks are sorted in alphabetical order. If false, tracks will be loaded specifically in the order that they are specified in the tracklist configuration files. Default:true. Added in JBrowse 1.11.5|
|`trackSelector→collapsedCategories`|A comma separated list of categories from the trackList that will be collapsed initially. This helps when many tracks are loaded in the trackList but you want to collapse certain categories when the user first loads. If there are subcategories specified using slashes, don't use spaces around the slashes. Default:none. Added in JBrowse 1.11.5|

# General configuration options

JBrowse supports some other configuration variables that customize the overall behavior of the browser. Each of these variables goes in the top level of JSON configuration files (i.e. jbrowse_conf.json), or in a `[general]` section in textual configuration files (i.e. jbrowse.conf), or outside of the "tracks" section in a trackList.json or tracks.conf.
Expand Down

0 comments on commit 1d86463

Please sign in to comment.