Hub Track Database Definition (v3)

How to declare Dataset Display Settings in Genome Browser Hubs

For returning readers: We keep a list of changes to the trackDb specification below.

This document describes how to set dataset display characteristics using "track database" or "trackDb" settings through name-value pair associations used in a Track Hub's trackDb.txt file.

The text file format for trackDb settings starts by creating a text block, or "stanza", for each track dataset. These stanzas should be structured according to the following format specification:

• Lines consist of name-value pairs. The first line of the stanza establishes the the track name. Additional lines will contain further "setting" names followed by "values" of one or more words of numbers.
• All trackDb stanzas must begin with a track line and a stanza ends with a blank line.
• Periods should be avoided in track names, although there are some settings that include periods in the name, e.g. filter.fieldName.
• The format supports '\' continuation characters. If the setting is long or complex, break it into several lines using terminating '\' characters to make it more readable.
• Text should be ASCII characters, but a limited set of Unicode characters are supported for longLabel and shortLabel settings.

Here is an example:

        track myFirstTrack
        type bigBed 3
        bigDataUrl myFirstTrack.bb
        shortLabel Example Data
        longLabel The data in this track is format "bigBed 3".    

Every track stanza should have these five settings (track type bigDataUrl shortLabel longLabel). The first line's track key value (myFirstTrack) is the identifier for the dataset given to the Browser and it must be unique for each track within your data hub. After the track key, the most important setting is the type key. This value (bigBed 3) tells the Browser the type of format the data is in, defines how to display it, and determines which options are available for fine control of that display. For some configurable features, like filters, an additional period or plus may be needed (bigBed 5 .) or (bigBed 9 +).

While there are over 100 settings (providing a high level of flexibility for track display) defined in this document and supported at UCSC, only the above five are required to define a track and other sites that display hubs have more limited settings support. To ease the task of hub developers and sites that display hubs, each setting has been assigned a support level. The most commonly used and broadly supported settings have been designated as base settings, to foster hub portability. The level for each setting is indicated in this document by color, shown below and in each description section as well as in the Table of Contents. The support levels are:

This documentation page has also been assigned a version number so that when new settings are added, or older settings are deprecated other browser sites and track hub builders can verify the hub to the relevant version. To learn about new settings you can view our software release log or view news at a collaborative track hub mailing list. You can also see the commit history of recent changes to the document library.

You can use the hubCheck utility to check the compatibility of your hub and its trackDb settings with the UCSC Genome Browser or other genome browsers, such as Ensembl. Our track hub help page provides some examples of how you might use hubCheck to do this and you can read more in this related blog post.