Search this document:

^ Top

Track Database Definition

Hub Track Database Definition (v3)

How to declare Dataset Display Settings in Genome Browser Hubs

This page describes all of the settings one might use in creating a track or assembly hub. Hubs display your own data in the Genome Browser by hosting your files on a web server and connecting them with a simple text configuration file, giving you more control and permanence than custom tracks. This initial section touches on the files and settings needed in creating a hub before providing a listing of settings separated by track type.

For those new to creating hubs: Our Hub Basics page provides a simple introduction to creating hubs.

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

Start with a hub.txt

All hubs must include a top-level hub.txt file. This file contains general settings that identify your hub in our internal databases and in the Genome Browser interface. The URL to the hub.txt is used to load your hub. Our Hub Basics describes how to create a hub.txt. A full listing of hub.txt settings can be found in the General hub configuration settings section below.

If your hub contains tracks on a single genome assembly, then you can put all of the hub, genome, and track configuration settings into a single file with useOneFile.

Defining your hub's genomes

A genomes.txt is only necessary if you are NOT using the useOneFile setting as described below. When using useOneFile, one only needs to include the genome line. This line will reference a UCSC assembly name (e.g. hg38) or a GenBank assembly available through our GenArk repository beginning with GCF or GCA (e.g. GCF_000891275.1). If an assembly is not available in GenArk, request it.

If your hub contains tracks for more than one genome, you will need to define a genomes.txt. A full listing of genomes.txt settings, including those needed for an assembly hub, settings can be found in the Assembly hub "genome" settings section below.

Use `useOneFile on` for hubs with only one genome

If your hub is only displaying one genome, one can use the useOneFile on setting to put all hub, genome, and track configuration settings into a single file. Load a working example here.

Declaring track settings

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

Running hubCheck on your hub.txt file identifies errors in settings, file paths, and formatting that could prevent your hub from loading correctly. Download hubCheck from the utilities download page and see the hubCheck documentation and related blog post for more information on validating hubs.

Using trackDb include statements

Hubs also support the use of include statements, allowing one to insert a file containing a set of trackDb stanzas into a primary trackDb. Use this when you have the same track across several assemblies, or several large, complex tracks.

Assembly Hubs

Assembly hubs can display novel genome assemblies and annotations in the UCSC Genome Browser. Note: Many genome assemblies available in GenBank are also available in our GenArk repository. If an assembly is not available in GenArk, but is available in GenBank, request it. However, if your genome assembly is not yet publicly available, you can make a custom assembly hub. To create an assembly hub, refer to our Assembly Hub User Guide or our Quick Start Guide to Assembly Hubs.

Page Contents

The remainder of this document is divided into the following sections and should be used as a ready reference. Settings are colored based on their support level:

required required settings

base common settings supported at other sites

deprecated settings that are being retired (replacement is listed in the details section)

new new settings not yet assigned a level (may be replaced)

full other settings

See the list of changes to see recent additions.

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: Multiple 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
General Hub and Assembly Configuration Settings
- General hub configuration settings
- Assembly hub "genome" settings
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>`
`canPack <off/on>`
`configureByPopup <on/off>`
`origAssembly <db>`
`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>`
`onlyVisibility <dense\|squish\|pack\|full>`
`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`
`barChartMatrixUrl <url>`
`barChartStatsUrl on`
`singleCellColumnNames off`
`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`
`colorFields default="<label>" <fieldName>="<label>" ...`
`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,...>`
`detailsScript.<plotType>.<fieldName> <jsonConfig>`
`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>`
`style <heatmap>`
`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>`
`filterBy <field1:title=[+]opt1a...> [field2:title=[+]opt2a...]`
`filterLabel.<fieldName> <label>`
`filterPriority.<fieldName> <number>`
`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>`
`highlightPriority.<fieldName> <number>`

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 targetDb`
`bigDataUrl <url/relativePath>`
`linkDataUrl <url/relativePath>`
`otherTwoBitUrl <url/relativePath>`
`chainColor <scheme>`
`chainNormScoreAvailable <yes/no>`
`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>`
`intronGap <#bases>`
`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 …]`
`pairwiseHeight <#>`
`speciesGroups <sgroup1> [sgroup2 …]`
`speciesDefaultOff <species1> [species2 ...]`
`speciesCodonDefault <species>`
`itemFirstCharCase noChange`
`irows off`
`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>`
`baseColorTickColor <lighterShade/contrastingColor>`
`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>`
`mouseOverFunction <noAverage>`
`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>`
`lollyNoStems <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>`
`hicArcLimit <integer>`
`hicArcLimitEnabled <true\|false>`
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>`
`sampleMetadataFile <url>`
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
Example hub of a superTrack with a composite track containing different track types with Views

Faceted composite track settings

`compositeTrack faceted`
`metaDataUrl <url>`
`primaryKey <field>`
`maxCheckboxes <integer>`
`dataTypes <name1\|"table title" name2\|"table title" ...>`
`defaultSortField <name>`
`subtrackUrls <field1>=<url1> <field2>=<url2> ...`
Example of a faceted composite track containing different track types:
Example of a faceted composite track containing different track samples and data types:

Aggregate or Overlay track settings

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

General Hub and Assembly Configuration Settings

This section describes hub and assembly configuration settings. It is recommended to use the useOneFile setting, which allows all hub configuration settings to be placed in a single file without the need for separate hub.txt, genomes.txt, or trackDb.txt files.

General hub configuration settings

`hub <str>`
`shortLabel <str>`
`longLabel <str>`
`genomesFile <url/relativePath>`
`email <email address>`
`descriptionUrl <url/relativePath>`
`useOneFile <on>`
Example of an opening hub stanza

Assembly hub "genome" settings

`genome <str>`
`trackDb <url/relativePath>`
`groups <url/relativePath>`
`description <str>`
`twoBitPath <url/relativePath>`
`chromAlias <url/relativePath>`
`chromAliasBb <url/relativePath>`
`chromSizes <url/relativePath>`
`chromAuthority <str>`
`codonTable default=<id> <sequenceName>=<id> ...`
`organism <str>`
`defaultPos <chr:start-end>`
`orderKey <int>`
`scientificName <str>`
`htmlPath <url/relativePath>`
`transBlat <url> <port>`
`blat <url> <port>`
`isPcr <url> <port>`
Example of a genome stanza

Miscellaneous Deprecated Settings

Setting	For Types	Notes
`metadata`	all
`noInherit`	all
`useScore`	bed, bigBed, bigGenePred, psl, bigPsl	Replaced with spectrum, which sets the same flag and takes the same type list.

required	required settings
base	common settings supported at other sites
deprecated	settings that are being retired (replacement is listed in the details section)
new	new settings not yet assigned a level (may be replaced)
full	other settings