Track Database Definition

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

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:

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

Use `useOneFile on` for hubs with only one genome

This page focuses on the settings found in the trackDb.txt file; however, all hubs must include a top-level hub.txt. If your hub is only displaying one genome, there is a way to put the genomes.txt and trackDb.txt all into one file. Read about the special useOneFile on setting to allow all a hub to exist in one file. Load a working example here.

Assembly Hubs

This page focuses on the settings found in the trackDb.txt file used in both Track Hubs and Assembly Hubs; however, this page does not describe the settings unique to Assembly Hubs. Track Hubs can display novel genomes, through a type of hub called an Assembly Hub. The genomes.txt file for an Assembly Hub involves many additional settings not described on this page, such as twoBitPath and defaultPos to identify the location of the sequence for the novel assembly and what default position to display. The genomes.txt file in Assembly Hubs also requires display information such as organism, scientificName, description, and htmlPath to label the novel assembly on the gateway page. A special groups setting in Assembly Hubs points to a separate text document that defines track groups under the main image (such as the first "Mapping and Sequencing" group found on almost all Browsers). Read the "Create the genomes.txt file" section of the Track Hub User Guide for more information, and see examples in the Quick Start Guide to Assembly Hubs .

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.

Common trackDb settings
Settings by track type – with examples
- bam/cram: Compressed Sequence Alignment/Map tracks
- bigBed: Item or region tracks
- bigBarChart: Bar charts of categorical variables displayed over genomic regions
- bigChain: Genome-wide Pairwise Alignments
- bigGenePred: Gene Annotations
- bigInteract: Pairwise interactions
- bigLolly: Lollipops
- bigNarrowPeak: Peaks
- bigMaf: Mulitple Alignments
- bigPsl: Pairwise Alignments
- bigWig: Signal graphing tracks
- hic: Hi-C contact matrices
- halSnake: HAL Snake Format
- vcfTabix: Variant Call Format
- vcfPhasedTrio: Variant Call Format Trios
Grouping tracks into sets and hierarchies – with examples
Table of Contents

Common trackDb settings

Common Settings

`track`
`type`
`shortLabel`
`longLabel`
`bigDataUrl <url/relativePath>`
`html`
`visibility`
`meta`

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>`
`downloadUrl <label> <URL>`
`iframeUrl <url>`
`iframeOptions <string>`
`mouseOver <pattern>`
`mouseOverField <fieldName>`
`multiRegionsBedUrl <url/relativePath>`
`otherDb <otherDb>`
`otherTwoBitUrl <url/relativePath>`
`pennantIcon <iconFile>/<text color> [html [tip]] [; <iconFile>/<text color> [html [tip]]]`
`tableBrowser <off/on/noGenome/tbNoGenome> [table1 ...]`
`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>`
`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>`
`doWiggle on`
Additional settings found in the "Item or region tracks" section are also available for displaying bam tags. maxWindowCoverage, maxWindowToDraw,
Example of a bam track

bigBarChart - Bar chart display of categorical variables over genomic regions

`type bigBarChart`
`barChartBars <label1 label2...>`
`bigDataUrl <url/relativePath>`
`barChartColors <color1 color2...>`
`barChartLabel <label>`
`barChartMaxSize <small/medium/large>`
`barChartSizeWindows <largeMax> <smallMin>`
`barChartStretchToItem on`
`barChartFacets on`
`barChartStatsUrl on`
`barChartMerge on`
`barChartMetric <metric>`
`barChartUnit <unit>`
`barChartCategoryUrl <url/relativePath>`
`barChartSampleUrl <url/relativePath>`
`barChartBarMinPadding <num>`
`barChartBarMinWidth <num>`
`maxLimit <maximum-bar-value>`
Additional settings defined in other sections are also available for displaying bigBarChart tracks. labelFields, defaultLabelFields url urlLabel urls
Example of a bigBarChart 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>`
`extraDetailsTable <url/relativePath>`
`extraTableFields <fieldName1\|table title,fieldName2\|table title,...>`
`detailsStaticTable <url/relativePath>`
`detailsDynamicTable <fieldName1\|table title,fieldName2\|table title,...>`
`exonArrows <on/off>`
`exonNumbers <on/off>`
`scoreFilter <low>[:<high>]` `scoreFilterLimits <low>[:<high>]`
`maxItems <integer>`
`maxWindowCoverage <integer>`
`maxWindowToDraw <integer>`
`minGrayLevel <1-9>`
`noScoreFilter on`
`spectrum on` `scoreMax <integer>` `scoreMin <integer>`
`thickDrawItem <off/on>`
`decorator.*`
`searchIndex <str>`
`searchTrix <url/relativePath>`
`labelFields <fieldName[,fieldName]>`
`defaultLabelFields <fieldName[,fieldName]>`
`labelSeparator <text>`
`filter.<fieldName> <default integer>` `filterByRange.<fieldName> <off/on>` `filterLimits.<fieldName> <low>[:<high>]`
`filterText.<fieldName> <default search string>` `filterType.<fieldName> <wildcard/regexp>`
`filterValues.<fieldName> <value1,value2,value3...>` `filterValuesDefault.<fieldName> <value1,value2,value3...>` `filterType.<fieldName> <single/singleList/multiple/multipleListOr/multipleListAnd/multipleListOnlyOr/multipleListOnlyAnd>`
`filterLabel.<fieldName> <label>`
`highlight.<fieldName> <default integer>` `highlightByRange.<fieldName> <off/on>` `highlightLimits.<fieldName> <low>[:<high>]`
`highlightText.<fieldName> <default search string>` `highlightType.<fieldName> <wildcard/regexp>`
`highlightValues.<fieldName> <value1,value2,value3...>` `highlightValuesDefault.<fieldName> <value1,value2,value3...>` `highlightType.<fieldName> <single/singleList/multiple/multipleListOr/multipleListAnd/multipleListOnlyOr/multipleListOnlyAnd>`
`highlightColor <#hexcolor>`

Less frequently used item track settings
`bedNameLabel <label>`
`exonArrowsDense <off/on>`
`itemImagePath <path> <suffix>` `itemBigImagePath <path> <suffix>`
`mergeSpannedItems <on/off>`
`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>`
`otherTwoBitUrl <url/relativePath>`
`baseColorUseSequence < <extFile {seqTable} <extFile> / hgPcrResult / lfExtra / nameIsSequence / seq1Seq2 / ss / 2bit >`
`baseColorDefault <diffBases/diffCodons/itemBases/itemCodons/genomicCodons>`
`indelDoubleInsert <off/on>` `indelQueryInsert <off/on>` `indelPolyA <off/on>`

bigGenePred - Gene Annotations

`type bigGenePred`
`bigDataUrl <url/relativePath>`
`baseColorDefault <diffBases/diffCodons/itemBases/itemCodons/genomicCodons>`
`labelFields <fieldName[,fieldName]>`
`defaultLabelFields <fieldName[,fieldName]>`
`labelSeparator <text>`
Additional settings defined in other sections are also available for displaying bigGenePred tracks. decorator

bigInteract - Pairwise interaction display

`type bigInteract`
`bigDataUrl <url/relativePath>`
`interactDirectional <true/offsetSource/offsetTarget/clusterSource/clusterTarget>`
`interactUp <true/false>`
`detailsBoxesEnabled <true/false>`
`interactMultiRegion <true/padding>`
`endsVisible two`
Additional settings defined in other sections are also available for displaying bigInteract tracks. maxHeightPixels scoreMin spectrum,
Example of a bigInteract track

bigMaf - Multiple alignments

`type bigMaf`
`bigDataUrl <url/relativePath>`
`speciesOrder <species1> [species2 …]`
`speciesLabels <species1=newLabel1> [species2=newLabel2 …]`
`frames <url/relativePath>`
`summary <tableName/url>`

bigNarrowPeak - Peaks

`type bigNarrowPeak`
`bigDataUrl <url/relativePath>`
`pValueFilter` `qValueFilter` `signalFilter`

bigPsl - Pairwise Alignments

`type bigPsl`
`bigDataUrl <url/relativePath>`
`baseColorUseCds <given>`
`baseColorUseSequence < <extFile {seqTable} <extFile> / hgPcrResult / lfExtra / nameIsSequence / seq1Seq2 / ss >`
`baseColorDefault <diffBases/diffCodons/itemBases/itemCodons/genomicCodons>`
`showDiffBasesAllScales on`
`indelDoubleInsert <off/on>` `indelQueryInsert <off/on>` `indelPolyA <off/on>`
`pslSequence <no/all/different>`
`showCdsAllScales on`
`showCdsMaxZoom <basesPerPixel>`
`showDiffBasesMaxZoom <basesPerPixel>`
`labelFields <fieldName[,fieldName]>`
`defaultLabelFields <fieldName[,fieldName]>`
`labelSeparator <text>`
`otherTwoBitUrl <url/relativePath>`
Additional settings defined in other sections are also available for displaying bigPsl tracks. decorator

bigWig - Signal graphing track settings

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

bigLolly - lollipop graphs

`type bigLolly`
`bigDataUrl <url/relativePath>`
`noStems <on/off>`
`lollySizeField <integer>`
`lollyMaxSize <integer>`
`lollyField <integer>`
`yAxisLabel.<integer> <integer> <on/off> <R,G,B> <string>`
`yAxisNumLabels <on/off>`

hic - Hi-C contact matrices

`type hic`
`bigDataUrl <url/relativePath>`
`color <red,green,blue>`
`drawMode <triangle\|square\|arc>`
`normalization <NONE\|VC\|VC_SQRT\|KR>`
`resolution <Auto\|integer>`
`saturationScore <float>`
`autoScale <off/on/group>`
`hicDistanceMin <integer>`
`hicDistanceMax <integer>`
Example of a hic track

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>`
`hapClusterMethod <centerWeighted\|fileOrder\|treeFile url>`
`hapClusterColorBy <altOnly\|function\|refAlt\|base>`
`geneTrack <track>`
`hapClusterTreeAngle <triangle\|rectangle>`
`hapClusterHeight <N>`
Related settings: `applyMinQual <true\|false>`
`minQual <Q>`
`minFreq <F>`
`vcfDoFilter <on/off>`
`vcfDoQual <on/off>`
`vcfDoMaf <on/off>`
Additional settings found in the "Item or region tracks" section are also available for displaying Variant Call Format tracks. maxWindowCoverage maxWindowToDraw
Example of a VCF track

vcfPhasedTrio - Variant Call Format Trio track settings

`type vcfPhasedTrio`
`bigDataUrl <url/relativePath>`
`vcfChildSample <sampleName\|altName>`
`bigDataIndex <url/relativePath>`
`vcfParentSamples <sampleName\|altName,sampleName\|altName>`
`vcfUseAltSampleNames <on/off>`
`geneTrack <track>`
`vcfDoFilter <on/off>`
`vcfDoQual <on/off>`
`vcfDoMaf <on/off>`
Additional settings found in the "Item or region tracks" section are also available for displaying Variant Call Format tracks. maxWindowCoverage maxWindowToDraw
Example of a VCF Phased Trio 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 show`
`parent <superTrack>`
Example of a Supertrack

Composite track settings

`parent <composite> [off/on]`
`compositeTrack on`
`allButtonPair on`
`centerLabelsDense <off/on>`
`dragAndDrop subTracks`
`hideEmptySubtracks <on/off>`
`hideEmptySubtracksMultiBedUrl file.bb`
`hideEmptySubtracksSourcesUrl file.tab`
`hideEmptySubtracksLabel <label>`
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

Setting	For Types	Notes
`metadata`	all
`noInherit`	all
`useScore`	bed, factorSource, bed5FloatScore, broadPeak	Replaced with spectrum.

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

Hub Track Database Definition (v3)

How to declare Dataset Display Settings in Genome Browser Hubs

Use useOneFile on for hubs with only one genome

Assembly Hubs

Miscellaneous Deprecated Settings

Use `useOneFile on` for hubs with only one genome