Track Database Definition

Hub Track Database Definition (v2)

How to declare Dataset Display Settings in Genome Browser Hubs

This document describes how to set dataset display characteristics using "track database" or "trackDb" settings through key-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 following "ra" rules to establish a "record" of related settings. The first line establishes the track "key", with additional lines containing further "setting" keys, and one or more words or numbers that follow, which are the "values" for each setting. All trackDb stanzas are keyed by track and delimited by blank lines. 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".    

A basic track stanza should have these five above 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.

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:

requiredrequired settings
basecommon settings supported at other sites
deprecatedsettings that are being retired (replacement is listed in details section)
newnew settings not yet assigned a level (may be replaced)
fullother settings

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 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.

The remainder of this document is divided into the following sections and should be used as a ready reference.

 Expand/close descriptions of settings in the sections below.
  1. Common trackDb settings
  2. Settings by track type – with examples
  3. Grouping tracks into sets and hierarchies – with examples
  4. Table of Contents
  Common trackDb settings
 Common Settings
track
type
shortLabel
longLabel
bigDataUrl <url/relativePath>
html
visibility

 Common Optional Settings
color <red,green,blue>
priority <float>
altColor <red,green,blue>
boxedCfg <on/off>
chromosomes <chr1,chr2,...>
darkerLabels on
dataVersion <str>
directUrl <url>
iframeUrl <url>
iframeOptions <string>
mouseOverField <fieldName>
otherDb <otherDb>
pennantIcon <icon> [html [tip]]
url <url>
urlLabel <label>
urls <fieldName1>="<url1>" <fieldName2>="<url2>" ...
skipEmptyFields on
skipFields fieldName1,fieldName2 ...
sepFields fieldName1,fieldName2 ...
  Settings by track type

Many settings are valid only for certain types of tracks. Many of these tracks are described below along with settings specific to their types.

 bam/cram - Compressed Sequence Alignment track settings
type bam
bigDataUrl <url/relativePath>
refUrl <url>
bigDataIndex <url/relativePath>
Related settings:
bamColorMode <strand/gray/tag/off>
bamSkipPrintQualScore .
indelDoubleInsert <off/on>
indelQueryInsert <off/on>
indelPolyA <off/on>
minAliQual <#>
Related settings:
pairEndsByName .
showNames <on/off>

Additional settings found in the "Item or region tracks" section are also available for displaying bam tags.

maxWindowToDraw,
Example of a bam track


 bigBed - Item or region track settings
type bigBed <3-12> [+/.]
bigDataUrl <url/relativePath>
itemRgb on
colorByStrand <red,green,blue> <red,green,blue>
denseCoverage <maxVal>
labelOnFeature <on/off>
exonArrows <on/off>
exonNumbers <on/off>
scoreFilter <low>[:<high>]
scoreFilterLimits <low>[:<high>]
maxItems <integer>
maxWindowToDraw <integer>
minGrayLevel <1-9>
noScoreFilter on
spectrum on
scoreMax <integer>
scoreMin <integer>
thickDrawItem <off/on>
searchIndex <str>
searchTrix <url/relativePath>
labelFields <fieldName[,fieldName]>
defaultLabelFields <fieldName[,fieldName]>
labelSeparator <text>
 Less frequently used item track settings
bedNameLabel <label>
exonArrowsDense <off/on>
itemImagePath <path> <suffix>
itemBigImagePath <path> <suffix>
linkIdInName on
nextExonText <str>
prevExonText <str>
scoreLabel <label>
showTopScorers #
Examples of item base types


 bigChain - Genome-wide Pairwise Alignments
type bigChain
bigDataUrl <url/relativePath>
linkDataUrl <url/relativePath>


 bigGenePred - Gene Annotations
type bigGenePred
bigDataUrl <url/relativePath>
labelFields <fieldName[,fieldName]>
defaultLabelFields <fieldName[,fieldName]>
labelSeparator <text>


 bigMaf - Multiple alignments
type bigMaf
bigDataUrl <url/relativePath>
speciesOrder <species1> [species2 …]
frames <url/relativePath>
summary <tableName/url>


 bigPsl - Pairwise Alignments
type bigPsl
bigDataUrl <url/relativePath>
baseColorUseCds <given/table <table>>
baseColorUseSequence < <extFile {seqTable} <extFile> / hgPcrResult / lfExtra / nameIsSequence / seq1Seq2 / ss >
baseColorDefault <diffBases/diffCodons/itemBases/itemCodons/genomicCodons>
showDiffBasesAllScales on
labelFields <fieldName[,fieldName]>
defaultLabelFields <fieldName[,fieldName]>
labelSeparator <text>


 bigWig - Signal graphing track settings
type bigWig <#> <#>
autoScale <off/on>
maxHeightPixels <max:default:min>
viewLimits <lower:upper>
viewLimitsMax <lower:upper>
alwaysZero <off/on>
bigDataUrl <url/relativePath>
graphTypeDefault points
maxWindowToQuery <integer>
negateValues <on>
smoothingWindow <off/1-16>
transformFunc <NONE/LOG>
windowingFunction <mean/mean+whiskers/maximum/minimum>
yLineMark <#>
yLineOnOff <off/on>
gridDefault on
Examples of signal graphing tracks


 halSnake - Genome-wide Multiple Alignments
type halSnake
bigDataUrl <url/relativePath>
showSnpWidth <integer>
otherSpecies <otherSpecies>


 vcfTabix - Variant Call Format (indexed by tabix) track settings
type vcfTabix
bigDataUrl <url/relativePath>
bigDataIndex <url/relativePath>
Related settings:
hapClusterEnabled <true|false>
Related settings:
applyMinQual <true|false>
minFreq <F>

Additional settings found in the "Item or region tracks" section are also available for displaying Variant Call Format tracks.

maxWindowToDraw
Example of a VCF track


  Grouping tracks into sets and hierarchies
Depending on how closely related they are, tracks can be organized into one of three hierarchical containers:
  • "multiWig" container: when the tracks are all in signal (wiggle or bigWig) format and it makes sense to overlay them.
    Example: a set of bigWig tracks with H3K27ac signal, all on the same scale
  • "composite" container: when the tracks are expected to be configured together or have an internal subgrouping, like cell type or cell treatment.
    Example: a set of ChIP-bigBeds in three different cell types
  • "superTrack" container: when the tracks share no specific configuration and you mostly want to show them together.
    Example: a set of composite tracks or a mix of bigBed, bigWig and bam
 Supertrack (Folders) settings
superTrack on
parent <superTrack>
Example of a Supertrack


 Composite track settings
parent <composite> [off/on]
compositeTrack on
allButtonPair on
centerLabelsDense <off/on>
dragAndDrop subTracks
Example of a Composite track


 Composite track subgroup settings
subGroup1 <gTag1> <gTitle1> <mTag1a=mTitle1a> [mTag1b=mTitle1b…]
subGroup2 <gTag2> <gTitle2> <mTag2a=mTitle2a> [mTag2b=mTitle2b…]
subGroup3 subGroup4 subGroup5 subGroup6 subGroup7 subGroup8 subGroup9
subGroups <gTag1=mTag1?> [gTag2= mTag2?]
dimensions <dimX=gTag#> [dimY=gTag#] [dimA=gTag# ...]
filterComposite <dim[A/B/C][=one]> [dimB dimC ...]
dimensionAchecked <mTag1a> [mTag1b …]
dimensionBchecked dimensionCchecked
sortOrder <gTag#=+/-> [gTag#=- …]
Examples of Composite tracks with Subgroups


 Composite track View settings
subGroup1 view <Views> <vTag1a=vTitle1a> [vTag1b=vTitle1b…]
track <viewName>
view <viewTag>
subGroups view=<vTag1>…
parent <viewName> [off/on]
viewUi on
configurable <off/on>
Example of a Composite track with Views


 Aggregate or Overlay track settings
container multiWig
parent <containerTrack>
aggregate <transparentOverlay/stacked/solidOverlay/none>
showSubtrackColorOnUi on
Example of an Aggregate track

Miscellaneous Deprecated Settings

SettingFor TypesNotes
all
noInheritall
useScore bed, factorSource, bed5FloatScore, broadPeak Replaced with spectrum.