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:
required | required settings |
base | common settings supported at other sites |
deprecated | settings that are being retired (replacement is listed in details section) |
new | new settings not yet assigned a level (may be replaced) |
full | other 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.
track |
type |
shortLabel |
longLabel |
bigDataUrl <url/relativePath> |
html |
visibility |
Many settings are valid only for certain types of tracks. Many of these tracks are described below along with settings specific to their types.
type bam |
bigDataUrl <url/relativePath> |
refUrl <url> |
bigDataIndex <url/relativePath> |
Related settings:
bamColorMode <strand/gray/tag/off> |
bamGrayMode <aliQual/baseQual/unpaired> aliQualRange <min:max> baseQualRange <min:max> < |
bamColorTag <XX> |
noColorTag . |
bamSkipPrintQualScore . |
indelDoubleInsert <off/on> indelQueryInsert <off/on> indelPolyA <off/on> |
minAliQual <#> |
Related settings:
pairEndsByName . |
pairSearchRange <#> |
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
|
type bigBarChart |
barChartBars <label1 label2...> |
bigDataUrl <url/relativePath>
|
barChartColors <color1 color2...>
|
barChartLabel <label>
|
barChartMetric <metric>
|
barChartUnit <unit>
|
barChartMatrixUrl <url/relativePath>
|
barChartSampleUrl <url/relativePath>
|
maxLimit <maximum-bar-value>
|
Additional settings defined in other sections are also available for displaying bigBarChart tracks. labelFields, defaultLabelFields |
Example of a bigBarChart track
|
type bigChain |
bigDataUrl <url/relativePath> |
linkDataUrl <url/relativePath> |
type bigGenePred |
bigDataUrl <url/relativePath> |
labelFields <fieldName[,fieldName]> |
defaultLabelFields <fieldName[,fieldName]> |
labelSeparator <text> |
type bigMaf |
bigDataUrl <url/relativePath> |
speciesOrder <species1> [species2 …] |
frames <url/relativePath> |
summary <tableName/url> |
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> |
type halSnake |
bigDataUrl <url/relativePath> |
showSnpWidth <integer> |
otherSpecies <otherSpecies> |
type vcfTabix |
bigDataUrl <url/relativePath> |
bigDataIndex <url/relativePath> |
Related settings:
hapClusterEnabled <true|false> |
hapClusterColorBy <altOnly|refAlt|base> |
hapClusterTreeAngle <triangle|rectangle> |
hapClusterHeight <N> |
Related settings:
applyMinQual <true|false> |
minQual <Q> |
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
|
superTrack on |
parent <superTrack> |
Example of a Supertrack
|
parent <composite> [off/on] |
compositeTrack on |
allButtonPair on |
centerLabelsDense <off/on> |
dragAndDrop subTracks |
Example of a Composite track
|
container multiWig |
parent <containerTrack> |
aggregate <transparentOverlay/stacked/solidOverlay/none> |
showSubtrackColorOnUi on |
Example of an Aggregate track
|
Setting | For Types | Notes |
---|---|---|
metadata
|
all | |
noInherit | all | |
useScore |
bed, factorSource, bed5FloatScore, broadPeak | Replaced with spectrum. |