UCSC Track Database Definition

JavaScript is disabled in your web browser

You must have JavaScript enabled in your web browser to use the Genome Browser

Track Database Definition

How to declare Dataset Display Settings in the Genome Browser

Hub contributors should use the Hub Track specific version of this document.

This document describes how to declare dataset display characteristics in the Genome Browser through trackDb settings. Introducing new datasets for display in the Browser requires declaring the location and format of the data and defining initial display characteristics. In many cases, you may need to choose how the displayed data (aka "track") may be selected and configured. These settings are declared in a simple text file format and stored in a database called the "track database", or trackDb for short.

The text file format for trackDb settings follow the simple "ra" rules which establish a "record" as a set of related settings in a "stanza" delimited by blank lines. The first line of each stanza typically establishes the "key". Each line in a stanza will contain a single word "setting" name and one or more words or numbers that follow are the setting's "value". All trackDb stanzas are keyed by "track" and most will have certain common settings followed by track specific settings. Here is an example:

        track myFirstTrack
        type bed 6
        shortLabel Example Data
        longLabel The data in this track is format "bed 6".

Every track should have these four settings. The key of this track (myFirstTrack) is the name of the dataset. If the data is loaded into a MariaDB table then the track name is almost always the table name. If the data is in one of the remote indexed file types (e.g. bigWig, bam, etc.) then the name is typically the root file name. However, this is a key to the track so it must be unique within the Genome Browser. (Data hubs need only declare track names unique to their hub.) After the "track" key, the most important setting for defining a track is the "type". This tells the Browser which format the data is in, defines how to display it, and determines which options are available for fine control of that display.

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

Common trackDb settings
Settings by track type – with examples
- bed/bigBed: Item or region tracks
- wig/bigWig/bedGraph: Signal graphing tracks
- genePred/bigGenePred: Gene models and predictions
- bam/cram: Compressed Sequence Alignment/Map tracks
- pgSnp: Personal Genome SNP tracks
- vcfTabix: Variant Call Format
- vcfPhasedTrio: Variant Call Format Trios
- psl/bigPsl: Sequence alignments
- chain/bigChain and netAlign: Paired sequence alignments
- wigMaf/bigMaf: Multiple alignments
- expRatio: Microarray expression data
- snp: Short genetic variants from dbSNP
- barChart/bigBarChart: Categorical values over a region
- interact/bigInteract: Pairwise interactions
- bigLolly: Lollipop charts
- hic: Hi-C contact matrices
- Specialize or rarely used:
  altGraphX, bedDetail, clonePos, ctgPos, downloadsOnly, encodeFiveC, factorSource, rmsk and snake.
Grouping tracks into sets and hierarchies – with examples
Special settings for custom tracks
Obscure or special cases – (aka Rejections)
Table of Contents

Open/close all details.

Common trackDb settings

Common Settings

`track`
`type`
`shortLabel`
`longLabel`
`visibility`
`html`

Common Optional Settings

`bigDataUrl <url/relativePath>`
`boxedCfg <on/off>`
`color <red,green,blue>`
`altColor <red,green,blue>`
`chromosomes <chr1,chr2,...>`
`configureByPopup <on/off>`
`darkerLabels on`
`dataVersion <str>`
Related settings: `directUrl <url>`
`hgsid on`
`iframeUrl <url>`
`iframeOptions <string>`
`mouseOver <pattern>`
`mouseOverField <fieldName>`
`multiRegionsBedUrl`
`otherDb <otherDb>`
`origAssembly <db>`
`pennantIcon <iconFile>/<text color> [html [tip]]`
`priority <float>`
`release <alpha/beta/public>[,beta/public]`
`table <tableName>`
`tableBrowser <off/on/noGenome> [table1 ...]`
`url <url>` `urlLabel <label>` `idInUrlSql <sql for id>`
`urls <fieldName1>="<url1>" <fieldName2>="<url2>" ...`
`skipEmptyFields on`
`skipFields <fieldName1>,<fieldName2> ...`
`sepFields <fieldName1>,<fieldName2> ...`
`wgEncode on`

Settings by track type

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

bed/bigBed - Item or region track settings

`type bed <3-12> [+/.]` `type bigBed <3-12> [+/.]`
`type bed5FloatScore` `type bedRnaElements` `type broadPeak` `type coloredExon` `type gvf` `type ld2` `type narrowPeak` `type peptideMapping`
`bigDataUrl <url/relativePath>`
`colorByStrand <red,green,blue> <red,green,blue>`
`compareGenomeLinks <db[.table[.column]]=label> [db[.table[.column] =label …]`
`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>`
`<column>Filter <low>[:<high>]` `scoreFilter <low>[:<high>]` `pValueFilter` `qValueFilter` `signalFilter` `<column>FilterLimits <low>[:<high>]` `<column>FilterByRange <off/on>`
`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>`
`filterBy <field1:title=[+]opt1a...> [field2:title=[+]opt2a...]`
`itemRgb on`
`maxItems <integer>`
`maxWindowCoverage <integer>`
`maxWindowToDraw <integer>`
`minGrayLevel <1-9>`
`noScoreFilter on`
`spectrum on` `scoreMax <integer>` `scoreMin <integer>`
`thickDrawItem <off/on>`

Less frequently used item track settings
`bedFilter on`
`bedNameLabel <label>`
Related settings: `baseColorUseSequence < <extFile {seqTable} <extFile> / hgPcrResult / lfExtra / nameIsSequence / seq1Seq2 / ss >`
`baseColorUseCds <given/table <table>>`
`baseColorDefault <diffBases/diffCodons/itemBases/itemCodons/genomicCodons>`
`baseColorTickColor <lighterShade/contrastingColor>`
`showDiffBasesAllScales on`
`showDiffBasesMaxZoom <basesPerPixel>`
`showCdsAllScales`
`showCdsMaxZoom <basesPerPixel>`
`exonArrowsDense <off/on>`
`itemDetailsHtmlTable <table>`
`itemImagePath <path> <suffix>` `itemBigImagePath <path> <suffix>`
`linkIdInName on`
`mergeSpannedItems <on/off>`
`mafTrack <trackName>`
`nextExonText <str>` `prevExonText <str>`
`scoreLabel <label>`
`showTopScorers #`
Examples of item base types

wig,bigWig - Signal graphing track settings

`type wig <low#> <high#>` `type bigWig <#> <#>`
`type bedGraph <field>` `minLimit <#>` `maxLimit<#>`
`alwaysZero <off/on>`
`autoScale <off/on/group>`
`bigDataUrl <url/relativePath>`
`graphTypeDefault points`
`logo on`
`maxHeightPixels <max:default:min>`
`maxWindowToQuery <integer>`
`negateValues <on>`
`spanList <s1>[,s2…]`
`smoothingWindow <off/1-16>`
`transformFunc <NONE/LOG>`
`mouseOverFunction <noAverage>`
`viewLimits <lower:upper>` `viewLimitsMax <lower:upper>`
`wigColorBy <bedTable>`
`windowingFunction <mean/mean+whiskers/maximum/minimum>`
`yLineMark <#>` `yLineOnOff <off/on>` `gridDefault on`
Examples of signal graphing tracks

genePred - Gene model track settings

`type genePred [pepTable [mrnaTable]]`
Related settings: `geneClasses <cl1 cl2...>`
`gClass_<xxx> <red,green,blue>`
`itemClassTbl <table>`
`itemClassNameColumn <col>`
`itemClassClassColumn <col>`
`filterBy <field1:title=[+]option1a...> [field2:title=[+]opt2a...]`
`autoTranslate 0`
`intronGap <#bases>`
`defaultLinkedTables <table1>[,table2...]`
`idXref <idColumn> <altIdColumn>`
`oldToNew <tableName>`
Additional settings found in the "Item or region tracks" section are also available for displaying gene models. baseColorUseSequence, baseColorDefault, itemDetailsHtmlTable, maxWindowCoverage, maxWindowToDraw, showDiffBasesAllScales, showDiffBasesMaxZoom
Examples of genePred tracks

bam/cram - Compressed Sequence Alignment track settings

`type bam`
`bigDataUrl <url/relativePath>`
`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. baseColorUseSequence, baseColorDefault, maxWindowCoverage, maxWindowToDraw, showDiffBasesAllScales, showDiffBasesMaxZoom
Example for 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`
`barChartMetric <metric>`
`barChartUnit <unit>`
`barChartMatrixUrl <url/relativePath>`
`barChartSampleUrl <url/relativePath>`
`barChartCategoryUrl <url/relativePath>`
`barChartFacets <url/relativePath>`
`barChartStatsUrl <url/relativePath>`
`barChartMerge <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

bigInteract - Pairwise interaction display

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

bigLolly - Lollipop charts

`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>`
Example of a bigLolly track

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

pgSnp - Personal Genome SNP track settings

`type pgSnp`
`pgPolyphenPredTab <arg>`
`pgSiftPredTab <arg>`
Example of a Personal Genome SNP track:

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>`
`vcfDoQual <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>`
`vcfDoQual <on/off>`
Additional settings found in the "Item or region tracks" section are also available for displaying Variant Call Format tracks. maxWindowToDraw
Example of a VCF Phased Trio track

psl - Sequence alignment tracks settings

`type psl <subtype> [otherDb]`
`blastRef <assembly.table>`
`colorChromDefault off`
`pred <assembly.table>`
`pslSequence <no/all/different>`
`transMapGene <assembly.table>` `transMapInfo <table>` `transMapSrc <assembly.table>` `transMapTypeDesc <label>`
`ucscRetroInfo`
Additional settings defined elsewhere in this document are also available for displaying psl tracks. baseColorUseSequence, baseColorDefault, chainLinearGap, chainMinScore, indelDoubleInsert, indelQueryInsert, indelPolyA, itemDetailsHtmlTable, matrix, matrixHeader, maxItems, maxWindowCoverage, maxWindowToDraw, showCdsAllScales, showCdsMaxZoom, showDiffBasesAllScales, showDiffBasesMaxZoom, spectrum
Examples of psl alignment tracks

chain and netAlign - paired species alignment track settings

`type chain <otherDb>` `otherDb <otherDb>`
`type netAlign <otherDb> <otherChainTable>` `otherDb <otherDb>`
`chainColor <scheme>`
`chainLinearGap <loose/medium>`
`chainMinScore <#>`
`chainNormScoreAvailable <yes/no>`
`matrix <size> <#,#,#,#,…>` `matrixHeader <b1,b2,b3,b4>` `$matrix` token in html.
`spectrum on`
Examples of chain and netAlign tracks

wigMaf - Multiple alignment track settings

`type wigMaf <minVal> <maxVal>`
`frames <table>`
`irows off`
`itemFirstCharCase noChange`
`pairwiseHeight <#>`
`speciesCodonDefault <species>`
`speciesDefaultOff <species1> [species2 ...]`
Related settings: `speciesOrder <species1> [species2 …]`
`speciesGroups <sgroup1> [sgroup2 …]` `sGroup_<sgroupN> <species1> [species2 …]`
`speciesLabels <species1=newLabel1> [species2=newLabel2 …]`
`summary <tableName>`
`treeImage <imageFile>`
`wiggle <table1> <leftLabel1> <uiLabel1> [table2 leftLabel2 uiLabelN ...]`
Examples of wigMaf tracks

expRatio - Microarray expression track settings

`type expRatio`
`expDrawExons on`
`expScale <#>`
`expStep <#>`
`expTable <tableName>`
`groupings <fileName>`
Example of an expRatio track:

snp - Short genetic variants from dbSNP track settings

`type bed 6 +`
`chimpDb <db>`
`chimpMacaqueOrthoTable <table>`
`chimpOrangMacOrthoTable <table>`
`codingAnnoLabel_<table> <text>`
`codingAnnotations <table>[,table]`
`defaultGeneTracks <genesTrack>[,genesTrack]`
`defaultMaxWeight <1\|2\|3>`
`hapmapPhase <II\|III>`
`macaqueDb <db>`
`orangDb <db>`
`snpExceptions <table>`
`snpExceptionDesc <table>`
`snpSeq <table>`
`snpSeqFile <path>`
Additional settings found in the "Item or region tracks" section are also available for displaying snp tracks. maxWindowCoverage maxWindowToDraw
Example of a snp track:

Specialized or rarely used types:

NONE OF THESE ARE FOR HUBS. Nor are any of their settings.

altGraphX - Alternate splicing gene model track settings

`type altGraphX`
Example of an altGraphX track:

bedDetail - Text extended bed track settings

`type bedDetail <#>`
Additional settings defined elsewhere in this document are also available for displaying bedDetail tracks. itemRgb, url, urlLabel TODO: Currently almost no settings or configuration options are supported by bedDetail tracks. However, there is very little, in principle, that should prevent adding support for almost all the "Item or region tracks" settings.
Example of a bedDetail track:

clonePos - Genome coverage track settings

`type clonePos`
Example of a clonePos track:

ctgPos - Physical map contigs track settings

`type ctgPos`
Example of a ctgPos track:

downloadsOnly - Specialized downloadable file track settings

`type downloadsOnly`
`fileSortOrder ...`
Example of a Downloads Only track:

encodeFiveC - Five C Chromatin interaction track settings

`type encodeFiveC`
`interTable <tableName>`
`interTableKind <label>`
Example of an encodeFiveC track:

factorSource - Combined items track settings

`type factorSource`
`sourceTable <table>`
`inputTrackTable <table>`
`inputTableFieldDisplay <f1> [f2...]`
`filterBy <field1:title=[+]option1a...> [field2:title=[+]opt2a...]`
`motifTable <on>`
`motifTable <table>`
`motifPwmTable <table>`
`motifMapTable <table>`
`motifMaxWindow <window size>`
Example of a factorSource track:

rmsk - Repeat masking track settings

`type rmsk`
Additional settings found in the "Item or region tracks" section are also available for displaying gene models. maxWindowToDraw, spectrum
Example of a Repeat Masking track:

snake - Self referencing alignment track settings

`type snake <db>` `otherDb <otherDb>`
Additional settings found in the "Item or region tracks" section are also available for displaying snake tracks. maxWindowToDraw, spectrum
Example of a snake track:

Grouping tracks into sets and hierarchies

All tracks have to be assigned to one predefined track group ("Mapping and sequencing", "Genes", etc).
In addition and 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

Predefined major track groupings setting

`group <groupId>`
Example of a track belonging to a predefined group:

Supertrack (Folders) track settings

`superTrack on`
`parent <superTrack>`
Example of a Supertrack:

Composite track settings

`compositeTrack on`
`parent <composite> [off/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…]`
`subGroups <gTag1=mTag1?> [gTag2= mTag2?]`
`dimensions <dimX=gTag#> [dimY=gTag#] [dimA=gTag# ...]`
`filterComposite <dim[A/B/C][=one]> [dimB dimC ...]`
`dimension<?>checked <mTag1a> [mTag1b …]`
`controlledVocabulary <pathToFile> <gTag#=mdbVar> [gTag#=mdbVar …]`
`sortOrder <gTag#=+/-> [gTag#=- …]`
`fileSortOrder <var=val> [var=val ...]`
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:

Special settings for custom tracks

Custom track specific settings

`genome`
`offset`
The following trackDb style settings are only set internally by the hgCustom CGI code.
`browserLines`
`dataUrl`
`dbTrackType`
`fieldCount`
`firstItemPos`
`htmlFile`
`htmlUrl`
`initialPos`
`inputType`
`itemCount`
`mafFile`
`maxChromName`
`origTrackLine`
`tdbType`
`wibFile`
`wigFile`

Obscure or special case settings. (aka Rejections)

Rejected "types":

axt – rare bed 3 variant (replaced with netAlign?), panTro1.axtNetHg16

drosophila/dp1/trackDb.ra:type axt dm1

human/hg13/trackDb.ra:type axt mm3

human/hg15/trackDb.ra:type axt mm3

worm/ce1/trackDb.ra:type axt cb1

worm/ce2/trackDb.ra:type axt cb1

bedLogR – encode 1% test only??? Not found with tdbQuery from *

human/encodeTest/wgEncodeMetaCheckTest.ra

chromGraph - ??? Not found in tdbQuery -strict from *

gff http://genome.ucsc.edu/FAQ/FAQformat.html#format3

Not found in tdbQuery -strict from *

gtf http://genome.ucsc.edu/FAQ/FAQformat.html#format4

Not found in tdbQuery -strict from *

maf – replaced by wigMaf hg17, tdbQuery -strict: 1 track: fr1.tbaFishBirdCFTR

http://genome.ucsc.edu/FAQ/FAQformat.html#format5

net but not netAlign - custom only??? Not found with tdbQuery non strict

sample – RARE bed variant, hg15.affyTranscriptome, Affymetrix Transcriptome

hg15.hg15Mm3L

Completely replaced by type wig and more recently bigWig

List of Miscellaneous Specal Case, Deprecated, Rejected or Rarely Used Settings

Rejected settings	For Types	Reason
`accession`	all ENCODE only	ENCODE only; DEPRCATED (replaced with mdb )
`canPack <off/on>`	all	NOT FOR HUBS. Deprecated. Almost tracks can be displayed in the five standard visibilities. However on some track types such as wiggles, `squish` and `pack` offer no real advantage over `dense` and `full`. By default, these tracks will not offer the less valuable visibilities. Nevertheless, you can make your track offer these visibility choices by turning canPack on. Note: subtracks of composites will always offer all five choices. Example: canPack on
`cdsDrawDefault`	genePred	There are a number of occurrences of cdsDrawDefault in our trackDbs, always set to ‘genomic\ codons ‘. However, I have found no documentation and no code that references this setting.
`cdsDrawOptions`	psl	I have found no documentation and no code that references this setting. Also, I do not see it in our trackDbs.
`cdsEvidence`	genePred	Used by JK experimental tracks only as either `jkgTxCdsEvidence` or `jkgTxCdsEvidence2`. This will show an evidence table named in the setting.
`cell`	bed, bedGraph ENCODE only	Obsolete: replaced with metaDb.
`chip`	expRatio, bed ENCODE only	DROP (no takers in any of our trackDb.ra files)
`dateSubmitted`	bedGraph, bed ENCODE only	Obsolete: replaced with metaDb.
`dateUnrestricted`	bed ENCODE only	Obsolete: replaced with metaDb.
`db`	chain, netAlign, genePred, bed 3	Not found in any of our trackDb.ras. Further, this is the same as assembly so implicit.
`dbProfile`	all	In hg18 experimental and cancerGenomics only.
`dividers`	all	OBSOLETE: use sortOrder instead.
`endFudge`	bed	Special case for hg17 HGSV Discordant (variation) tracks. Used in hgc to fudge chromEnd, I think.
`ensArchive`	genePred	Only in danRer4 Ensembl NonCoding to generate an Ensembl URL.
`ensemblTranscriptIdUrl`	genePred ENCODE Gencode Only	Special for ENCODE Gencode to generate external URL.
`ensemblGeneIdUrl`	genePred ENCODE Gencode Only	Special for ENCODE Gencode to generate external URL.
`ensemblIdUrl`	genePred ENCODE Gencode Only	Special for ENCODE Gencode to generate external URL.
`expProbeTable`	expRatio	Can't find code that supports this.Rare: only in human. affyHumanExon "Affy All Exon"
`extTable`	all	This setting points to a one record table that holds the external filename. This should be replaced by: track, table or bigDataUrl. (rare bigWig hg18.brTestPlus experimental track)
`extraFields`	bed	OBSOLETE: replaced by looking up "as" table description. However, that method does not allow for: selective inclusion/exclusion of fields reordering fields formatting titles
`filePos`	all	Can't find this in any of our trackDb.ra files.
`filterTopScorers`	bed5FloatScoreWithFdr, bed5FloatScore ENCODE only	Currently only used by pilot encode 1%. Presents user option to limit to the top scoring N items. Might be useful in other MariaDB table based tracks but how valuable is it?
`gainColor` `lossColor`	bed ENCODE only	Currently only used by pilot encode 1% in hg17.encodeDless. Provides special color for "gain" and "loss" items.
`graphType`	bedGraph	Not found in code. Probably typo of graphTypeDefault. (rare hg18.encodeRegulomeDnaseArray)
`hgGene`	genePred	Cannot find code for this. No effect. ???
`informant`	genePred	Special setting for N-SCAN genes. Swapped into html description page.
`inputTracksSubgroupDisplay`	bed, factorSource ENCODE only	Only in hg18/hg19 wgEncodeReg*Clustered tracks. In code #ifdef TO_BE_REMOVED.
`itemAttrTbl`	genePred	Only used in borEut13. transMapRefGene.
`linesAt`	chromGraph	Unused track type (tdbQuery -strict).
`longlabel`	genePred	Typo, should be longLabel.
`longLabelClip`	all	Only used in sacCer3 (tdbQuery -strict).
`mafDot`	wigMaf	Can't find this in any of our trackDb.ra files and only supported as cart var.
`mafDotDefault`	wigMaf	Can't find this in any of our trackDb.ra files.
`mapDispatcher`	expRatio	Only hg17 group "x" [tingwang 2007] and not in C.
`maxScore`	broadPeak	Obsolete, replaced with scoreFilterLimits.
`metadata`	all ENCODE only	OBSOLETE: replaced by metaDb. Currently only way for datHubs to have metadata dropdowns. Used by WashU hubs.
`mgiUrl`	bed	Special case variant of url used by no current tracks (tdbQuery -strict).
`mgiUrlLabel`	bed	Special case variant of url used by no current tracks (tdbQuery -strict).
`minMax`	chromGraph	Unused track type (tdbQuery -strict).
`minScore`	bed, narrowPeak, broadPeak	Obsolete, replaced with scoreFilterLimits.
`msaTable`	wig, wigMafProt, wigMaf	Only hiv tracks use this. Code in wigMaf display and is used to look up species order.
`ncbiAccXref`	bed	Special case used by hg17/hg18 kiddEichler tracks. Names a table to convert kiddEichler IDs to NCBI IDs and print links.
`nextItemButton`	all	This setting lets you override the Browser wide setting to disable nextItem arrows (which is off by default). When this is on, the nextItem arrows will show up for your track. The opposite does not seem to be the case, where nextItems are enabled, but you want to exclude them from your track.
`noInherit`	all	This one should be OBSOLETE but there continue to be edge cases where this setting has some affect. Currently only 2 places this is read this: in hdb to makesuperChildren inherit settings from their supertrack. This is done by putting the super settings into the child's settings hash. tdbQuery where it appears to have no affect.
`nonBedFieldsLabel`	bigBed	OBSOLETE when bigBed has "as" definitions. Instead, the extraFieldsPrint should pick up the non-standard bed fields straight from the as definition.
`notNCBI`	bed	Only used in drosophila dm2/dm3. Referenced in hgc.c code.
`ococci`	bed	Not referenced in any of our trackDb.ra files or in code.
`otherOrg`	chain, netAlign	Typo: should be otherDb.
`onlyVisibility`	all	Not universally supported (rightClick/subtrack cfg, etc.) so deprecate or else expand. This setting restricts the visibility options of a track to only one setting such as "`full`". (rare hg19.lincRNAsAllCellTypeTopView)
`otherDbTable`	bed	Special case for Jackson lab's QTL (Quantitative Trait Locus) tracks.
`pairedEndUrlFormat`	bed	Special case only used on kiddEichler track. This is another external URL variant.
`pairwise`	wigMaf	Deprecate, replaced by summary.
`patDb`	expRatio	Only hg17 group "x" [jzhu 2007] and not referenced in C.
`patKey`	expRatio	Only hg17 group "x" [jzhu 2007] and not referenced in C.
`patTable`	expRatio	Only hg17 group "x" [jzhu 2007] and not referenced in C.
`pgDbLink`	bed	Special only used in hg18/hg19 Genome Variants so far. This setting is used to name one or more tables that hold links to phenotype and other databases for pgSnps. Each table must have chrom, chromStart, chromStop, name and srcUrl as fields. The links will be seen in the bed item details page and will be looked up in each listed table by item location. Example: pgDbLink pgKb1PhenCode pgKb1Snpedia pgKb1Hgmd
`private`	bed	Only used in human/hg7/trackDb.ra, and not even there using tdbQuery -strict. Prevents access to data by removing from trackList when doing "pruneEmpties". Gotta wonder when the track is ever seen in the browser or why it is a track at all.
`pslTable`	bed	Special for hg18/hg19 illuminaProbes "Illumina WG-6". Used in hgc. (Hardwired to be the same `illuminaProbesAlign` when track is "illuminaProbesAlign".) Used for making an hgcAnchor `htcIlluminaProbesAlign`.
`pubsArticleTable`	bed, psl	Special for publications track.
`pubsMarkerTable`	bed, psl	Special for publications track.
`pubsPslTrack`	bed, psl	Special for publications track.
`pubsSequenceTable`	bed, psl	Special for publications track.
`refSeqAnnoVersion`	genePred	Special for rheMac2.refSeqAnno track. Not found in code.
`scoreFilterMax`	bed, bedLogR, peptideMapping, bigBed	OBSOLETE: replaced by scoreFilterLimits
`searchMethod`	bed	Error. Should be part of searchTable stanza, not track stanza. TODO: Document searchTable stanza.
`searchType`	bed	Error. Should be part of searchTable stanza, not track stanza. TODO: Document searchTable stanza.
`selectSubject`	psl	Special only used in hiv(only used by hiv and h1n1. (Just h1n1 according to tdbQuery -strict).
`seqTable`	bed	Special for hg18/hg19 illuminaProbes "Illumina WG-6". Used in hgc. (Hardwired to be the same `illuminaProbesSeq` when track is "illuminaProbesAlign".) Used for making an hgcAnchor `htcIlluminaProbesAlign`.
`settingsByView`	all	OBSOLETE: replaced with "view in the middle" view as separate track.
`snpTable <table>`	bed gwasCatalog only	Special for gwasCatalog: table used to map dbSNP IDs to genomic coords
`snpVersion`	bed gwasCatalog only	Special for gwasCatalog: dbSNP build number of table used to map dbSNP IDs to genomic coords
`speciesTarget`	wigMaf	OBSOLETE. Not in our trackDbs (tdbQuery -strict). Specifically ifdef'd out of code with `#define BRANEY_SAYS_USETARG_IS_OBSOLETE.`
`speciesTree`	wigMaf	OBSOLETE. Replaced by treeImage. Not in our trackDbs (tdbQuery -strict). Specifically ifdef'd out of code with `#define BRANEY_SAYS_USETARG_IS_OBSOLETE.`
`speciesUseFile <fileName>`	wigMaf	Deprecated Much more rarely used, this setting can replace `speciesOrder` and `speciesGroups`. Set the `speciesUseFile` to a path relative to the apache cgi-bin. The file should contain a single species name as the first word of each line. Example: speciesUseFile speciesLists/conserved8Way.txt
`stripPrefix`	bam	Not yet implemented? Only on hg18.oneKGHighCovSeq experimental track.
`subgroups`	bed	Typo: should be subGroups.
`subTrack`	all	OBSOLETE: replaced with parent.
`symbolTable`	bed, genePred	In hgTracks, flyBaseGeneName() methods, if an item name is found in this symbol table, the symbol name will be shown instead. Found in drosophila and strangely rn4 RGD Genes (but table named in rn4 does not have a symbol column. Instead, symbol lookup is hard-coded to rgdGene2ToSymbol).
`txInfo`	genePred	Only seems to be used in experimental tracks in hg18 and mm8.
`urlName`	genePred	Not referenced in code and rarely used. (e.g. hg18: encodePseudogeneConsensus, encodePseudogeneYale).
`url2`	bed	Special cased second URL used much like url.
`url2Label`	bed	Special cased second URL label used much like urlLabel.
`useScore`	bed, factorSource, bed5FloatScore, broadPeak	Deprecate: replaced with spectrum as a slighly less obscurely named setting.
`vegaGeneIdUrl`	genePred ENCODE Gencode Only	Special for ENCODE Gencode to generate external URL.
`vegaTranscriptIdUrl`	genePred ENCODE Gencode Only	Special for ENCODE Gencode to generate external URL.
`visibilityViewDefaults`	all	OBSOLETE since view in the middle change. LOSE
`wgEncodeGencodeVersion`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodeAttrs`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodeExonSupport`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodeGeneSource`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodeTranscriptSource`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodePdb`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodePubMed`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodeRefSeq`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodeTag`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodeTranscriptSupport`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodeUniProt`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodePolyAFeature`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodeAnnotationRemark`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`wgEncodeGencodeTranscriptionSupportLevel`	genePred ENCODE Gencode Only	Special for ENCODE Gencode.
`yLinOnOff`	wigMaf	Typo: should be yLineOnOff.
`yalePseudoAssoc`	all ENCODE Gencode Only	Special for ENCODE Gencode.
`yalePseudoUrl`	all ENCODE Gencode Only	Special for ENCODE Gencode to generate external URL.
`yaleUrl`	all ENCODE Gencode Only	Special for ENCODE Gencode to generate external URL.

The following settings, which must be defined for each trackDb record, are common to all data format types. The first few settings are required for all tracks. Some type-specific requirements will be mentioned in the appropriate sections to follow.

track

Required: Yes

This is the name of the dataset and must be unique within the Genome Browser or dataHub. Typically this is the MariaDB table name or remote data file root name (without path or suffix). Must begin with a letter and contain only the following chars: [a-zA-Z0-9_].

Example:

   track myFirstTrack

type

Required: Yes

Declares the format of the data and is used to determine display methods and options.

Valid settings:

altGraphX, bam, bed, bed5FloatScore, bedGraph, bedRnaElements, bigBarChart, bigBed, bigInteract, bigLolly, bigPsl, bigChain, bigMaf, bigWig, broadPeak, chain, clonePos, coloredExon, ctgPos, downloadsOnly, encodeFiveC, expRatio, factorSource, genePred, gvf, hic, ld2, narrowPeak, netAlign, peptideMapping, psl, rmsk, snake, vcfTabix, wig, wigMaf

Not all track types are supported in hubs. The types specifically supported are called out at the top of the Hub Track Database Definition page. In many cases the type setting includes additional parameters to further specify the data format. Some track types have additional setting requirements, to be discussed below.

Example:

   type bed 6 +

type

Required: Yes

Declares the format of the data and is used to determine display methods and options.

Valid settings:

bam/cram, bigBarChart, bigBed, bigChain, bigInteract, bigLolly, bigMaf, bigPsl, bigWig, halSnake, hic, vcfTabix,

Detailed descriptions of each type can be found below. In many cases the type setting includes additional parameters to further specify the data format. Some track types have additional setting requirements, to be discussed below.

Example:

   type bigBed 6 +

shortLabel

Required: Yes

Specifies the track's "short label", which is used in a number of places in the Browser to identify the track. For example, the short label is displayed alongside the track in the Browser image. This label must be brief and is limited to 17 printable characters.

Example:

   shortLabel Human mRNAs

longLabel

Required: Yes

Specifies the track's "long label", which is also used in numerous places in the Browser to identify a track. For instance, the long label is displayed above the track's data in the Browser image. This label should be descriptive enough to allow users to uniquely identify the track within the Browser. It is limited to 76 printable characters.

Example:

   longLabel Human mRNAs from GenBank

meta

Required: No

Meta specifies the metadata tag for this track. This tag is a key into the metadata table specified in either metaDb or metaTab in the genomes.txt file. The meta tag can be any alphanumeric string. Each meta tag should appear in a trackDb stanza AND in either the tab-separated file specified by metaTab, or tagStorm file specified by metaDb in the hub's genomes.txt file. Examples on how to include metadata in your hubs can be found on the following metadata guide.

visibility

Required: No

Visibility (i.e. "display mode") specifies which of 5 modes (including 'hide') should be used to display the track within the Browser image. This setting is almost always dynamically customizable by each user. The exact configuration of the display for each mode depends upon the track's type, and some modes may not be supported for certain track types. Please note visibility settings in composite subtracks are directly inherited from the parent. Therefore, any visibility lines added at the subtrack level of a composite will be ignored. Be sure to experiment with this setting to verify that it works as expected for your track type and track structure.

Valid settings:

hide: DEFAULT. The track is not displayed in the Browser image unless the user changes the display setting.
dense: The track is displayed as a single line or ribbon. In many cases multiple items are summarized or drawn on top of one another, and the long labels are not displayed.
squish: Each item is drawn individually, but at half height and without a label. (Not supported for all types.)
pack: Items are displayed individually at full height, but in a much more compact vertical space than in full mode. (Not supported for all types.)
full: Each item is displayed as a separate line in the Browser image. Graphed signals may be displayed in varying heights.

Example:

   visibility dense

html

Required: No

Use the html path/to/explain.html to specify the file that contains the complete description of a track in HTML format. The path of this file name is relative to the path of the trackDb file, or it can be a full URL. It is also possible to have the ".html" suffix implied, for instance just have html explainFile. To further simplify trackDb, if there is a file, nameOfTrack.html, in the same directory as the trackDb matching the name of the track, track nameOfTrack, then the html file does not need to be declared.

To help users understand Public Hub data, we request you provide a web page that explains what your Track Hub is presenting. Adding an html page for your Track Hub is also useful to instruct people on how to cite your data.

To be consistent with standard Genome Browser track descriptions, html for tracks should contain several sections as seen below. Here is a link to an example template that you can use.

Description

A few sentences describing the track.

Display Conventions and Configuration

If the track has colors, or unusual display properties, explain them in this section, or how to configure special settings.

Methods

This section can explain data-handling algorithms, or the significance of scores if generated in a special fashion.

Credits

This section helps people find the contacts for questions about the data. Please include an email or laboratory web page.

References

Relevant publications regarding the data.

Example:

    html docs/myFirstTrack.html

Or with full path:

    html https://path/to/location/docs/explainMyData.html

Common, though less frequently used settings

The following settings are available for many or all track types but are less frequently used. Most are optional, but some may be required for specific track types or in specific situations.

Inside hint: The ra file format supports '\' continuation characters. If the setting is long or complex, break it into several lines using terminating '\' characters to make it more readable.

linkDataUrl <url/relativePath>

Required: For Hubs

The location of a remote data file containing the chain link data.

lollyField <integer>

Use the given field as the height of the lollipop.

noStems <on/off>

Don't draw the stems of the lollipops.

lollySizeField <integer>

Use the given field as the size of the lollipop, measured in percentage of the total available drawing area.

lollyMaxSize <integer>

The maximum size of a lollipop in the file, used to establish margins.

yAxisLabel.<integer> <integer> <on/off> <R,G,B> <string>

Add a label on the y axis at the given position. Draw a line of color if requested.

yAxisNumLabels.<on/off> <integer>

Turn the y axis number labels on or off

bigDataUrl <url/relativePath>

Required: For Hubs

The location of a remote data file containing the bulk of the data for the track. This setting is required for all data tracks in a track hub.

The setting is either the full URL (including http: or another protocol) or it is relative to the directory in which the trackDb file containing this setting is located. The file must be in one of the supported remote data file formats: bam/cram, bigBarChart, bigBed, bigChain, bigLolly, bigInteract, bigMaf, bigPsl, bigGenePred, bigNarrowPeak, bigWig or vcfTabix. Note that bam/cram and vcfTabix/vcfPhasedTrio types require a separate index file that must have the same name as the data file plus a standard suffix (".bai" and ".tbi" respectively), unless bigDataIndex is used. All occurrences of the string $D in the URL will be substituted with the genome assembly database name. This allows a trackDb entry to be used with for multiple assemblies. $D substitution is not implemented for track hubs.

Example:

   bigDataUrl http://vizhub.wustl.edu/VizHub/hg19/biBrainH3K4me1.bb

   bigDataUrl biBrainH3K4me1.bb

bigDataIndex <url/relativePath>

The location of a remote data file containing the index. This setting can be used when the index cannot be placed alongside the big data file, e.g. because of restricted access permissions or due to file name constraints.

Example:

   bigDataIndex http://vizhub.wustl.edu/VizHub/hg19/biBrainH3K4me1.bam.bai

boxedCfg <on/off>

Configuration controls can be placed inside a box on the configuration page. This setting is decorative only, but can make a busy page look more cohesive. Not all track types currently support this feature, but the most common types do, including wig, bigWig, bed, and bigBed. DEFAULT: off.

Example:

   boxedCfg on

canPack <off/on>

NOT FOR HUBS. Deprecated.

Most tracks can be displayed in all five visibilities modes. However on some track types such as wiggles, the squish and pack modes offer no real advantage over the dense and full modes. By default, these tracks will not offer the squish and pack vilibility settings. Nevertheless, you can make your track offer these visibility choices by turning canPack on. Note: subtracks of composites will always offer all five choices.

Example:

   canPack on

color <red,green,blue>

Many track types allow the color of the data displayed in the image to be specified with this setting. The setting accepts red, green and blue values, each in the range of 0-255 and delimited by commas. Though this setting is widely supported, some track types in certain display modes ignore it, such as the EST tracks in dense mode.

Example:

   color 255,0,0

This example sets the color to red.

altColor <red,green,blue>

Many track types allow setting a color range that varies from color to altColor. For instance the CpG Island tracks use the altColor setting to display the weaker islands, while the stronger ones are rendered in color. If altColor is not specified, the system will use a color halfway between that specified in the color tag and white instead. Tracks using altColor with the windowing function "mean+whiskers" will see the shading of colors impacted, with lighter shades for values within a standard deviation around the mean, most noticeable when zoomed out and average calculations are taking place.

Example:

   altColor 0,0,255

This example sets the alternate color to blue.

chromosomes <chr1,chr2,...>

Some datasets do not contain data for all chromosomes of a genome. When this is true, use this setting as a comma-separated list of the chromosomes that are covered. The system displays a message that no data is available when the user browses chromosomes not included in this list.

Example:

   chromosomes chr1,chr7,chr18,chr19,chr22,chrX,chrM

configureByPopup <on/off>

NOT FOR HUBS.

Most track displays that can be configured by a user can also be configured from directly within the Browser image through a right-click option that pops up a configuration dialog. While this functionality works on the majority of track types, some configuration dialogs are too complex or have too much embedded javascript control to be reliably configured through a pop-up. To turn off the ability to configure the track via right-click, change this setting to "off". The user will still be able to configure the track on the track's configuration page. DEFAULT: on.

Example:

   configureByPopup off

darkerLabels on

If this setting is "on", the color of the left labels on the track display will have a somewhat darker color than the track display itself. This can be useful where the track color (which may have been chosen to adhere to external conventions) is too light for readable labels.

dataVersion <str>

Many tracks undergo multiple revisions over time. In some cases, the older versions should be retained, but even if they are not, it can be useful to declare the current version of the track. Use this setting to display a version statement on the track configuration page and item details page of a track. The string will support limited HTML. For native tracks, not track hubs, this setting can also be a local absolute filename to read the version string from.

Example:

   dataVersion May 2011 <em>beta</em>

Related settings:
directUrl <url>

By default, items shown in the Browser image can be linked to a details page giving information about that item. The link can instead go to the URL declared here. The URL is formatted as a printf line including the following fields in this order:

%s - item name
%s - chromosome name
%d - chromosome start position (relative to zero)
%d - chromosome end position (relative to one)
%s - track name
%s - database name

Not all fields need be present, but those present must be in this order, and if a later field is present, all earlier fields must be used. The URL can either be a full external URL or local to the web site.

Examples:

   directUrl http://mygenes.org/cgi-bin/geneView/%s

   directUrl /cgi-bin/hgGene?hgg_gene=%s&hgg_chrom=%s&hgg_start=%d&hgg_end=%d&hgg_type=%s&db=%s

hgsid on

NOT FOR HUBS.

The "cart" is a hidden table that contains the persistent selections that users have made in the Genome Browser. To ensure your directUrl has access to these cart settings, include the user's Browser ID with this setting.

Example:

    directUrl /cgi-bin/hgGene?hgg_gene=%s&hgg_chrom=%s&hgg_start=%d&hgg_end=%d&hgg_type=%s&db=%s
    hgsid on

In this example the URL specified by directUrl will have the user's Browser ID appended so that cart settings will be available.

iframeUrl <url>

This setting allows integrating an external html page into the default details page, as an iframe. The usual replacement variables can be used within this URL:

$$ - ID, will be replaced by the name of an item or other string id depending upon the fields in the given track's type.
$T - database table name
$S - chromomosome name (scaffold name on scaffold assemblies)
$[ - left-most position of current viewing window (relative to zero)
$] - right-most position of current viewing window (relative to one)
${ - start location of clicked item (relative to zero)
$} - end location of clicked item (relative to one)
$s - chromosome name without chr prefix (or without scaffold_ or Scaffold_ prefix on scaffold assemblies)
$D - database name (e.g. "hg19")
$P - item name portion before first : in name
$p - item name portion after first : in name up to next colon
$taxId - NCBI Taxon ID of current organism (from hgCentral.dbDb)
$n - Scientific Name of current organism (from hgCentral.dbDb)

The URL can either be a full external URL or local to the web site.

In HTML, iframes cannot be resized easily, so the default static size is 1024 pixels. This can be changed with iframeOptions

Examples:

    iframeUrl https://www.ncbi.nlm.nih.gov/nuccore/$$
    iframeOptions height='600' width='1024'

iframeOptions <string>

When iframeUrl is used, this statement specifies a string that is inserted literally into the HTML <iframe> tag. It can include options needed for iframe formatting, like width, height, scrolling, etc.

If the statement is not present, the default is width='100%' height='1024'.

Note: dynamic resizing of iframes is not trivial, as they have to be resized with javascript, across domains. We recommend keeping the size static and to use scrollbars.

Example:

   iframeOptions width='800' height='800' scrolling='yes'

This example fixes the size to 800x800 pixels and activates scrollbars.

directUrl <url>

%s - item name
%s - chromosome name
%d - chromosome start position (relative to zero)
%d - chromosome end position (relative to one)
%s - track name
%s - database name

Example:

   directUrl http://mygenes.org/cgi-bin/geneView/%s

otherSpecies <otherSpecies>

The name of the other assembly in the pairwise alignment for this track.

Example:

   otherSpecies tweeter

The other species (other than the reference) in the alignment is the tweeter assembly in the same HAL file.

otherDb <otherDb>

Track types that show pairwise alignments often need to declare the other species/assembly included in the alignment. Types that use this setting include bed, chain, netAlign, psl and snake.

Example:

   otherDb mm10

This example sets the second assembly in the alignment to the mouse mm10 assembly.

otherTwoBitUrl <url/relativePath>

For pairwise alignment tracks this can specify where to find the query sequence This setting can be used in psl, bigPsl, chain, and bigChain tracks.

Example:

   otherTwoBitUrl https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.2bit

origAssembly <db>

NOT FOR HUBS.

The original assembly version for which the dataset was generated. Datasets generated by mapping to one genome assembly may prove useful enough to map to a more recent assembly. Ideally datasets will be regenerated to map to the new assemblies coordinates, but sometimes this is not practical or expedient. Therefore, the dataset may have its genome coordinates "lifted over" to the more recent assembly. In some cases this results in an inferior but nevertheless useful representation. Such datasets should have their original assembly defined with this setting.

Example:

   origAssembly hg18

pennantIcon <iconFile>/<text color> [html [tip]] 
[; <iconFile>/<text color> [html [tip]]]

Certain tracks can be visually flagged in the Browser menu by use of an icon or text label and a link to a description of the flags meaning. The icon is displayed next to the track's short label in the track groups section below the Browser image, and on the track's description and configuration pages. Multiple pennantIcons can be added on a single track by separating each entry with a semicolon ';'. This setting has three parts:

icon - Can be fully qualified URL (http, https, ftp) to an image file, or the name of an image in the Browser's images directory in the Browser source tree.
text - A single word label. Case is ignored; the label is displayed capitalized lower case.
color - An HTML color name to color the text label
html - A relative or full html path to a description document explaining the icon's meaning. This page displays when the user clicks on the icon.
tip - A "quoted string" tip that will be seen when the user's mouse pointer hovers over the icon.

Examples:

    pennantIcon 18.jpg ../goldenPath/help/liftOver.html "lifted from hg18"

    pennantIcon New red ../goldenPath/releaseLog.html "Released October 19, 2017"

    pennantIcon 19.jpg liftOver.html "lifted hg19"; p12 black http://genome.ucsc.edu/patches/ "annotations patch"

priority <float>

The priority is used to define the order of a track within its track group or data hub, as well as its default order within the Browser image. The order within the image can be dynamically changed by the user and will always depend upon which other tracks are currently visible. Typically the priority is set only for tracks that are on by default in order to move them ahead of other tracks. Prioritized tracks within a group or data hub are displayed in ascending priority order, followed by unprioritized tracks sorted alphabetically by short label. Tracks of the same priority within a group or hub are sorted by short label. Priority is a floating point number. Default: 0.

Example:

   priority 50

release <alpha/beta/public>[,beta/public]

NOT FOR HUBS.

This specifies the version of the Browser where the track will be displayed. It can contain any combination of the three values:

alpha - displayed on the alpha Browser (aka genome-test, hgwdev)
beta - displayed on the beta Browser (aka hgwbeta)
public - released on the public Browser (aka genome.ucsc.edu)

Default: alpha,beta,public (all three Browsers).

Example:

   release alpha,beta

table <tableName>

NOT FOR HUBS.

The track setting of most tracks is the same as the table name. However, in some cases it is desirable to reference the same table in more than one track. An example of this is showing a table as a single signal track and as part of a combination overlay track, as described later in this document. For data contained in MariaDB tables, this setting must be used if the track setting is not the name of the table.

Example:

    track mySecondTrack
    table myFirstTable

tableBrowser <off/on/noGenome> [table1 ...]

The Table Browser typically allows querying and downloading of some or all of the raw data for a track. The off value blocks Table Browser access to datasets with restrictions (for example, those with confidentiality or licensing limitations). The noGenome value allows queries within specific genomic regions, but not genome-wide. By naming additional tables in this setting, access to those tables can be denied as well.

Examples:

   tableBrowser off decipherRaw knownToDecipher

The table for this track, as well as the decipherRaw and knownToDecipher tables, are blocked from Table Browser access.

   tableBrowser noGenome omimAv omimAvRepl

Genome-wide queries are disabled for the track table as well as omimAv and omimAvRepl. Queries on genomic regions are permitted.

url <url>
urlLabel <label>
idInUrlSql <sql for id>

Many tracks allow an external link when an individual track data item is examined. Use this setting to put a link to an external URL on the details page. The url may include wildcards that will be substituted with values from the track data or other Browser variables:

$$ - ID, will be replaced by the name of an item or other string id depending upon the fields in the given track's type.
$T - database table name
$S - chromomosome name (scaffold name on scaffold assemblies)
$[ - left-most position of current viewing window (relative to zero)
$] - right-most position of current viewing window (relative to one)
${ - start location of clicked item (relative to zero)
$} - end location of clicked item (relative to one)
$s - chromosome name without chr prefix (or without scaffold_ or Scaffold_ prefix on scaffold assemblies)
$D - database name (e.g. "hg19")
$P - item name portion before first : in name
$p - item name portion after first : in name, up to next colon
$taxId - NCBI Taxon ID of current organism (from hgCentral.dbDb)
$n - Scientific Name of current organism (from hgCentral.dbDb)
$<fieldName> - For bigBed based tracks only (so excluding vcf, vcfPhasedTrio, bam/cram and hic), substitute the <fieldName> value from the bigBed.

The default prompt the user will see for this url is "outside link:". Use urlLabel to provide a more informative prompt.

For local (non-hub) tracks, an additional setting can be used to find an ID from another table based upon the item name or id from the track's table. The value found will replace the "$$" token in the url. Note that the format of this trackDb setting is a normal C language format so that the item will replace the "%s" token in the sql statement.

Example:

    url https://www.ncbi.nlm.nih.gov/htbin-post/Entrez/query?form=4&db=$n&term=$$&extra=$<field2>
    urlLabel NCBI Details:
    idInUrlSql select name from sibTxGraph where id=%s

url <url>
urlLabel <label>

$$ - ID, will be replaced by the name of an item or other string id depending upon the fields in the given track's type.
$T - database table name
$S - chromomosome name (scaffold name on scaffold assemblies)
$[ - left-most position of current viewing window (relative to zero)
$] - right-most position of current viewing window (relative to one)
${ - start location of clicked item (relative to zero)
$} - end location of clicked item (relative to one)
$s - chromosome name without chr prefix (or without scaffold_ or Scaffold_ prefix on scaffold assemblies)
$D - database name (e.g. "hg19")
$P - item name portion before first : in name
$p - item name portion after first : in name, up to next colon
$taxId - NCBI Taxon ID of current organism (from hgCentral.dbDb)
$n - Scientific Name of current organism (from hgCentral.dbDb)
$<fieldName> - For bigBed based tracks only (so excluding vcf, vcfPhasedTrio, bam/cram and hic), substitute the <fieldName> value from the bigBed for this item. Note the preceding '$' before the brackets.

The default prompt the user will see for this url is "outside link:". Use urlLabel to provide a more informative prompt.

Example:

    url https://www.ncbi.nlm.nih.gov/htbin-post/Entrez/query?form=4&db=$n&term=$$&extra=$<field2>
    urlLabel NCBI Details:

urls <fieldName1>="<url1>" <fieldName2>="<url2>" ...

This is similar to the url tag, but allows urls on fields that are not the "name" field. Use this statement if you need multiple linkouts on the details page or if your linkout is not based on the name field.

Put the identifiers for these links into extended bigBed fields as explained in example 3 of the bigBed documentation. The field names from your .as file are the field names referenced in this statement. The urls in this statement support the same wildcards as the url statement. Make sure to enclose the URLs in double quotes. The default label for the identifier is the field description in the .as file (all text after the # mark).

The field can contain multiple values, separated by a comma "," where multiple links will then be created on each item. For instance, a "pmid" field with an entry "11932250,34718705" would create two links.

If an entry of comma-separated values contains a "|" symbol, the part before the pipe symbol is used to replace the $$ wildcard and the part after it is used as the label, as opposed to the default label description in the .as file. This pipe substitution is similar to how Wikipedia markup encodes links. In the example below, a value for the field pmid of "11932250|W James Kent" would create a link with the URL https://www.ncbi.nlm.nih.gov/pubmed/11932250 and the label "W James Kent".

Example:

    urls pmid="https://www.ncbi.nlm.nih.gov/pubmed/$$" spId="http://www.uniprot.org/uniprot/$$"

skipEmptyFields on

If this setting is "on", the item details page will not show fields that have empty values. This can be useful when you have numerous extra fields but only few of them have a value.

skipFields <fieldName1>="<url1>" <fieldName2>="<url2>" ...

This setting can be used to suppress extra fields on the item details page. It can be useful if you do not want to show fields that are only used for mouseOvers or labels.

Example:

    skipFields mouseOver,labelField,hiddenField

sepFields fieldName1,fieldName2 ...

This setting changes the item details page and splits the table used for showing extra fields before any of the specified fields. It can be useful to visually separate extra fields into logical categories.

Example:

    sepFields pmid,spId

mouseOverField <fieldName1>

For bigBed files with more than 8 fields (not counting any extra bigBed fields), this adds mouse over text that are different from the "name" field of a bigBed file. If the field is empty then the mouse over will fallback to the name field.

To make this work, create a bigBed file with at least 8 columns and put the text for the mouse over into an extra bigBed field as explained in example 3 of the bigBed documentation. The field name from your .as file is the field name for this statement.

Example:

    mouseOverField comment

mouseOver <pattern>

For bigBed files with more than 8 fields (not counting any extra bigBed fields), this adds mouse over text from a pattern based on the values of fields in the file. The pattern is constructed with fieldnames from the .as file, preceded by the dollar sign ($), and can include arbitrary text between the fieldnames.

Example:

    mouseOver variant $name/$chrom:${chromStart} value $score

multiRegionsBedUrl <url/relativePath>

This setting causes a link to appear on the track configuration and items details pages to launch a multi-region custom regions view, where the regions are defined by the file supplied as an argument to the setting. It is useful for tracks with sparse annotations in the genome. The file must be BED format, and should contain a limited number (e.g. 2 to 10) regions of interest for the track. It can be BED 3 format (chrom, start, end), but may have any number of additional fields. When the link is clicked, a companion custom track is also created in order to highlight and title the displayed regions. If the name field (field 4) is present in the BED file, the name for each region will be displayed in the custom track.

Example

    multiRegionsBedUrl covidMuts.regions.bed

wgEncode on

NOT FOR HUBS.

This setting designates an ENCODE track. It activates the following special features:

Special thumbnail (NHGRI helix) is displayed before the track label in the brower track menu
ENCODE logo is displayed on track configuration page
'Downloads' and 'Preview' browser links shown in upper right portion of track configuration page
Track description includes a note about data on preview browser
'downloads' and 'metadata' links appear after 'View table:' on track details page

Example:

   wgEncode on

bed/bigBed: Item or region tracks

Some of the most common track types are those that highlight regions or items of varying size in a genome assembly. There are many variations to the "items" track, most of which are specified with a bed or bigBed format. These two formats are really a cluster of many formats all starting with three common fields (chromosome start end) and having optionally many more fields. For complete bed or bigBed format definitions please see the FAQ.

bigChain: Genome-wide Pairwise Alignments

The bigChain format describes a pairwise alignment that allow gaps in both sequences simultaneously, just as Chain files do, but bigChain files are compressed and indexed as bigBeds. bigChain files are created using the program bedToBigBed with a special AutoSQL file that defines the fields of the bigChain. The resulting bigChain files are in an indexed binary format. The main advantage of the bigChain files is that only portions of the files needed to display a particular region are transferred to UCSC. So for large data sets, bigChain is considerably faster than regular Chain files. The bigChain file remains on your web accessible server (http, https, or ftp), not on the UCSC server. Only the portion that is needed for the chromosomal position you are currently viewing is locally cached as a "sparse file". For complete bigChain format definitions please see the bigChain help page.

bigPsl: Pairwise Alignments

The bigPsl format stores alignments between two sequences, as PSL files do, but they are compressed and indexed as bigBeds. bigPsl files are created using the program bedToBigBed with a special AutoSQL file that defines the fields of the bigPsl. The resulting bigPsl files are in an indexed binary format. The main advantage of the bigPsl files is that only portions of the files needed to display a particular region are transferred to UCSC. So for large data sets, bigPsl is considerably faster than regular PSL files. The bigPsl file remains on your web accessible server (http, https, or ftp), not on the UCSC server. Only the portion that is needed for the chromosomal position you are currently viewing is locally cached as a "sparse file". For complete bigPsl format definitions please see the bigPsl help page.

bigGenePred: Gene Annotations

The bigGenePred format stores annotation items that are a linked collection of exons, much as BED files indexed as bigBeds do, but bigGenePred has additional information about the coding frames and other gene specific information in eight additional fields. bigGenePred files are created using the program bedToBigBed with a special AutoSQL file that defines the fields of the bigGenePred. The resulting bigBed files are in an indexed binary format. The main advantage of the bigBed files is that only portions of the files needed to display a particular region are transferred to UCSC. So for large data sets, bigBed is considerably faster than regular BED files. The bigBed file remains on your web accessible server (http, https, or ftp), not on the UCSC server. Only the portion that is needed for the chromosomal position you are currently viewing is locally cached as a "sparse file". For complete bigGenePred format definitions please see the bigGenePred help page.

bigNarrowPeak: Peaks

The bigNarrowPeak format stores peaks over a range with a single basepair central peak. bigNarrowPeak files are based on the bigBed format. The first six fields are the same as bed. The other four include three scores, and the base-pair offset of the central peak. bigNarrowPeak files are created using the program bedToBigBed with a special AutoSQL file that defines the fields of the bigNarrowPeak. The resulting bigBed files are in an indexed binary format. The main advantage of the bigBed files is that only portions of the files needed to display a particular region are transferred to UCSC. So for large data sets, bigBed is considerably faster than regular BED files. The bigBed file remains on your web accessible server (http, https, or ftp), not on the UCSC server. Only the portion that is needed for the chromosomal position you are currently viewing is locally cached as a "sparse file". For complete bigNarrowPeak format definitions please see the bigNarrowPeak help page.

bigMaf: Multiple Alignments

The bigMaf format stores multiple alignments in a format compatible with MAF files, which are then compressed and indexed as bigBeds. bigMaf files are created using the program bedToBigBed with a special AutoSQL file that defines the fields of the bigMaf. The resulting bigMaf files are in an indexed binary format. The main advantage of the bigMaf files is that only portions of the files needed to display a particular region are transferred to UCSC. So for large data sets, bigMaf is considerably faster than regular MAF files. The bigMaf file remains on your web accessible server (http, https, or ftp), not on the UCSC server. Only the portion that is needed for the chromosomal position you are currently viewing is locally cached as a "sparse file". For complete bigMaf format definitions please see the bigMaf help page.

bigBed: Item or region tracks

Some of the most common track types are those that highlight regions or items of varying size in a genome assembly. There are many variations to the "items" track, most of which can be represented with a bigBed format. This format is really a cluster of many formats all starting with three common fields (chromosome start end) and having optionally many more fields. For complete bigBed format definitions please see the bigBed help page.

halSnake -- Multiple Alignments in a HAL file

HAL is a file generated by the Cactus Progressive Alignment Suite, see Cactus github page.

type halSnake

If the bigDataUrl setting is included, the data at the location specified by that URL will be displayed. Otherwise, a database table with a single column fileName can specify the location of a local file or a URL. If the database table includes a column seqName, a different VCF file or URL can be specified for each assembly sequence.

Example can be found below.

type bed <3-12> [+/.]
type bigBed <3-12> [+/.]

Both bed and bigBed declare the number of standard bed fields in the data. Additional fields may follow these standard ones. If so, the type should end with a '+' (plus). Even if there are not additional non-standard fields, the additional parameter '.' (dot) is needed, if this track is meant to be configurable.

Examples can be found below.

type bigBed <3-12> [+/.]

Type bigBed declares the number of standard "bed" fields in the data. There may be additional fields following these standard ones. If so, the type should end with a '+' (plus). Even if there are no additional non-standard fields, the parameter '.' (dot) must be specified if this track is meant to be configurable.

Example:

  type bigBed 9 +

type bigPsl

There are no extra options that can appear on the type bigPsl line.

type bigChain

There are no extra options that can appear on the type bigChain line.

type bigNarrowPeak

There are no extra options that can appear on the type bigNarrowPeak line.

type bigGenePred

There are no extra options that can appear on the type bigGenePred line.

type bigMaf

There are no extra options that can appear on the type bigMaf line.

type bigBarChart

There are no extra options that can appear on the type bigBarChart line.

type bigLolly

There are no extra options that can appear on the type bigLolly line.

type bigInteract

There are no extra options that can appear on the type bigInteract line.

type hic

There are no extra options that can appear on the type hic line.

type bed5FloatScore
type bedRnaElements
type broadPeak
type coloredExon
type gvf
type ld2
type narrowPeak
type peptideMapping

Each of these is a specialized variation of the bed format. Their specialized definitions should be sought elsewhere. However, these item tracks share many of the same configuration options available to bed tracks.

An example can be found below.

bigDataUrl2 <url/relativePath>

This setting is for remote data file type tracks (e.g. bigWig) and is fully described in the "Common trackDb settings" portion of this document.

colorByStrand <red,green,blue> <red,green,blue>

To color items differently by the strand they align to, use the colorByStrand setting. The first color will be used for plus strand alignments and the second for the minus strand. This setting is incompatible with spectrum and all items on the same strand will have the same color, regardless of the item's score.

Example:

   colorByStrand 255,0,0 0,0,255

Plus strand alignments will be colored red, and minus strand alignments will be blue. This setting is incompatible with spectrum, and therefore all items on the same strand will have the same color, regardless of the item's score.




compareGenomeLinks <db[.table[.column]]=label>
            [db[.table[.column] =label …]
    NOT FOR HUBS
    Sometimes the
    features that a bed track highlights in one genome are also
    displayed in tracks of other genomes.  If an item of the same name
    exists in the bed tracks of two or more genomes, a bridge can be
    readily made between them through links on the item's detail page. To establish
    this association, the feature must have the same name in each genome, and the name 
    must be unique within the bed track of each genome.  The components of this
    setting are a genome assembly database, an optional table and column,  
    with a label for the link.  If the column parameter is omitted, it is
    assumed to be name. If the table is omitted, it
    is assumed to be the same as the current table.  Links to multiple
    genomes can be established with this setting, as each pair is
    joined by '=' and delimited by space.  Be sure to use
    '_' as a substitute for spaces in the labels.
    Example:
        compareGenomeLinks panTro2=Chimpanzee_(March_2006) rheMac2=Rhesus_(January_2006) \
                       mm9=Mouse_(July_2007) rn4=Rat_(November_2004) canFam2=Dog_(May_05) \
                       bosTau4=Cow_(October_2007)    
    In this example for
    the hg18 ENCODE bi-directional promoter track, each genome has a
    track of the same name, and the names are unique within each track.
    However, a named bi-directional promoter will not be found in
    every genome; therefore, only links to genomes where the name is actually
    found will be displayed.
    




denseCoverage <maxVal>
    bigBed specific
    Type bigBed tracks
    in dense mode do a density plot based on maximum coverage seen at
    each pixel.  The maxVal corresponds to the count at which the plot
    reaches maximum darkness.  If maxVal is 0 then this will be
    calculated from the data itself.
    Example:
       denseCoverage 100



labelOnFeature <on/off>
    Usually, labels (the BED name field) are drawn next to the
    features. This statement tries to draw the feature 
    label over the exon blocks. The effect depends on the size of the feature
    on the screen, which in turn depends on the zoom level. If there is not enough
    space for 4 characters, no label is drawn at all. If there is more space,
    the label is drawn with a contrasting color onto the exon-like blocks. 
    If they are too short for the text, it is trimmed to fit into the available space
    and the suffix "..." appended. Note that features should not have too
    long thin (UTR) regions, as the text might be hard to read
    in these parts.

    To keep the text readable, the arrows that indicate the strand are shown over
    introns, but suppressed on blocks, so the statement should be used
    for tracks where strand is not of primary importance, not defined in the
    BED strand field or deactivated
    with exonArrows.  
    Example:
       labelOnFeature on



exonArrows <on/off>
    On tracks that show
    exons or blocks within features, exon arrows allow the user to jump to
    the next exon or block outside the image. Exon arrows are typically shown by default
    in these types of tracks, with the exception of tracks in the Regulation group. 
    The arrows can be explicitly shown or hidden using this setting.
    
    Example:
       exonArrows off



exonNumbers <on/off>
    A mouseover that shows the exon and intron numbers 
    can be explicitly shown or hidden using this setting.
    The default is "on" for the track types genePred and bigGenePred.
    Example:
       exonNumbers off
    The text can be set with the options "exonText" and "intronText". It defaults to "exon" and "intron", respectively.




    <column>Filter <low>[:<high>]

    scoreFilter <low>[:<high>]

    pValueFilter

    qValueFilter

    signalFilter

    <column>FilterLimits <low>[:<high>]

    <column>FilterByRange <off/on>
    
    A number of
    numerical filters are available for bed tracks.  These are
    conveniently named by the field that is filtered on.  The most
    common numerical filter is based on the standard bed field
    score, and is thus controlled by the scoreFilter
    setting.  Other examples are pValueFilter, qValueFilter and
    signalFilter, which are filters on non-standard bed fields defined
    in the broadPeak and narrowPeak formats.  These numerical filter
    settings should include the default value.  If the numeric field
    is floating point, the default should contain at least one decimal
    place.
    
    By default the range
    of values for a numeric filter is 0 to 1000.  However, you
    can explicitly set the upper and lower limits of the filter by
    setting <column>FilterLimits.
    
    The numeric filters
    will exclude items that fall below the setting. That is, a
    scoreFilter of 800 will  exclude all items with a score below 800.
    You can also filter for values within a range, by including the
    <column>FilterByRange setting.  For example, a 
    scoreFilter range of
    800-900 will include only items with scores at or above 800 and
    below 900.
    Note: multiple
    filters of different fields are allowed.
    Examples:
       scoreFilter 100
    In this example, the standard bed
    field score, which is an integer, will be used to filter items
    in the track.  By default, items with scores below 100 will be
    excluded.  Also by default the limits of the scoreFilter are
    0-1000.
        pValueFilter 3.0:15.0
    pValueFilterLimits 0.0:15.0
    pValueFilterByRange on    
    The non-standard bed field pValue, which
    is floating-point, will be filtered by range.  The expected data
    range is 0.0 to 15.0, and by default only items with pValues within the 3.0 to 15.0
    range will be displayed.




    scoreFilter <low>[:<high>]

    scoreFilterLimits <low>[:<high>]

    
    Type bigBed tracks can be filtered on the standard bed field
    score.  This numerical filter is requested by the 
    scoreFilter setting, which should include the default value.  
    
    By default the range
    of values for a score filter is from 0 to 1000.  However, you
    can explicitly set the upper and lower limit of the filter by
    setting scoreFilterLimits.
    
    The score filter will exclude items that fall below the setting. That is, a
    scoreFilter of 800 will exclude all items with a score below 800.
    Since the introduction of scoreFilter more powerful filter.<fieldName>
    options exist where the score column can be filtered with different syntax.
    In such a way scoreFilter 400 and scoreFilterLimits 0:1000
    can be replaced with filter.score 400 and filterByRange.score 0:1000.
    The advantage of switching to the filter.<fieldName> approach is that filters
    can also be added on additional bigBed <fieldNames> such as filterText.disease
    or filterValues.cellType where bigBeds defined with a disease or cellType column can
    be filtered. See filter.<fieldName> for more information and examples. 
    Example:
        scoreFilter 300
    scoreFilterLimits 200:1000
    The standard bed
    field of score, which is an integer will be used to filter items
    in the track.  By default, items with scores below 300 will be
    excluded.  The filter cannot be set to less than 200 or more than 1000..



filterBy  <field1:title=[+]opt1a...>
                            [field2:title=[+]opt2a...]
    
    NOT FOR HUBS.  Not yet supported by bigBeds
    Another method of
    filtering items relies upon discrete values.  One or more fields
    such as name or score may contain a limited number
    of discrete values that can be filtered on. These discrete values will be
    displayed in a dropdown list from which the user can choose one or
    more options.  While the maximum number of options in the list is
    not limited, displaying too many options can be confusing for the user.
    
    Setting complexities:
    
     Because filters for different fields are delimited by whitespace, any
    whitespace in titles and labels should be replaced by the '_'
    (underscore) character.
     Each field/option pair is joined by '=' (equal sign).
     The field portion
    can have a title that is delimited from the field name by ': (colon)'.
     A single field
    filter will have multiple options delimited by commas.
     If the options are
    a 1-based index (1,2,3...) then the option list can be preceded
    with a '+' (plus sign) and the options themselves are only labels.
     Otherwise, each
    option will be a value and optional label delimited by '|' (vertical bar).
    Note that if one option has a label then all options of that filter
    must have a label.
    Finally,
    options may have CSS style wrapped in {curly} brackets and
    appended to the end.
    
    Because of this
    complexity, please remember to use the '\' continuation line to
    ensure the setting is readable:  
    
        filterBy {field1}[:{Title1}]=[+]\
             option1a[|label1a[{style1a}]],\
             option1b[|label1b[{style1b}]],... \
             [{field2}[:{Title2}]=[+]\
             option2a[|label2a[{style2a}]],,...]    
    It is probable
    that this setting will be redefined at some point, given that it
    is very complicated. However, this current format will
    be supported until entirely replaced.


    
        Secret tricks:
        
        Avoid the use of the delimiter chars  ,|:={} in titles and
        labels.  (These characters can be included via HTML codes.)  
        Spaces can be included by using the '_' character.
        The option labels
        can be in color or have other CSS style attributes. Append the style 
        enclosed in curly brackets and containing no spaces. For example:
        Pull_Over{color:#AA0000;text-decoration:blink;}.
        If one option has CSS style, then all options of that
        filter must include a style definition.
        The filterBy option is implemented in the code using an SQL where clause.
        For instance, filtering on the name field for "Fred" and
        "Ethyl" would result in an SQL where clause of
        "where name in ('Fred','Ethyl')".  In type genePred
        tracks, this knowledge is used to define filters on fields in a separate table!
        This is done by defining the field as {otherTableName}.{fieldName}.
        
    
    The best way to
    understand this setting is with an example.  This is an operational
    example in the hg19 "Open Chrom Synth" track.
    Example:
        filterBy color:Validation_Level=\
             0|Validated_(OC_1){color:#000000},\
             255|Open_Chromatin_(OC_2-3){color:#0000FF},\
             39168|DNase_low_(OC_2){color:#009900},\
             10027008|FAIRE_low_(OC_3){color:#990000},\
             16711935|ChIP-seq_(OC_4){color:#FF00FF} \
             ocCode:OC_Code=+\
             One&#58;_Validated_(all),\
             Two&#58;_DNase_(all),\
             Three&#58;_FAIRE_(all),\
             Four&#58;_ChIP_(all)    
    This setting sets up
    two filters, one on the field "color" and a second for the
    "ocCode" field.  The color filter is given the title "Validation
    Level".  The second option has a value of "255" and a label
    of "Open Chromatin (OC 2-3)".  Note that it will appear
    as blue in the list due to the {color:#0000FF} style definition.
    Also notice that all options for this color field have a style
    defined, even though the first option is black and would be so by
    default. In this example, the only
    whitespace within the setting value section immediately precedes the second filter
    definition.  The second filter, "ocCode", is titled by the
    inscrutable "OC Code".  It is a numeric index filter
    (as declared by the '+').  The value of the second option is 2 and
    only the label gets defined as "Two: Dnase (all)".  Note
    that the colon in the label is an HTML code.
    
    The filterBy setting is very powerful. We recommend that you experiment with the
    settings to determine which work best for your case.
    




    filter.<fieldName> <default integer>

    filterByRange.<fieldName> <off/on>

    filterLimits.<fieldName> <low>[:<high>]

    
    There are a number of different filters available for bigBed data. See the 
    Filters Quick Start guide for
    more info. Note: for configurable features, like filters, an additional period
    "." or plus "+" is required in the type declaration,
    for instance type bigBed 5 . or type bigBed 9 +.
     filter.<fieldName>  is used for numerical data. It requires
    a default value to be passed. A value of 0 (or the lowest value present in the dataset) 
    can be used to enable numerical filtering, but filter nothing by default.
    By default, the range of values for filter.<fieldName> is 0 to 1000. 
    However, you can explicitly set the upper and lower limits of the filter with 
    filterLimits.<fieldName>.
    The numeric filters will exclude items that fall below the setting. That is, a
    filter.<fieldName> of 800 will exclude all items with a score 
    below 800. You can also filter values within a range by including the 
    filterByRange.<fieldName> setting. For example, 
    filter.<fieldName> 800:900 will include only items with scores at 
    or above 800 and below 900. It is recommended that filterByRange.<fieldName> 
    be used in combination with filterLimits.<fieldName> 
    to set limit boundaries.
    The filter label will be the description of the field as specified by the autoSql (.as) file.
    This label can be customized with the 
    filterLabel.<fieldName> parameter.
    See the bigBed help page and example 3 for more information about creating
    unique .as files for bigBed data.
    Notes:

    filter.<fieldName> can be used multiple times with different 
    columns
    Both integers and decimals (floats) are supported
    Any column/field values that start with non-numerical characters will be treated 
    as zeros
    Column/fieldName values that start with a number followed by non-numerical characters 
    will be treated as only the number; the non-numerical characters (and any numbers 
    that follow them) will be ignored (see example below)
    If a column/fieldName contains negative values, be sure to specify a default value
    at or below the lowest negative value in order to avoid actively filtering items by
    default (unless that is the intended behavior)
    In order for filters to work, the track must be type bigBed N + or
    type bigBed N . a "+" (for bigBed+ tracks) or a 
    "." (for non-extended bigBed tracks) is required
    
Filters are not supported in bed3 or bed4 files, even bed 3+x. The file must be
    at least a bed5
    By default, all bed tracks that are at least bed5 will have a score filter. 
    Enabling any of the filter*.<fieldName> filter settings will disable 
    that default filter


    Examples:
        filter.score 0
    In this example, filtering is being enabled for the field score. We are
    passing a default value of 0, which is usually a safe default value to pass as most score
    values contain only positive numbers. Note, however, that any negative values would be 
    filtered out by default in this example.
        filter.score 300
    In this second example, we are enabling filtering on the same field score, 
    however, we are passing the integer 300. This means that when the data is loaded, items with 
    scores below 300 will be excluded by default. This value can then be modified in the track 
    description page.
        filter.signal 300:400
    filterByRange.signal on
    filterLimits.signal 200:500
    In this example, we are enabling numerical filtering on the field signal. 
    filterByRange.<fieldName> is also being enabled, allowing for filtering 
    between interval values, this also allows us to pass a range of values to the 
    filter.<fieldName> parameter. In this case, by default only values between
    300 and 400 are being displayed. Lastly, the filter limits are being modified to accept values 
    between 200 and 500 as opposed to the default 0 to 1000.
        filter.confidenceScore 6
    Example values in the confidenceScore field/column:
       5
    6 (Uncertain)
    Unknown
    7.0	
    This example applies filter.<fieldName> to values in the
    field named confidenceScore containing some non-numerical values.
    If items with the four values above were filtered with a minimum value of 6:
    

    5 - item would be removed as it is less than the filter value

    6 (Uncertain) - item should show up, as it would be interpreted as
    "6"

    Unknown - item would be removed as it would be interpreted as 0

    7.0 - item would appear as decimals are supported




    filterText.<fieldName> <default search string>

    filterType.<fieldName> <wildcard/regexp>

    
    There are a number of different filters available for bigBed data. See the     
    Filters Quick Start guide for
    more info. Note: for configurable features, like filters, an additional period
    "." or plus "+" is required in the type declaration,
    for instance type bigBed 5 . or type bigBed 9 +.
    filterText.<fieldName> is used to enable text searching in the 
    specified fieldName. It requires a default search string to be passed. An asterisk/wildcard (*)
    can be used to enable text searching, but pass no default value. If a word or string is
    passed, items matching the string will be filtered by default. See examples below for 
    details.
    filterText.<fieldName> will enable two kinds of searching, wildcard and
    regexp. By default, the wildcard option is enabled. This means that a search term with 
    a wildcard (*) item on either end will match any number of additional characters before
    and/or after the search term. The regexp option allows for searching with regular 
    expression rules. For instance, with wildcard changed to a regexp type of search, putting in
    .*A\|B.* will match any items with an A or B in it, while .*[0-9] will
    match any item ending in a number. The optional settings filterType.<fieldName>
    may be added to switch the default from wildcard to regexp.
    The filter label will be the description of the field as specified by the autoSql (.as) file.
    This label can be customized with the filterLabel.<fieldName> parameter.
    See the bigBed help page and example 3 for more information about creating 
    unique .as files for bigBed data.
    Notes:

    filterText.<fieldName> will treat all fields as strings. That is to say,
    it can be enabled on entirely numerical fields, such as chromStart, if one is 
    looking to filter numerical values as text
    In order for filters to work, the track must be type bigBed N + or
    type type bigBed N . a "+" (for bigBed+ tracks) or a
    "." (for non-extended bigBed tracks) is required
    
Filters are not supported in bed3 or bed4 files, even bed 3+x. The file must be
    at least a bed5
    By default, all bed tracks that are at least bed5 will have a score filter. Enabling 
    any of the filter*.<fieldName> filter settings will disable 
    that default filter

    Examples:
        filterText.geneName *BRCA*
    In this example, we are applying a default filter on the field geneName 
    so that only items with BRCA in the geneName are visible. By default, this is 
    a wildcard search of *BRCA* which is equivelant to
    a regexp search .*BRCA.*. The filter term can be freely changed in the track 
    setting page allowing users to filter on other values in the geneName field.
        filterText.geneName *
    This example is enabling filtering on the same field as above, geneName,
    however, it is not declaring a default search parameter. This is done by passing only an
    asterisk/wildcard (*). This means that the search box 
    will be present but no geneName items will be filtered out of the data 
    unless the user specifies a value.
        filterText.geneName \.1$
    filterType.geneName regexp
    
    This example once again enables filtering on the same field, however, it is declaring
    regexp as the filter type and passing a regular expression to be applied by default. 
    In this case, we are targeting all geneName items that are version 1.




    filterValues.<fieldName> <value1,value2,value3...>

    filterValuesDefault.<fieldName> <value1,value2,value3...>

    filterType.<fieldName> <single/singleList/multiple/multipleListOr/multipleListAnd/multipleListOnlyOr/multipleListOnlyAnd>

    
    There are a number of different filters available for bigBed data. See the     
    Filters Quick Start guide for
    more info. Note: for configurable features, like filters, an additional period
    "." or plus "+" is required in the type declaration,
    for instance type bigBed 5 . or type bigBed 9 +.
    filterValues.<fieldName> is used to enable filtering by 
    specified values within a field. It can be used on fields that can contain
    one text value or a list of comma-separated values of text, like "classA,classB".
    Usually these are category names.
    The option requires at least one value to filter on.
    Every individual possible value that can ever occur in the field must be
    passed in a comma separated list. You will then be able to select those
    values as categories, choosing to display only items that
    belong to one, any, or at least one of the selected values. By default, the user
    can select multiple values from this list and the filter lets pass any features
    with at least one of these values (multiple).
    In order to choose the default selection behavior, the optional parameter
    filterType.<fieldName> may be used. If this parameter is not passed,
    by default the selection will be set to "one or more match" which is the same
    as having filterType.fieldName multiple. If the user should
    only be able to select a single value, 
    single can be passed instead. Another option,
    multipleListAnd, means that the user can select multiple categories,
    but the filter will let pass only features where all of these categories are present.
    
    
    Both single and multiple have "list" options. These options
    split the bigBed field values by commas, meaning that they should only be used when items can
    contain multiple values at once in the desired filter field. For example, if my data is 
    classifying variants, and they can only be a SNV, insertion, or deletion, I will want to
    use single and multiple. However, if instead the filter will be
    on a field classifying functional impact, there can be many values for each item. For 
    example, variant rs11541299, which is both a synonymous variant and a 
    coding sequence variant. In this case, I would want to use one of the "list"
    options. Most simply singleList or multipleList, or one of
    the additional varieties of multipleList depending on the desired options.
    
    
    multipleListOr and multipleListAnd both still let the user
    override the type of combination manually in the user interface with a radio button. 
    If you specify multipleListOnlyOr or multipleListOnlyAnd
    then the radiobutton is suppressed and the user cannot choose between the options
    anymore. This can be used in cases where by the nature of the field, it
    makes little sense to offer the OR or AND search. 
    
    You can also choose which values to have selected by default using the
    filterValuesDefault.<fieldName> parameter. It can take a comma separated
    list just like filterValues.<fieldName>, and any items included will be
    automatically selected. Not that the values need to be present in both settings.  
    The labels in the menu shown to the user can be configured to display a different name/label
    than the one present in the bigBed field. This can be helpful when the data values are
    written in short form, but you want a longer more descriptive name to show up in the UI.
    The format for this substitution is as follows:
    filterValues.fieldName fieldValue1|alternativeName1,fieldValue2|alternativeName2...
    E.g. if the value in the bigBed field is AML, a setting 
    like Acute Myeloid Leukemia|AML will show Acute Myeloid Leukemia 
    in the user interface but will lead to the value AML being searched in the bigBed 
    field. This can reduce the size of the bigBed file a lot. See example below for more information.
    Notes:

    Currently, all values must be stated individually
    Value names must match exactly
    By default, all bed tracks that are at least bed5 will have a score filter. Enabling any 
    of the filter*.<fieldName> filter settings will disable that default 
    filter
    In order for filters to work, the track must be type bigBed N + or
    type type bigBed N . a "+" (for bigBed+ tracks) or a
    "." (for non-extended bigBed tracks) is required
    
Filters are not supported in bed3 or bed4 files, even bed 3+x. The file must be
    at least a bed5
    There should not be any white spaces between declared items after commas, e.x.
    "itemOne,itemTwo,itemThree"
    The default label can be customized with the filterLabel.<fieldName> parameter
    When using filter values in a field that incudes commas, an additional comma
    can be used to escape it. E.x. "fieldOne,fieldTwo,,fieldTwo,fieldThree"
    

    Examples:
        filterValues.OddEven Odd,Even
    In this simple example, we are applying filterValues.<fieldName>
    to the OddEven field, which designates either "Even" 
    or "Odd". We can then filter the data using the OddEven 
    field with a drop-down menu displayed on the track controls page to just evens or odds. 
    As there is no filterType, the user can also show both evens and odds at the same time.
        filterValues.OddEven Odd,Even
    filterType.OddEven singleList
    In this follow up example, we are passing the filterType.fieldName singleList
    parameter, which means that only one item in the OddEven field can be 
    chosen, in this case "Odd" or "Even". This removes the default that 
    allows multiple selections.
        filterValues.OddEven Odd,Even
    filterType.OddEven singleList
    filterValuesDefault.OddEven Odd
    In this third example, we have added the filterValuesDefault.fieldName
    parameter as well. Now the default filter when the hub is loaded will have the Odd value
    preselected.
        filterValues.annotationType DNA-BR,AS,BS,BSi
    In this example the filter is being applied to multiple values in the 
    annotationType field. We can then select from these values in the 
    annotationType field with a drop-down menu displayed on the track settings page, 
    and display only items that match our selections. The selection choices will let us match
    one, all, or any combination of the supplied values.
        filterValues.annotationType DNA-BR|DNA-binding region,AS|active site,BS|beta strand,BSi|binding site
    In this follow up to the previous question, we have changed the name of the items that
    show up in the drop down menu to be more descriptive than the dense file format values. This means
    that if we wanted to only see items with annotationType of 
    DNA-BR, we would select DNA-binding region from the interface menu.



filterLabel.<fieldName> <label>
    When a user clicks on a track item in the Browser image,	
    the item detail page is shown. This setting specifies an
    alternate label for the filter on that page. Without this
    setting, the label will be the description of the field as 
    specified by the autoSql (.as) file. Some of the parameters modified by
    this are:
    
filter.<fieldName>
    filterText.<fieldName>
    filterValues.<fieldName>

    Example:
        filterValues.strand +,-
    filterLabel.strand Strand (Orientation)
    In this example, we have a standard "strand" BED field with the default 
    description "+ or - for strand". We have enabled a filter and simplified
    the label to just "Strand (Orientation)".



itemRgb on
    In bed formats supporting 
    at least 9 standard bed fields, this setting can be used to activate
    item coloring using the value in the ninth field, itemRgb. The
    value of the  item field must be an R,G,B triplet.  When loaded
    into a table, this field appears as an integer with the RGB values
    in specific bits of the integer. To observe this field, specify the type as,
     type bigBed 9, or, type bigBed 9+, for additional
    non-standard columns, 
    in the trackDb stanza for the bigBed file.
    Note that the display of color is affected by the maxItems option.
    When the track is zoomed to the point that the number of items to display
    exceeds maxItems, the track is forced into dense mode and the items
    are drawn from the bigBed summary in the default track color rather than using
    the itemRgb column.
  
    Example:
       itemRgb on



maxItems <integer>
    Maximum number of items to display individually in full mode.  When the maximum is
    exceeded, the excess items are drawn on top of one another on the last line.
    In packed mode this refers to the number of lines rather than number of items.
    Default: 250. For type bigBed tracks, this setting can never 
    be larger than than 100,000.
    Example:
    
       maxItems 25


maxWindowCoverage <integer>
    When too many individual bed items might be shown in the Browser image
    (such as might occur when a large region of a chromosome is viewed),
    maxWindowCoverage will switch the track into density coverage plot when
    the window contains more than the specified number of bases.
    Example:
       maxWindowCoverage 10000000

Browser images that show more than 10,000,000 bases will result in the track data being displayed as a density coverage graph.

maxWindowToDraw <integer>

When too many individual bed items might be shown in the Browser image (such as might occur when a large region of a chromosome is viewed), maxWindowToDraw will trigger a choice to display a message asking users to zoom in to a smaller region.

Depending on the current visibility of the bed track and which other tracks are being shown concurrently, the Browser may automatically reduce the display to pack or dense mode in some cases. The maxWindowToDraw setting allows you to force users to zoom in as an overriding message will block out the data display. Unlike the maxItems setting, which controls the display of vertical space and forces a display to dense when the maximum number of items is exceeded, the maxWindowToDraw setting dictates the number of bases to be displayed in a window before the track is obscured with a message explaining the requirement for zooming-in. Even without this setting, there are browser operations that will ultimately prevent too many items from being displayed by forcing a visualized summary in dense mode as noted.

Example:

   maxWindowToDraw 10000000

Browser images that show more than 10,000,000 bases will result in the track data being obscured with a note across the genomic range stating the message zoom in to <= 10,000,000 bases to view items.

minGrayLevel <1-9>

When a bed track contains the standard field score, and when that score is used to present items in gray or color scale (see spectrum), this setting specifies the lightest shade to be used. This prevents the lowest scores from being displayed in too light of a color to easily view. Set the value in the range 1 - 9, lightest to darkest.

Example:

   minGrayLevel   4

This sets the lowest scores to slightly less than medium gray, while the highest scores appear black.

noScoreFilter on

By default, bed tracks with 5 or more standard bed fields that contain either a '.' or a '+' in the type setting will be filterable on score; that is, they will have an assumed setting of "scoreFilter 0". To turn this old-style default off, include the "noScoreFilter" setting.

Example:

    type bigBed 6 +
    noScoreFilter on

spectrum on
scoreMax <integer>
scoreMin <integer>

Replaces useScore.

If your track is a bed 5 or greater, then the standard bed score field exists. This score, which is expected to vary from 0-1000, can be used to control the shading of bed items drawn in the Browser image. To activate this feature, set spectrum on. Lower scores will be shaded in light gray by default, while higher scores will trend towards black. This can be modified in a number of ways:

minGrayLevel can be used to set the level of the lightest shade
scoreMin and scoreMax can be used to define the lower and upper limits of the range that will receive graded shading

Note: The file type must be type bigBed x where x is at least bigBed 5. If only type bigBed is used, the setting will not work as it is assumed to be a bigBed 3.

Example:

    spectrum on
    scoreMin 700
    scoreMax 900

In this example, the track description will be displayed in blue, but the track will remain a gray scale. Items with scores less than or equal to 700 will be shown in very light gray, those with scores between 700 and 900 will display in increasingly darker shades of gray, and items with scores greater than or equal to 900 above will display in black.

searchIndex <str>

Specifies the list of field names on which a index has been made. When a user enters a string in the position search box of the browser, this index will be searched to find that name, and if the string is in the index, the user will either be navigated to that position in the browser, or if there are more than one matches of that string, will be give a list of the positions to choose from. See HERE for instructions on how to build an index for a bigBed file. The searchIndex setting requires the input BED data to be case-senstive sorted (sort -k1,1 -k2,2n), where newer versions of the tool bedToBigBed (available here) are enhanced to catch improper input.

Example:

   searchIndex name

searchTrix <url/relativePath>

Specifies the URL to a TRIX file that maps free text to a set of indices that are assumed to have indicies in the associated bigBed file. See here for instructions on how to build a TRIX file and a Searchable Track Hub Quick Start Guide here.

Example:

   searchTrix url or relative path

thickDrawItem <off/on>

In bed tracks that have 8 or more standard bed fields, portions of items in tracks such as gene models can be drawn thicker to differentiate exon regions from introns. When data is displayed at different scales, the items and the thick portions of the items should scale proportionally. However, it may be more important to see the existence of the thick regions than it is to attempt to maintain the proportion. By setting thickDrawItem on, the thick display regions of items are always drawn at a minimum of 3 pixels, even when zoomed out greatly.

Example:

   thickDrawItem on

bedFilter on

FOR BEDS ONLY

Activating this setting provides the bed filter type controls that allow you to filter bed items by name with wildcard matching.

Example:

   bedFilter  on

The bed track will be be filterable by the bed item names.

refUrl <url>

See CRAM track format page for a description of how to use this setting.

bedNameLabel <label>

When a user clicks on a bed track item in the Browser image, the item detail page is shown. This setting specifies an alternate label for the item name on that page. Without this setting, the label will be "Item:".

Example:

   bedNameLabel Gene Id

scoreLabel <label>

When a user clicks on a track item in the Browser image, the item detail page is shown. This setting specifies an alternate label for the score on that page. Without this setting, the label will be "Score:".

Example:

   scoreLabel Log of binding Score * 1000

maxLimit <#>

The upper limit of the data range in a track is specified with this setting.

Example:

   maxLimit 5000

mergeSpannedItems <on/off>

Allows merging all track items that extend beyond both sides of the current viewing window into one bed item in the display. The presence of this setting permits the display to offer this collapsed viewing option, while the on or off denotes what view should be shown by default.

The display can be enabled/disabled by the user either on the normal track configuration page, or via selection from the right-click menu. If the track is a bigBed 9 (+), then the merged item will be shaded as the average of all the merged items.

Example:

   mergeSpannedItems on

linkIdInName on

This setting changes the meaning of the bed name field to "identifier description". If it is activated, the browser does not show the first word of the BED item name, but uses this first word for linking out to the item detail page. This allows putting both an identifier, like a gene ID, and its human-readable description into the BED item name field, separated by a space.

Example:

   linkIdInName on

A BED name field of "9005 PITX2" will be shown "PITX2" on the genome browser, but when the user clicks on it, the URL will be built only from the first word, by default cgi-bin/hgc?i=9005&(...). The URL can be changed with directUrl, where %s is replaced by the identifier.

bigBed files are often created using the UCSC bedToBigBed program. By default, this program expects only a single word for BED item names. To tell the program to accept multiple words separated by spaces (required for this track setting), you will need to use the -tab option for bedToBigBed. This tells the program that that tab characters are used instead of spaces to separate fields of the BED file. Please note that this option will only work if tab characters are used as the field separator throughout your BED file. More information on creating bigBed files is available here.

baseColorUseSequence  <extFile {seqTable} /
                  hgPcrResult / lfExtra / nameIsSequence / seq1Seq2 / ss / 2bit >

Specifies where item sequence can be found (if any) so that item sequence, or differences from genomic sequence, can be drawn when viewing a sufficiently small region.

If extFile is specified, two additional parameters are required, the name of the seq table followed by the name of the extFile table to use in looking up the sequence. These tables are loaded by hgLoadSeq.
If hgPcrResult is specified then a PCR result is used.
If lfExtra is specified then the sequence of an item is found in the last column of the table or remote file.
If nameIsSequence is specified then the 4th column (name or sequence) contains the sequence. (see hg/lib/encode/tagAlign.as)
If seq1Seq2 is specified then the 7th & 8th columns (seq1 and seq2) contain the left and right pairs of the sequence. (see hg/lib/encode/pairedTagAlign.as)
If ss is specified then a user-provided blat sequence is looked for.
If 2bit is specified then looks for sequence in the file specified by the otherTwoBitUrl tag.

baseColorUseCds <given/table <table>>

Specifies where coding sequence (CDS) coordinates can be found (if any) so that codons can be drawn when viewing a sufficiently small region. If table is specified, an additional parameter of a table name, in cdsSpec format, is required.

baseColorDefault
                    <diffBases/diffCodons/itemBases/itemCodons/genomicCodons>

Specifies the default drawing mode. The itemBases, itemCodons, diffBases and diffCodons options are applicable only if the track has sequence, as specified by the baseColorUseSequence setting. The genomicCodons, itemCodons and diffCodons are applicable only if the track has CDS info, as specified by the baseColorUseCds setting.

baseColorTickColor <lighterShade/contrastingColor>

NOT FOR HUBS. Not yet supported by bigBeds

Choose a contrastingColor (this is often white) or lighterShade of color. This should be the same color as would be chosen for the base text if the user were zoomed in to base level.

showDiffBasesAllScales on

Show base differences for all zoom levels.

showDiffBasesMaxZoom <basesPerPixel>

Show annotations highlighting base or codon differences only if current zoom level does not exceed basesPerPixel (a float). showDiffBasesAllScales should also be set to make this useful.

showCdsAllScales on

Show CDS for PSL tracks at all zoom levels.

showCdsMaxZoom <basesPerPixel>

Use this setting (a float) to specify the maximum zoom-out allowed for displaying the CDS for psl tracks. In conjunction with this setting, showCdsAllScales must be set on and showDiffBasesMaxZoom should be set to a value not more than showCdsMaxZoom to make this display configuration useful.

Examples:

    baseColorDefault genomicCodons
    baseColorUseCds given
    showDiffBasesMaxZoom 10000.0
    showCdsMaxZoom 10000.0
    baseColorUseCds table hgFixed.transMapGeneUcscGenes
    baseColorUseSequence lfExtra
    baseColorDefault diffCodons
    baseColorTickColor lighterShade
    showDiffBasesAllScales .
    showCdsAllScales .

exonArrowsDense <off/on>

On tracks that show exons or blocks within items, exon arrows allow the user to jump to the next exon/block outside the image. Use this setting to display exon arrows even when the track is in dense mode.

itemDetailsHtmlTable <table>

NOT FOR HUBS. Supplemental table must be in local database.

Use this setting to specify a table, indexed by item name, that contains an optional HTML fragment to display on the details page for this item. The expected columns in the table are "name" and "html".

Example:

   itemDetailsHtmlTable pseudoGeneDetails

itemImagePath <path> <suffix>
itemBigImagePath <path> <suffix>

Items can be associated with images and the images can be made visible with these two settings. The itemImagepath specifies a URL path to a directory with image files named in the format {name}.{suffix}. The name is retrieved from the table or remote data file. This image will be displayed on the item detaiIs page. If itemBigImagePath is also supplied, then a link to a larger image will be provided. If the path provided is local to the browser then the path should be relative.

Example:

    itemImagePath images/myTrackImages png
    itemBigImagePath http://bigImages.com/myTrackImages jpg

When the user clicks on a item named fred, then the item details page will show the image images/myTrackImages/fred.png and will also provide a link to a larger image at http://bigImages.com/myTrackImages/fred.jpg.

mafTrack <trackName>

NOT FOR HUBS

By specifying a multiple alignments track, the item details page will illustrate the differences for that item across a number of species.

Example:

   mafTrack multiz46way

nextExonText <str>
prevExonText <str>

For tracks that offer multiple block items such as gene models, the next/previous exon arrows are usually displayed by default in the Browser. The functionality of these tiny arrows is described by mouse-over "tool tips" that default to "Next Exon" and "Prev Exon". If the blocks do not represent exons, you can adjust the tool tip text to the appropriate information with these two settings.

Example:

    nextExonText "Next Match"
    prevExonText "Previous Match"

showTopScorers #

Use this setting to show a list of some number of top-scoring items in a region of the genome, when looking at an individual item in the item details page. The region will cover the current browser window coordinates. Currently this setting is not configurable.

Example:

   showTopScorers 20

Examples of item base types

    type bed 3

The simplest bed format, with nothing more than a chromosome and the start and stop coordinates for each bed item. There is nothing to configure.

    type bed 6 +
    colorByStrand 255,0,0 0,0,255
      ...

    type bigBed 6 +
    colorByStrand 255,0,0 0,0,255
      ...

The type setting for a bed and a bigBed are nearly identical. Here, both type settings specify a track with the first 6 standard bed fields defined (up to strand) and with additional fields defined after those 6 (indicated by the '+'). The colorByStrand setting configures the plus strand items to be colored red, while the minus strand items are blue.

    type bigBed 8 .
    scoreFilter 700
    scoreFilterLimits 100:1000
    thickDrawItem on
    spectrum on
    scoreMin 700
    scoreMax 900
    color 0,0,128
    minGrayLevel   4
      ...

A bigBed track with the first 8 standard bed fields (through thickEnd), and no additional fields. The '.' tells the Browser that the user may configure this track. The score filter is explicitly declared to default to 700, and the defined range of 100 - 1000 suggests there are no values of interest below 100. This example also colors the description text blue and presents a spectrum or gradation of darkness based upon the score range. Items with a score or 700 or less are displayed as the lightest and items with a score of 900 or more are the darkest. Finally, the minGrayLevel ensures that the lightest shade is visible to the user. No doubt the value of '4' was chosen after experimentation with the Browser display.

    type broadPeak
    pValueFilter 2.0
    pValueFilterLimits 0.0:300.0

This track is a essentially a bed 6+3 format dataset, but it has been defined with special features for ENCODE. The pValueFilter applies to a field named pValue which is one of the 3 additional fields after the standard 6.

Examples of item base types

    type bigBed 6 +
    colorByStrand 255,0,0 0,0,255
      ...

The type setting for a bed and a bigBed are nearly identical. Here, both type settings would define a track with the first 6 standard bed fields defined (up to strand) and with additional fields defined after those 6. Notice that plus strand items are colored red, while minus strand items are blue.

    type bigBed 8 .
    scoreFilter 700
    scoreFilterLimits 100:1000
    thickDrawItem on
    spectrum on
    scoreMin 700
    scoreMax 900
    color 0,0,255
    minGrayLevel   4
      ...

A bigBed track with the first 8 standard bed fields (through thickEnd), and no additional fields. The '.' is required to tell the Browser that the user may configure this track. The score filter is explicitly declared to default to 700, and an allowable range for the score suggests there are no values below 100 worth looking at. This example also sets the description text to blue and presents a spectrum or gradation of darkness based upon the score range. Items with score 700 or less are the lightest, and items with score 900 or more are the darkest. Finally the lightest shade is set to be not too light with the minGrayLevel setting. No doubt 4 was chosen after experimentation to see how it actually looks in the Browser.

wig, bigWig, and bedGraph: Signal graphing tracks

Another set of common track types is one that graphs a density signal along the genome. The graph can be a continuously varying density plot or one that displays a density signal in only certain regions. The oldest and simplest of these is of wig format. This type has been improved as a bedGraph and then greatly enhanced as a bigWig. While there are differences among the formats, all support the basic graph configuration controls. For detailed specifications of each type and how to prepare them for display in the Genome Browser please see the FAQ.

bigWig: Signal graphing tracks

Another set of common track types are those that graph a density signal along the genome. The graph can be a continuously varying density plot or one that displays a density signal in only certain regions. For data hubs the most common signal track type is bigWig. For detailed specifications of the bigWig remote data file format and how to prepare it for display in the Genome Browser please see: http://genome.ucsc.edu/goldenPath/help/bigWig.html.

type wig <low#> <high#>
type bigWig <#> <#>

MariaDB tables of type wig and remote data files of type bigWig must declare the expected signal range for the data.

Examples can be found below.

type bigWig <#> <#>

The remote data files of type bigWig must declare the expected signal range for the data.

Examples can be found below.

type bedGraph <field>
minLimit <#>
maxLimit <#>

The bedGraph type track has the same file format as a bed file, but is loaded into the MariaDB database in a form that can be graphed. By default the value to be graphed is the fifth standard bed field, score; however, you can specify a different field to use. Typically only the first 3 standard bed fields are included (chrom, start, stop) and the fourth field contains the signal value. The bedGraph track offers a couple of important improvements over the wig track. In wig tracks, the value of the signal is truncated into a single byte, which is effective for graphing but fails at data storage. Also the wig type was originally designed for fixed-size windowing, though variations were added. The bedGraph type allows for variable windowing and defining values even down to the base level. To be clear, bigWig tracks are as versatile as bedGraphs. It is only the wig format that suffers from these limitations.

On the other hand the storage density of wig, particularly the fixed step variant, is vastly denser than bedGraph. In cases where the data is solely meant for display, the 256 levels supported by wig more than suffice. For single-base or even 10-base level resolutions, bedGraph is generally not practical genome-wide. Note also that wigs converted to bigWigs do not suffer the reduced precision of wigs loaded directly into the database. A bigWig based on fixedStep wigs is the best way to represent dense graphs over the genome.

Note that the lower and upper limits of the bedGraph signal are not declared in the type, but rather are declared with 2 separate settings, minLimit and maxLimit.

Examples can be found below.

alwaysZero <off/on>

When autoScale is set to "on" or "group" in the signal track, additionally setting alwaysZero to "on" will ensure that the y=0 value will be in view at all times. Default: off.

autoScale <off/on/group>

This setting is available for both the graph types of tracks (wig, bigWig, bedGraph) and the Hi-C heatmap tracks (hic). It behaves slightly differently for each.

For graph tracks, the graph of the data displayed in the Browser image is usually scaled on the y-axis in absolute coordinates. However, you can display the data in two types of autoScale which will ensure either that the high score in the current viewing window will peak at the top of the graph, or that all tracks in a composite will be scaled according to the highest point in the viewing window of any visible tracks in the same composite. Like most graph settings, this is configurable by the user. Setting it to "on" in trackDb will default the track to auto-scale to data view. Setting it to "group" in trackDb will default the track to group auto-scale. The default is "off" which will set the track to use vertical viewing range setting.

NOTE: These options can be misleading if a noisy, low signal erroneously appears as significant because there is no high signal in the view window. The "group" option only applies to composite bigWig tracks.

For Hi-C tracks, higher interaction scores are represented with more intense colors. When this setting is set to "off", the score at which the color reaches maximum intensity is a fixed value that can be chosen with the saturationScore trackDb setting. When this setting is set to "on", the maximum intensity score changes dynamically depending on the values in the current viewing window. The default value for this setting is "on". The "group" option for autoScale is not available for Hi-C tracks.

Example:

   autoScale on

graphTypeDefault points

The signal can be graphed as either "points" displayed at the signal value, or the default space-filling "bar".

Example:

   graphTypeDefault points

maxHeightPixels <max:default:min>

The amount of vertical viewing space for your signal track should be declared, though it is configurable by the user. Typically it is set to no more than 100 pixels and no less than 8, with a default of 16 or 32 pixels.

Example:

   maxHeightPixels 100:16:8

The browser will display the track as 16 pixels high, but the user can scale it up to 100 pixels.

maxWindowToQuery <integer>

For bigWigs only

When signal data is clicked in the Browser image, the details of the signal in the current viewing window are displayed. For bigWigs that reference remote data, the query can be a very expensive operation if the current window is large. To avoid overburdening the Browser, the size of the window to query should be limited. The value of this setting is the maximum window size in bases that should be queried to give the detailed signal numbers.

negateValues <on>

Negate the values in the wiggle, meaning that positive values become negative and vice-versa. This is useful for wiggles representing transcription or other activities on the Crick strand. Be aware that wiggles with negative values are drawn in altColor not color as positive values are. Also, tracks using the windowing function "mean+whiskers" will see the shading of colors impacted, with lighter shades for values a standard deviation around the mean, most noticeable when zoomed out and average calculations are taking place.

spanList <s1>[,s2…]

NOT FOR HUBS. For wig tracks only.

Sets the data point span to just be the first span in table or list of spans in the loaded table you can find the spans by doing: "select span from <table> group by span". Typically spanList is only one as the example shows. Rarely there may be more:
"spanList 1,1000". Special efforts must be made to load extra spans into the table for special purposes.

Example:

   spanList 1

smoothingWindow <off/1-16>

Often signal information is chunky, because a single value is given for a number of bases. The graph can smooth the chunky data, presenting a display more reflective of the actual biology it is meant to illustrate. The numerical value of this setting determines how much surrounding data to use for smoothing: the larger the number, the less abrupt the curves will be. The setting is user-configurable. Default: off.

Example:

   smoothingWindow 4

transformFunc <NONE/LOG>

The track's signal can be presented in log scale with this user-configurable setting. Default: NONE.

Example:

   transformFunc LOG

logo on

The signal can be graphed as reference base nucleotide letters with their heights equal to the signal value within the bigWig track. If not sufficiently zoomed in, the bigWig will revert to bars instead of letters by default. See a working example of the logo dynseq display on the bigWig help page.

Example:

   logo on

mouseOverFunction <noAverage>

Limit mouse over value display to only display the fundamental values without any averaging of multiple data points. Display will show "zoom in to see values" when fundamental individual values can not be shown. Useful for tracks where averaging values together is not a valid operation.

Example:

   mouseOverFunction noAverage

viewLimits <lower:upper>
viewLimitsMax <lower:upper>

The data of most interest in a graph track may be contained within a narrow range. Typically high outlier values can skew a graph and very low values may represent uninteresting data. Use viewLimits to set the default viewing range. Also use viewLimitsMax as suggested outer bounds.

Example:

    viewLimits 5:20
    viewLimitsMax0:100

Any data points of 20 or above will be shown as the peak of the graph. Data points that are below 5 will not be displayed. Even though the full data range extends to 100, these settings suggest that scores of 20 or more are all considered highly relevant.

wigColorBy <bedTable>

NOT FOR HUBS. For wig tracks only.

Regions of the graphed signal may be highlighted by color. Use a bed table and the color settings to shade regions of the wig track.

Example:

    wigColorBy myBed
    color 175,150,128
    altColor 255,128,0

The bed-type table "myBed" is used to highlight regions of graphed signal based upon the scores in that table. The table may itself be a visible track, or may exist only for the purpose of highlighting the signal track.

windowingFunction <mean/mean+whiskers/maximum/minimum>

Depending upon how large of a genomic region is displayed in the Browser image, it may be necessary to summarize the actual signal. This user-configurable setting controls how the Browser collapses the signal from (for example) 100 or 100 thousand bases down to a single pixel. By default the single pixel represents the mean of the data, though the maximum or minimum can alternatively be displayed. A more informative option is often mean+whiskers. This setting displays the mean, max and one standard deviation above mean, differentiated by shading. The mean is displayed as the darkest shade, one stdDev above mean as slightly lighter, and the max as the lightest shade. This subtle shading can quickly indicate if the condensed data is hiding important information that can be adequately evaluated only by zooming in.

Example:

   windowingFunction mean+whiskers

When zoomed out, this track will show the mean signal but include shading representing higher scores. The user may change this setting.

yLineMark <#>
yLineOnOff <off/on>
gridDefault on

It can be useful to draw a line across the track's signal graph at some fixed y coordinate. Do this by setting yLineOnOff to "on" and specifying the y coordinate with yLineMark. These two settings are configurable by the user. Defaults: off and 0.0.

Often confused with these configurable settings is the gridDefault, which simply draws a a line at y=0 across your entire track. This setting might be useful if the lack of data is equivalent to a 0 signal.

Example:

    yLineOnOff on
    yLineMark 2.5
    gridDefault on

The signal is graphed with a default solid line at zero, suggesting that any gaps in data should be interpreted as zero signal. There will also be a line at the signal height of 2.5 that may be used to emphasize which peaks in the signal reach this critical height.

Examples of signal graphing tracks

    type wig 0 100
    windowingFunction maximum
    viewLimits 5:20
    viewLimitsMax 0:100
    maxHeightPixels 100:16:8
    spanList 1
    wigColorBy myBed
      ...

This wiggle track is composed of a MariaDB table and binary "wib" files that are referenced in the table. The default windowing function is the maximum signal in each window (under each pixel) shown. The span of bases covered by each row in the table is identical and can be gathered from the first row in the table. The wiggle has colors supplied by the bed table, myBed.

    type bigWig -0.25 37.6
    windowingFunction mean+whiskers
    viewLimits 5:20
    viewLimitsMax 0:37.6
    maxHeightPixels 100:32:8
    yLineOnOff on
    yLineMark 15
    gridDefault on
    color 128,0,128
      ...

This bigWig format signal is held in a data file (which may be remote). The more informative mean+whiskers windowing function is used by default in this track, and the signal will be 32 pixels high in the Browser image display. Note that even though the signal value may be less than zero, that portion of the signal will not be displayed. The Browser will display a line at y=0 and another at y=15, which may be a threshold value for this signal. The track will be colored purple.

    bedGraph 4
    minLimit 0
    maxLimt 20
    viewLimits 5:8
    viewLimitsMax 0:20
    maxHeightPixels 100:16:8
      ...

This bedGraph style signal track is composed of a MariaDB table of items, each with a score defined in the fourth column. While a wiggle track is usually composed of fixed interval windows of signal (e.g. 200 bp), the bedGraph table may define a signal in varying granularities of windows with or without gaps.

Example of signal graphing tracks

    type bigWig -0.25 37.6
    windowingFunction mean+whiskers
    viewLimits 5:20
    viewLimitsMax 0:37.6
    maxHeightPixels 100:32:8
    yLineOnOff on
    yLineMark 15
    gridDefault on
    color 128,0,128
      ...

This bigWig format signal is held in a data file (which may be remote). The more informative mean+whiskers windowing function is used by default in this track, and the signal will be 32 pixels high in the Browser image display. Notice that even though the signal value may be less than zero, that portion of the signal will not be displayed. The Browser will display a line at y=0 and another at y=15, which may be a threshold value for this signal. The track will be colored purple.

genePred: Gene models and predictions

NOT FOR HUBS. (None of the settings in this section apply to hubs.)

genePred is a variation of item-based tracks designed especially for displaying gene models. Gene models can be represented in bed 12 or bigBed 12 type tracks, but the genePred table format allows for more detail, such as distinguishing between transcript, coding region, and coding vs. non-coding exons. Please refer to the FAQ for information on how to prepare genePred tables for inclusion in the Genome Browser.

type genePred [pepTable [mrnaTable]]

This type of track, based on MariaDB tables, is for gene models and predictions.

pepTable - Optional protein sequence table
mrnaTable - Optional representative mRNA table

Note that missing options can be filled with a '.' dot. Additional settings described below allow the grouping of gene models into classes and the coloring and filtering of the models by class.

Examples can be found below.

Related settings:
geneClasses <cl1 cl2...>

Genes can be grouped into classes for the purposes of coloring and filtering. The trick is how to associate each named gene with its class. Use geneClasses to create a list of all gene class names delimited by white space.

gClass_<xxx> <red,green,blue>

Declare an RGB color for a named class.

itemClassTbl <table>

Declare a MariaDB table that will link classes to named gene models.

itemClassNameColumn <col>

Optionally declare the column of the itemClassTbl that will hold the genePred names. Default: name.

itemClassClassColumn <col>

Optionally declare the column of the itemClassTbl that will hold the class. Default: class.

Example:

    geneClasses rRNA tRNA snRNA
    gClass_rRNA 255,0,0
    gClass_tRNA 0,255,0
    gClass_snRNA 0,0,255
    itemClassTbl rnaTypes
    itemClassNameColumn rnaName
    itemClassClassColumn rnaType

In this genePred type track, RNA gene models are divided into 3 classes that are colored red, green or blue. The association of named gene models in the genePred table with the three classes is defined in the "rnaType" table. That table holds the RNA type in the "rnaType" column and the gene name in the "rnaName" column.

filterBy <field1:title=[+]option1a...>
                                [field2:title=[+]opt2a...]

Filtering gene models by table column or even itemClassTbl column can be achieved by this setting. Complete description of this setting can be found in the bed/bigBed item-based track settings. Here is an example for referencing the class as found in the table defined by itemClassTbl. Not all track types will support externally referenced tables using filterBy as genePred type does. But if you understand the CGI code that performs the table select, then filterBy can provide a powerful extension to the SQL selection used.

Example:

    geneClasses rRNA tRNA snRNA
    gClass_rRNA 255,0,0
    gClass_tRNA 0,255,0
    gClass_snRNA 0,0,255
    itemClassTbl rnaTypes
    itemClassClassColumn rnaType
    filterBy rnaTypes.rnaType:Class=\
             rRNA|Ribosomal_RNA{color:#FF0000},\
             tRNA|Transfer_RNA{color:#00FF00},\
             snRNA|Small_Nuclear_RNA{color:#0000FF}

When gene models are selected from the genePred table for display in the Browser, their class is also selected from the "rnaTypes" table. Using the filterBy setting creates a user selectable drop-down list box of 3 choices or "all". When the user filters by tRNA and snRNA (the green and blue choices), the SQL select statement used by the Browser will be limited by the where clause "where rnaTypes.rnaType in ('tRNA','snRNA')".

autoTranslate 0

By default, a predicted protein translation is generated for a gene model when a user views it on the details page. This feature may be blocked by setting autoTranslate to zero.

Example:

   autoTranslate 0

The genPred track will NOT show auto-generated protein sequence, perhaps because this track is for RNA genes.

intronGap <#bases>

In drawing gene models, it can be useful to see "exon arrows" when the transcript extends beyond the current window. This setting, which defaults to zero, ensures that these arrows will not be drawn if the interceding intron gap is less than the stated number of bases.

Example:

   intronGap 12

Don't draw exon arrows when the gap between exons is 12 bases or less.

defaultLinkedTables <table1>[,table2...]

In hgTables, when selecting output fields, display these all.joiner-linked tables by default.

Example:

   defaultLinkedTables kgXref

idXref <idColumn> <altIdColumn>

By using this setting you can link alternative names to the gene models found in a genePred. This is used by the Table Browser to establish links to other tables.

Example:

    track knownGenes
    idXref kgAlias kgID alias

The ID in the name column of the knownGenes table is related to the alias found in the kgAlias table.

oldToNew <tableName>

In successive versions of gene models, it can be helpful to map older genes to their newer models. This can be done by providing a MariaDB table that maps the change, and then using this setting to ensure the gene details page shows any changes.

Example:

    track knownGeneOld5
    oldToNew kg5ToKg6

The older version of UCSC Genes references changes that are seen in the newer version.

Examples of genePred tracks

    type genePred
    oldToNew kg5ToKg6
    baseColorUseCds given
    baseColorDefault genomicCodons
    geneClasses coding nonCoding pseudo
    itemClassTbl myClasses
    gClass_coding 12,12,120
    gClass_nonCoding 0,153,0
    gClass_pseudo 255,51,255
    filterBy myClasses.transcriptClass:Class=\
            coding{color:#0C0C78},\
            nonCoding{color:#009900},\
            pseudo{color:#FF33FF}
      ...

Gene model track with defined classes and the option to filter by the color-coded classes. Note the base level coloring option.

    type genePred . mrna
    url https://www.ncbi.nlm.nih.gov/IEB/Research/Acembly/av.cgi?db=hg17&l=$$
    urlLabel AceView Gene Summary:

This gene prediction track has associated representative mRNAs found in the "mrna" table. There is also an "AceView Gene Summary" url presented on the details page.

bam/cram: Compressed Sequence Alignment/Map tracks

The bam/cram format is an indexed compressed data format for sequence alignments. It is ideal for remote access of high-throughput sequence tags and is a native output format for some high-throughput sequencing (HTS) aligners. The format of bam data is data-file pairs, with an index in a separate file. CRAM files are compressed versions of BAM files where the reference sequence is not included. CRAM files should be listed as "type bam" in trackDb. These are frequently remote datasets, not residing on the UCSC server. Please refer to the BAM track format page or CRAM track format page and the SAMtools website for information on how to create and deploy these remote data files for inclusion in the Genome Browser.

type bam

Declares configuration settings for a track of type bam. If the bigDataUrl setting is included, that data at the location specified by that URL will be displayed. Otherwise, a database table with a single column fileName can specify the location of a local file or a URL. If the database table includes a column seqName, a different BAM file or URL can be specified for each assembly sequence.

Example can be found below.

Related settings:
bamColorMode <strand/gray/tag/off>

There are numerous ways to color bam tracks to highlight certain aspects of the data. All of these are user-configurable.

Possible settings:

strand: (Default) When colored by strand, mismatched bases are highlighted in bright red, alignments on the reverse strand are colored dark red, and alignments on the forward strand are colored dark blue.
gray: When colored in grayscale, items are shaded according to the method specified by bamGrayMode: alignment quality, base qualities, or unpaired ends.
tag: Colors are specified in "user-defined tags". SAM/BAM may include user-defined tags, the names of which begin with X, Y or Z and include one other letter or number. The user-defined tag named here specifies red, green and blue (RGB) intensities as a zero-terminated string (tag type Z) containing comma-separated triples of numbers from 0-255. For example, if a SAM/BAM record includes the tag YC:Z:255,0,0, then the item is colored red; YC:Z:0,0,255 makes the item blue. By default, the tag is "YC" unless changed using the bamColorTag setting.
off: No additional coloring.

bamGrayMode <aliQual/baseQual/unpaired>
aliQualRange <min:max>
baseQualRange <min:max>

When bamColorMode is set to "gray", you can highlight one of the following:

aliQual: (Default) The "alignment qualities" of the items are shaded on a scale of 0 (lightest) to 99 (darkest). Use aliQualRange to specify a default range.
baseQual: "Base qualities" are shaded on a scale of 0 (lightest) to 40 (darkest). Use baseQualRange to specify a default range.
unpaired: When "unpaired ends" is selected, an item that was paired in sequencing but whose mate was not mapped is colored gray, while singletons and properly paired items are colored black.

Refer to the SAM format details for a discussion of these values.

bamColorTag <XX>

You can also use RGB data associated with individual tags within the bam file itself. Refer to the SAM documentation to understand how the RGB values are included. When the bamColorMode is set to "tag", the standard "YC" tag is used as the default. The default may be overridden with this setting.

noColorTag .

The bam coloring options are all user-configurable within the browser. If your bam dataset contains no color tags, this setting should be included to block the Browser from offering the option to color tags by an embedded RGB value.

Examples:

    bamColorMode strand
    noColorTag

Sets the bam to use the default coloring scheme based on strand alignment. At the same time, the bam track will not offer the option to color the tags by RGB values, perhaps because this bam has no RGB values.

    bamColorMode gray
    bamGrayMode aliQual
    aliQualRange 20:80

These settings will highlight tags by alignment quality score. If the score is at 80 or above, the tag is shaded black; if it is less than 20, the tag is shaded very light gray.

    bamColorMode tag
    bamColorTag YC

The bam file includes RGB values in the YC field that will be used to color tags.

    bamColorMode off

No special coloring will be applied to items.

bamSkipPrintQualScore .

Any bam tag can be displayed on the details page by clicking on it in the Browser image. The details include quality scores by default. If these scores are not relevant for this particular bam, they may be excluded from the details page with this setting.

Example:

   bamSkipPrintQualScore .

indelDoubleInsert <off/on>
indelQueryInsert <off/on>
indelPolyA <off/on>

Insertion and deletion differences between tag sequences and the reference genome can be highlighted with the use of these settings. These options may be set by the user.

indelDoubleInsert: Use to highlight alignment gaps in both the target (reference) and query (tag) sequence with double (=) lines.
indelQueryInsert: Use to highlight an insert in the query sequence only by drawing an orange (|) or purple (|) vertical line. Orange lines show unalignable regions in the middle of a sequence, and purple highlights regions at the end of the query sequence.
indelPolyA: Use to highlight an apparently valid poly-a tail by drawing a vertical green line (|).

Example:

    baseColorUseSequence genbank
    indelDoubleInsert on
    indelQueryInsert on
    indelPolyA on

minAliQual <#>

When the Browser image is zoomed in to the level where individual tags are visible, the tags in a bam file can be filtered to show only those with a minimum alignment quality score. This is a user-configurable setting. Default: 0.

Example:

   minAliQual 20

Related settings:
pairEndsByName .

Some high-throughput sequencing technologies result in "paired end" tags, which are two individual bam records joined by their name. If this is the case with your dataset, include this setting.

pairSearchRange <#>

Searching to join pairs of tags by name will be limited to a maximum distance (default: 20,000 bases). Use a larger range to increase the likelihood that both reads in a pair will be found even when only one read is in the viewed region. Use a smaller range to speed image rendering.

Example:

    pairedEndsByName .
    pairSearchRange 5000

The dataset includes paired end tags. The maximum search range to join tag pairs by name is capped at 5000.

showNames <on/off>

When the Browser image is zoomed in to the level where individual tags are viewable, the query name for each tag is shown by default. Use this setting to hide this name.

Example:

   showNames off

doWiggle on

The doWiggle setting enables the BAM data to be displayed as a bar graph where the height is proportional to the number of reads mapped to each genomic position. Through dynamic calculation of items in the current window, this feature plots a line similar to a wiggle graph that can be customized with a number of graph-based configuration options such as drawing indicator lines, smoothing plots, adjusting graph height and vertical range, and switching from bars to points. Please note that the feature is best displayed with "Display mode" set to full and that the default "Data view scaling" is "auto-scale to data view."

Example:

   doWiggle on

Example of a bam track

    type bam
    bigDataUrl http://hgdownload/ucsc.edu/goldenPath/hg19/bambam/barneysSon.bam
    pairEndsByName on
    showNames off
    bamColorMode off
    bamGrayMode aliQual
    indelDoubleInsert on
    indelQueryInsert on
    maxWindowToDraw 10000
      ...

The bam data is held in the file "barneysSon.bam" which is at an internet-accessible location. In addition to the data file, an associated index file must reside at the same location. The index file must have the same name as the data file, with ".bai" appended (e.g. barneysSon.bam.bai).

psl: Sequence alignments

NOT FOR HUBS. (None of the settings in this section are available for hubs, although it is likely that hub support will be added in the future.)

PSL is an alignment format in which the data is typically taken from files generated by BLAT or psLayout. For further information about this format please refer to the FAQ and BLAT documentation.

type psl <subtype> [otherDb]

The psl type tracks require the specification of a subtype: est, mrna, protein or xeno. The default, which is represented as ".", is regular human mRNA. When the xeno subtype is selected, an additional optional parameter may be set to specify the other species assembly. If present, the alignments can be color-coded by chromosome, and the chromosome and position (in kilobases) are shown in the alignments label.

Examples can be found below.

blastRef <assembly.table>

Include a blastRef to an assembly and table that contains geneId and position retrievable by accession id. This information will be displayed in the item name.

Example:

   blastRef hg17.blastKGRef02

colorChromDefault off

For psl tracks of subtype xeno, the alignments may be colored to indicated their location in the other species. This setting is turned on by default when the other species is specified in the type psl setting. Use this setting to turn off chromosome coloring by default, offering the user the choice to turn it on.

Example:

    type psl xeno loxAfr1
    otherDb loxAfr1
    colorChromDefault off

pred <assembly.table>

Use the pred setting to name an assembly and table containing protein sequence data for the named alignments.

Example:

  pred hg18.blastKGPep04

pslSequence <no/all/different>

This setting specifies some display configuration options for psl tracks that also have sequence loaded.

all: Display nucleotide labels on all bases.
different: Label only base differences.
no: Allow the user to select which of the other two options is preferred.

Example:

    pslSequence different

transMapGene <assembly.table>
transMapInfo <table>
transMapSrc <assembly.table>
transMapTypeDesc <label>

For alignment tracks generated using the TransMap cross-species alignment algorithm, these settings are used to connect the transMap detailed information with the alignments.

transMapInfo: Use to name the table in the current assembly that ties an alignment with the source assembly and feature.
transMapSrc: Use to name the table in the source species assembly that contains the details of the feature's source location.
transMapGene: Use to name the table mapping the alignment to gene names in the relevant species. Note that tables that are common to multiple species should be put in the hgFixed database.
transMapTypeDesc: Use to set a label for the type of transMapping that the alignment covers.

Example:
```
    transMapInfo transMapInfoUcscGenes
    transMapSrc hgFixed.transMapSrcUcscGenes
    transMapGene hgFixed.transMapGeneUcscGenes
    transMapTypeDesc UCSC Gene
    baseColorUseCds table hgFixed.transMapGeneUcscGenes
    baseColorUseSequence extFile hgFixed.transMapSeqUcscGenes    
```
Note that several of the named tables are in hgFixed, which is a database containing tables that are shared by multiple species and assemblies. Also notice that the same table that was named in transMapGene is also used in this example for baseColorUseCds.

ucscRetroInfo

For alignments illustrating retrotransposition, use this setting to name a table with details of the source location.

Example:

   ucscRetroInfo ucscRetroInfo1

Examples of psl alignment tracks

    track ucscRetroAli1
    type psl
    ucscRetroInfo ucscRetroInfo1
    baseColorDefault diffCodons
    baseColorUseCds table ucscRetroCds
    baseColorUseSequence extFile ucscRetroSeq1 ucscRetroExtFile1
    indelDoubleInsert on
    indelQueryInsert on
    showDiffBasesAllScales .
    showDiffBasesMaxZoom 10000.0
      ...

In this example of retroposed genes, mature mRNA has been aligned to the genome. Notice there is a ucscRetroInfo table that describes the non-transposed gene location. Also notice the use of the baseColor settings for coloring the coding sequence (CDS).

    track protBlat
    color 0,100,0
    altColor 255,240,200
    type psl protein
      ...

In this example of protein sequence blat results, the color of matching sequence is green, while indels (in this case introns) are highlighted with yellow.

    track rgdEst
    spectrum on
    color 12,12,120
    type psl est
      ...

This expressed sequence tag example will have colored alignments that are graded by a score thanks to "spectrum on". Though psl tracks do not have a score column as part of the format, a score is generated based upon matches and mismatches in the alignment. The shading is even more subtle in that the weight given to inserts varies depending upon whether the alignment is to the same or a different species.

    track blastzTetNig1
    color 0,0,0
    altColor 50,128,50
    spectrum on
    type psl xeno tetNig1
    otherDb tetNig1
      ...

This psl track is for foreign species or "xeno" alignments, in this case the sequence reads of a species of fish aligned to human.

chain and netAlign: paired species alignments

NOT FOR HUBS. Nor are any of the settings in this section.

While "chain" and "netAlign" formats are different, they often are paired to show two different views of the same data.

Chain tracks show alignments of a "query" species to a "target" genome assembly. For example, a chimp panTro2 can be aligned to the human hg19 genome. The chain format allows for gaps in both sequences simultaneously. When chains are viewed in the Browser, they show solid boxes for alignments, separated by either single or double lines. The single lines appear when an insertion occurs in the target or a deletion occurs in the querying species. Double lines represent gaps in both species that could result from a number of causes (e.g. an inversion in one species). For more information on the "chain" format, please refer to http://genome.ucsc.edu/goldenPath/help/chain.html.

A netAlign track represents the best chain for each region in the target genome. The net track will show the largest, highest scoring chains that span a region. When these chains have gaps, they may be filled in with additional chains, shown at a lower level, and gaps in these chains may in turn be filled at an even lower level. These levels help in visualizing genome rearrangements such as inversions and retroposed elements. For more information on the netAlign format, please refer to http://genome.ucsc.edu/goldenPath/help/net.html.

type chain <otherDb>
otherDb <otherDb>

Tracks of type chain show sequence alignments from another species to the reference genome. This type requires the assembly database of the other species to be named in both the type setting and in the "otherDb" setting.

Example can be found below.

type netAlign <otherDb> <otherChainTable>
otherDb <otherDb>

Tracks of type netAlign show the best chains of sequence alignments from another species to the reference genome. Gaps are filled in levels, where possible. This type requires the assembly database of the other species to be named in both the type setting and in the "otherDb" setting.

Example can be found below.

chainColor <scheme>

By default chains are colored by the alignment chromosome of the query species. This can be overridden with this setting. The three options are:

Chromosome - default
Normalized Score - chains are colored by score
Black - no coloring occurs

This setting affects chain but not netAlign type tracks.

Example:

   chainColor Black

chainLinearGap <loose/medium>

The chainLinearGap setting should reflect the "-linearGap" parameter used in axtChain to generate the track. It represents the gap scoring matrix used and will be either:

loose - chicken/human linear gap costs
medium - mouse/human linear gap costs

This setting is for both chain and netAlign type tracks.

Example:

   chainLinearGap medium

chainMinScore <#>

The chainMinScore setting should reflect the "-minScore" parameter used in axtChain to generate the track. It represents the score threshold for chains to be included in the set. Default is 1000. This setting is for both chain and netAlign type tracks.

Example:

   chainMinScore 5000

chainNormScoreAvailable <yes/no>

A given chain or netAlign track may or may not have a populated normScore column. If the column exists, then its value can be displayed in the item details page of the Browser by setting chainNormScoreAvailable to yes. Item coloring based upon score as selected by the chainColor Normalized Score setting also requires this setting to be yes.

Example:

    chainNormScoreAvailable yes
    chainColor Normalized Score

matrix <size> <#,#,#,#,…>
matrixHeader <b1,b2,b3,b4>
$matrix token in html.

The method for scoring and selecting chains and generating netAligns relies upon a matrix of costs for base substitutions. The matrix used in the generation of any given paired alignment can vary depending upon such things as evolutionary distance and the species involved. The matrix used can be dynamically included in the HTML description using three elements:

The HTML description must have the $matrix token in it.
The matrix to be used must be defined with this trackDb setting. The format of this setting is the cell size of the matrix which for DNA alignments is 16. This size is separated by a space from the comma-delimited array of all the values as the matrix cells are filled in left to right and top to bottom.
The matrixHeader setting should be used to define the order of base transitions in the matrix. Typically it is “A,C,G,T “.

Example:

    html chainNet
    matrixHeader A,C,G,T
    matrix 16 91,-114,-31,-123,\
                 -114,100,-125,-31,\
                 -31,-125,100,-114,\
                 -123,-31,-114,91

Here the $matrix token found in the chainNet.html file will be replaced by the following matrix:

	A	C	G	T
A	91	-114	-31	-123
C	-114	100	-125	-31
T	-31	-125	100	-114
G	-123	-31	-114	91

Examples of chain and netAlign tracks

    track chainRheMac2
    type chain rheMac2
    otherDb rheMac2
    color 0,0,0
    altColor 100,50,0
    matrix 16 91,-114,-31,-123,-114,100,-125,-31,-31,-125,100,-114,-123,-31,-114,91
    matrixHeader A,C,G,T
    chainMinScore 3000
    chainLinearGap medium
    html chainNet
      ...

    track netRheMac1
    type netAlign rheMac1 chainRheMac2
    otherDb rheMac2
    matrix 16 91,-114,-31,-123,-114,100,-125,-31,-31,-125,100,-114,-123,-31,-114,91
    matrixHeader A,C,G,T
    chainMinScore 3000
    chainLinearGap medium
    html chainNet
      ...

Both the chain and netAlign tracks above are for alignments of the query species/assembly rheMac2 against the target species determined by the database this trackDb belongs to (e.g., human/hg19). Because the netAlign track is based upon the data in the chain track, it references the track in its type setting. Both tracks use the same matrix, chainMinScore and linear gap settings. Methods to group these two tracks into a single set that share settings are described later in this document.

wigMaf: Multiple alignments

NOT (currently) FOR HUBS. Nor are any of the settings in this section.

Multiple pairwise alignments can be displayed with "wigMaf" type tracks. Tracks of this type may actually be composed of multiple tables and data files. The type setting will name the one MAF format table (with an associated "maf" file in /gbdb). The optional "wiggle" setting will name one or more wig format tables (with an associated "wib" files) that contain conservation signals. Please refer to the FAQ for information on how to prepare multiple alignment format datasets.

type wigMaf <minVal> <maxVal>

A wigMaf type track is composed both of MAF format alignment (loaded with hgLoadMaf). The track may optionally include one or more conservation signals. The signals must be within the same data range defined with the min and max values in the type setting.

Examples can be found below.

frames <table/url>

A wigMaf or bigMaf track can display gene codon translation. The reading frame may differ between species. By providing the reading frames information in a separate table, the user can choose which frame to use when viewing the data. For bigMaf the value is expected to be a bigBed, for wigMaf it should be a table. Read about bigMaf supporting files on the help page.

Example:

   frames myCodonFrames

   frames myCodonFrames.bb

irows off

By default, gaps in the non-reference species are filled with the placeholder character:

Single Line '-': No bases in the aligned species. Possibly due to a lineage-specific insertion between the aligned blocks in the human genome or a lineage-specific deletion between the aligned blocks in the aligning species.
Double line '=': Aligning species has one or more unalignable bases in the gap region. Possibly due to excessive evolutionary distance between species or independent indels in the region between the aligned blocks in both species.
Pale yellow coloring: Aligning species has Ns in the gap region. Reflects uncertainty in the relationship between the DNA of both species, due to lack of sequence in relevant portions of the aligning species.

These display conventions make it easier to visualize the columns in stacked alignments, but they also tend to clutter the display. The user has the option to remove these placeholders by unchecking the "Display chains between alignments" option. To set the default of this option to off, set irows to "off".

Example:

   irows off

itemFirstCharCase noChange

This controls if species names in the multiple alignment should be capitalized in the pairwise display. Set "noChange" to avoid forcing the first letter to lower case.

Example:

   itemFirstCharCase noChange

pairwiseHeight <#>

A wigMaf display in the Browser image is a stacked set of pairwise alignments to the target genome. Using this setting, you can change the height of each pairwise signal in the image.

Example:

   pairwiseHeight 10

speciesCodonDefault <species>

This setting, which is used with "frames", declares the default species for the codon reading frame.

Example:

    speciesCodonDefault hg19
    frames myCodonFrames

speciesDefaultOff <species1> [species2 ...]

To control which of the stacked pairwise alignments are displayed or hidden by default, use speciesDefaultOff to list the species alignments that will not be displayed. Each species is specified as in the MAF file Organism names except embedded dots and/or spaces are replaced with underscores (e.g. C. elegans -> c_elegans).

Example:

   speciesDefaultOff galGal2 fr1 danRer1

Related settings:
speciesOrder <species1> [species2 …]

Use speciesOrder to declare the order of the stacked alignments. If there are many species in your track, it may make sense to use the speciesGroups setting instead.

speciesLabels <species1=newLabel1> [species2=newLabel2 …]

Use speciesLabels to specify new labels that map to sequence names.

Example:

   speciesLabels mm10=mouse_mm10 mm39=mouse_mm39

speciesGroups <sgroup1> [sgroup2 …]
sGroup_<sgroupN> <species1> [species2 …]

You can include a list of "clades" to group the species into. This option is an alternative to speciesOrder, used when there are many species. Each speciesGroup in the list must have its own setting (sGroup_<group>), followed by a list of species, specified as for speciesOrder.

Examples:

    speciesOrder panTro1 canFam1 mm5 rn3 \
                 galGal2 fr1 danRer1
    speciesGroups Mammal Vertebrate
    sGroup_Mammal mm9 rn4
    sGroup_Vertebrate galGal2 fr1 danRer1

Choose one of these two alternatives to display species.

speciesUseFile <fileName>

Deprecated

Much more rarely used, this setting can replace speciesOrder and speciesGroups. Set the speciesUseFile to a path relative to the apache cgi-bin. The file should contain a single species name as the first word of each line.

Example:

    speciesUseFile speciesLists/conserved8Way.txt

summary <tableName/url>

This setting contains a table name containing a MAF summary table, or a url that points to a bigBed containing that information. The summary view is used when the browser display is zoomed out to contain a million or more basepairs. A summary table is created from a multiple alignment MAF file using the utility hgLoadMafSummary. For bigMaf, the value is assumed to be bigBed, Read about bigMaf supporting files on the help page.

Example:

   summary hg17Maf8waySummary

treeImage <imageFile>

The phylogenetic tree can used to show the relations of the species in the multiple alignment should be included as an image file. This path is relative to the htdocs images directory (usually /images).

Example:

   treeImage phylo/hg17Maf8way.jpg

wiggle <table1> <leftLabel1> <uiLabel1>
                                        [table2 leftLabel2  uiLabelN ...]

Optionally more than one conservation signal can be included with your MAF display by using this setting. When you include conservation wiggles, you can also include the standard settings for controlling signal type tracks. The setting includes three parts, then (optionally) additional sets of three, all delimited by white space. The first table is the default. The leftLabel is used to prefix the label "Cons" in the left label area of the Browser image. The uiLabel is displayed in the track configuration page. If only one table is listed, and no label is present, the default label "Conservation" will be displayed. The labels cannot contain spaces, but underscores (_) will be translated to spaces in the display.

Note: directly pairing the conservation signals within the wigMaf track is an older way of doing things. It is easier to give users control of what they want to see, by including your wigMaf track and separate signal type tracks as subtracks within a composite track. See the composite track description below.

Example:

    wiggle phastCons8wayMammal Mammal Placental_Mammal \
           phastCons8way Vertebrate Vertebrate

Examples of wigMaf tracks

    track hg17Maf8way
    type wigMaf 0.0 1.0
    summary hg17Maf8waySummary
    wiggle phastCons
    treeImage phylo/hg17Maf8way.jpg
    speciesOrder panTro1 canFam1 mm5 rn3 galGal2 fr1 danRer1
    speciesDefaultOff galGal2 fr1 danRer1
    irows off
    pairwiseHeight 10
    maxHeightPixels 100:16:8
    viewLimits 0.5:0.9
    viewLimitsMax 0.0:1.0
      ...

This 8-way multi-alignment for the hg17 human assembly is defined to include a summary table, tree image and one wiggle table containing the conservation score for the 8 species. Notice that the pairwise alignments for the last three species are turned off by default, and each pairwise alignment will have a height of 10 pixels. With few species displayed by default, irows defaults to "off" as well, which will result in a cleaner display. Since there is a conservation wiggle, there are additional settings for that signal.

    track multiz46way
    type wigMaf 0.0 1.0
    summary multiz46waySummary
    frames multiz46wayFrames
    speciesCodonDefault hg19
    itemFirstCharCase noChange
    treeImage phylo/hg19_46way.gif
    speciesGroups Primate Placental_Mammal Vertebrate
    sGroup_Primate panTro2 gorGor1 ponAbe2 rheMac2 papHam1 calJac1 tarSyr1 micMur1 otoGar1
    sGroup_Placental_Mammal tupBel1 mm9 rn4 …
    sGroup_Vertebrate macEug1 monDom5 ornAna1 …
    speciesDefaultOff panTro2 gorGor1 ponAbe2 papHam1 …
    pairwiseHeight 10
      ...

For this wigMaf track, there is no wiggle defined. In this actual example taken from the hg19 Genome Browser, the several conservation signals displayed in concert with this multiple alignment are separate signal-type tracks defined as part of the "Conservation" composite track (see discussion of composites below). Notice that the 46 species in this alignment are organized into clades using the "speciesGroups" setting. Each clade has its own "sGroup" setting to declare the order within (not all species shown).

expRatio: Microarray expression data

NOT FOR HUBS. Nor are any of the settings in this section.

Though many microarray experiments have been superseded by high-throughput sequencing (e.g., ChIP-seq) experiments, several microarray tracks still exist. Further, microarray experiments can be the economical or practical choice in many instances. The datasets for the built-in microarray tracks in the Genome Browser are stored in bed 12+3 (bed 15) format that includes three additional fields: expCount, expIds, and expScores. To display correctly in the Genome Browser, microarray tracks require the setting of several attributes in the trackDb file associated with the track's genome assembly. Each microarray track set must also have an associated microarrayGroups.ra configuration file that contains additional information about the data in each of the arrays. Please refer to the microarray track section of the UCSC genomewiki for information on how to prepare microarray tracks. In particular, that document describes the format of the groupings.ra file that must be associated with an expRatio track.

Note: The expRatio data formats are reused for the factorSource type.

type expRatio

Microarray data is displayed in the Browser by expRatio type tracks. The type requires additional settings: expScale, expStep and groupings.

Example can be found below.

expDrawExons on

If microarray data includes gene model or blocks within items, then the data can be viewed as exons and introns by setting expDrawExons to on. The setting is configurable by the user.

Example:

   expDrawExons on

expScale <#>

Maximum expression value.

Example:

   expScale 3.0

expStep <#>

Amount to step in visible expression scale. A round number close to expScale divided by 8 is best.

Example:

    expScale 3.0
    expStep 0.5

expTable <tableName>

This setting specifies the name of a table in the common hgFixed database that contains names of experiments, etc.

groupings <fileName>

A microarray dataset must refer to a specific set of configurations to load from the microArrayGroups.ra file. Please refer to the microarray track section of the UCSC genomewiki for detailed instructions on the location of this file and its format. Use the "groupings" setting to point to a stanza keyed on "name" in that file.

Example:

   groupings gnfHumanAtlas2Groups

Example of an expRatio track

    track sestanBrainAtlas
    type expRatio
    expScale 3.0
    expStep 0.5
    expTable sestanBrainAtlasExps
    groupings sestanBrainAtlasGroups
      ...

This microarray dataset refers to groupings defined in the "gnfHumanAtlas2Groups" stanza of the makeDb/hgCgiData/Human/microarrayGroups.ra file.

extraDetailsTable <url/relativePath>

This setting was renamed June 2022. Please use detailsStaticTable instead.

Provides a template to a tab separated text file where $<fieldName> strings will be substituted for data in the bigBed and displayed as an HTML table. For an example of this, please see the following text file: http://hgdownload.soe.ucsc.edu/gbdb/hg38/gnomAD/v3.1/variants/v3.1.genomes.popTable.txt, where the strings such as "${AC_afr}" will be substituted for the data in that field for the particular item from the bigBed.

Note that the same size table is displayed for every item of the bigBed, even if there is missing data in that field for a particular item. For variable size tables, please see detailsDynamicTable.

extraTableFields <fieldName1|table title,fieldName2|table title,...>

This setting was renamed June 2022. Please use detailsDynamicTable instead.

Tells the system that the data in <fieldName1,...> contains an encoded table that should be turned into a standard HTML table on the details page for that item. If the <fieldName> starts with "_json" or "json", then the system expects the data in <fieldName> to be valid JSON. If the field name starts with anything else, then the table is formatted using "|" and ";" as field and new row separators. The "table title" part of the statment is optional, if present it will be used as the title for the table, if not, then the title will be taken from the autoSql description of the field name, or if there is no autoSql because the data is from an external file, then the field name will be used.

An example of both formats is shown below, along with the corresponding trackDb statements:

trackDb line:

extraTableFields _jsonField1|JSON Title Example,tableField2|NON-JSON Title Example

the two columns from the bigBed (or external file):

_jsonField1	tableField2
{key:val, key1: val1, key2: val2}	key|val;key1|val1;key2|val2

And when clicking on an item in the browser, the following would be displayed:

JSON Title Example

key	val
key1	val1
key2	val2

NON-JSON Title Example

key	val
key1	val1
key2	val2

Note that the number of columns and rows is variable per item, meaning some items can have different sized tables than other items, contrasting with the extraDetailsTable statement, which enforces the same table size per item. For instance, in the above example, a 3 rows by 2 columns table is created for each field, but if our JSON was instead:

{"transcript1": {annot1: val1, annot2: val2}, "transcript2": {annot3: val3}}

then the following nested table would be shown on the details page:

JSON Title Example

transcript1

annot1	val1
annot2	val2

transcript2

annot3

val3

detailsStaticTable <url/relativePath>

Note that the same size table is displayed for every item of the bigBed, even if there is missing data in that field for a particular item. For variable size tables, please see detailsDynamicTable.

detailsDynamicTable <fieldName1|table title,fieldName2|table title,...>

An example of both formats is shown below, along with the corresponding trackDb statements:

trackDb line:

detailsDynamicTable _jsonField1|JSON Title Example,tableField2|NON-JSON Title Example

the two columns from the bigBed (or external file):

_jsonField1	tableField2
{key:val, key1: val1, key2: val2}	key|val;key1|val1;key2|val2

And when clicking on an item in the browser, the following would be displayed:

JSON Title Example

key	val
key1	val1
key2	val2

NON-JSON Title Example

key	val
key1	val1
key2	val2

{"transcript1": {annot1: val1, annot2: val2}, "transcript2": {annot3: val3}}

then the following nested table would be shown on the details page:

JSON Title Example

transcript1

annot1	val1
annot2	val2

transcript2

annot3

val3

snpNNN: specialized subclass of BED 6 for dbSNP variants

NOT FOR HUBS. Nor are any of the settings in this section.

This particular variant of bed 6, identified by table name, is for UCSC's subset of dbSNP, NCBI's database of short genetic variants.

type bed 6 + # Track name starts with "snp"
    followed by the 3-digit dbSNP build number

UCSC's subset of dbSNP could be described as "bed 6 + 19" and is produced by a complex process starting with downloading several database dump files and fasta files from dbSNP, and ending with the creation of snpNNN and several auxiliary data tables. This type is not supported as a custom track type.

chimpDb <db>

If chimp chains/nets were used to identify the chimp reference assembly allele at the location homologous to the human SNP, this specifies which chimp genome assembly was used, e.g. panTro2.

chimpMacaqueOrthoTable <table>

If chains/nets from chimp and rhesus macaque were use to identify the chimp or macaque reference assembly allele at the location homologous to the human SNP, this specifies the database table that contains the mapped alleles.

chimpOrangMacOrthoTable <table>

If chains/nets from chimp, orangutan and rhesus macaque were use to identify the chimp/orangutan/macaque reference assembly allele at the location homologous to the human SNP, this specifies the database table that contains the mapped alleles.

codingAnnoLabel_<table> <text>

Deprecated; will probably be removed. This specifies a text label for display of <table>'s predictions of a SNP's effect on a protein-coding gene.

codingAnnotations <table>[,table]

Deprecated; will probably be removed. This specifies one or more tables containing predictions of SNP effects on protein-coding genes.

defaultGeneTracks <genesTrack>[,genesTrack]

The details page of a SNP can display the predicted functional affect on a gene from any genePred track. Since there are often many gene tracks and models, the prediction will depend upon the gene model used. The user has a chance to choose from those available, but this setting establishes a default gene track or tracks to base predictions on.

Example:

   defaultGeneTracks knownGenes

defaultMaxWeight <1|2|3>

dbSNP assigns a weight of 1, 2 or 3 to each variant, depending on how many distinct mappings a variant's flanking sequences have to the genome. If this is set to 1, only uniquely mapped variants will be displayed by default. If 2, only uniquely mapped variants and variants with a small number of duplicate mappings will be displayed. If 3, all variants will be shown regardless of weight. Note: some tables such as snpNNNCommon and snpNNNFlagged contain only uniquely mapped variants, so this setting has no effect on those tables.

hapmapPhase <II|III>

The SNP details page looks for the SNP's ID in HapMap track tables that have different names and contents depending on whether they were loaded from HapMap phase II or HapMap phase III data. (This setting is also used by HapMap SNPs tracks.)

macaqueDb <db>

If macaque chains/nets were used to identify the macaque reference assembly allele at the location homologous to the human SNP, this specifies which macaque genome assembly was used, e.g. rheMac2.

orangDb <db>

If orangutan chains/nets were used to identify the orangutan reference assembly allele at the location homologous to the human SNP, this specifies which orangutan genome assembly was used, e.g. ponAbe2.

snpExceptions <table>

This specifies an auxiliary table that contains annotations of unusual properties of variants. This setting applies only to versions prior to dbSNP build 132; starting with build 132, exceptions are incorporated into the main snpNNN table and an auxiliary table is no longer needed.

snpExceptionDesc <table>

This specifies an auxiliary table that maps exception keywords to one-sentence descriptions.

snpSeq <table>

This specifies an auxiliary table that maps variant IDs to file offsets at which flanking sequences are stored.

snpSeqFile <path>

This specifies an auxiliary file that contains the flanking sequences of each variant's representative submitted SNP.

Example of a SNP track

    track snp135Common
    shortLabel Common SNPs(135)
    longLabel Simple Nucleotide Polymorphisms (dbSNP 135) Found in >= 1% of Samples
    group varRep
    priority 99.0911
    visibility dense
    url https://www.ncbi.nlm.nih.gov/SNP/snp_ref.cgi?type=rs&rs=$$
    urlLabel dbSNP: 
    snpSeq snp135Seq
    snpExceptionDesc snp135ExceptionDesc
    defaultGeneTracks knownGene
    maxWindowToDraw 10000000
    type bed 6 +

This track displays variants from dbSNP build 135 with Minor Allele Frequency (MAF) of at least 1%. Flanking sequence file offsets come from the snp135Seq table, descriptions of unusual properties are taken from the snp135ExceptionDesc table, and effects of variants on protein-coding genes are shown with respect to the table knownGene (UCSC Genes track) by default. If the viewed region is more than 10,000,000 base pairs, the data will not be loaded and drawn.

vcfTabix: Variant Call Format indexed by tabix

Variant Call Format (VCF) is a flexible and extendable line-oriented text format developed by the 1000 Genomes Project for releases of single nucleotide variants, indels, copy number variants and structural variants discovered by the project. The format has been subsequently adopted by other large projects. When a VCF file is compressed and indexed using tabix and then made web-accessible, the Browser will fetch only the portions of the file necessary to display items in the viewed region. In other words, this is a remote data file format, as are the BAM, bigBed and bigWig formats. Please refer to the VCF and tabix track format page for a complete description of how to prepare and display VCF data.

type vcfTabix

Example can be found below.

hapClusterEnabled <true|false>

If the VCF file includes genotype columns for at least two individuals, then a haplotype sorting display is enabled by default. This option can be used to disable it if desired, for example if the genotypes have not been phased and a significant portion of the genotypes are heterozygous. More information about the haplotype sorting display can be found here.

hapClusterMethod <centerWeighted|fileOrder|treeFile url>

Assuming hapClusterEnabled is true, this specifies how genotypes are ordered for display:

centerWeighted: For diploid organisms, this separates the two haplotypes from each sample and dynamically clusters all haplotypes by similarity, weighted by proximity to a central variant. The clustering tree will be drawn in the left label area. This works best for phased genotypes.
fileOrder: Genotypes are displayed in the order in which they appear in the VCF file.
treeFile url: Genotypes are displayed in the order in which they appear in url, a Newick-formatted tree file whose leaf node IDs are the same as the genotype column IDs in the VCF file. The tree will be drawn in the left label area.

hapClusterColorBy <altOnly|function|refAlt|base>

Assuming hapClusterEnabled is true, this specifies one of three ways that reference and alternate alleles are colored:

altOnly: reference allele is white (invisible), alternate allele is black. This emphasizes haplotypes with alternate alleles. (default)
function: If the geneTrack setting is also provided, then reference allele is white (invisible) and alternate allele is red if the variant changes the protein sequence of a gene, green if the variant falls within a gene but does not change the protein sequence, blue if the variant falls within the UTR of a protein-coding gene or within a non-coding gene, and black if intronic or intergenic.
refAlt: reference allele is blue, alternate allele is red.
base: A is red, C is blue, G is green and T is magenta.

geneTrack <track>

This is for use with hapClusterColorBy function; it specifies the gene track to use when determining the functional effect of each variant.

hapClusterTreeAngle <triangle|rectangle>

Assuming hapClusterEnabled is true, this controls the shape of leaf clusters on the right of the tree (i.e. the lines drawn to denote groups of identical local haplotypes): triangle for the < shape (default), rectangle for the [ shape.

labelFields <fieldName[,fieldName]>

A list of fields from the bigBed based file that can be used as a label. The special value none can be specified if no labels are desired.

defaultLabelFields <fieldName[,fieldName]>

A list of fields from the bigBed based file that should be used as a label by default. Only applicable if labelFields is set. If defaultLabelFields is not specified, the first field in labelFields is used as the default. The special value none can be specified if no label should be the default.

labelSeparator <text>

One or more characters to use as the field separator between multiple labels. A slash (/) by default, this string can have double quotes around it if it should have white spaces in it.

showSnpWidth <integer>

The maximum width (in bases) of a window where the halSnake will show SNPs between the reference and the other species.

hapClusterHeight <N>

Assuming hapClusterEnabled is true, this specifies the height in pixels of the haplotype sorting display.

applyMinQual <true|false>

If true, then variants whose QUAL column contains a value less than the minQual setting will not be displayed.

minQual <Q>

Assuming applyMinQual is true, this is the minimum QUAL value required for a variant to be displayed.

minFreq <F>

The minimum minor allele frequency required for a variant to be displayed. By default this is 0.0 (i.e. display all variants).

vcfDoFilter <on/off>

Turn on/off the FILTER options available by default for VCF tracks

vcfDoQual <on/off>

Turns on/off the QUAL filter options available by default for VCF tracks

vcfDoMaf <on/off>

Turns on/off the Minor Allele Frequency filter options available by default for VCF tracks

Example of a VCF track

    track myVcf
    type vcfTabix
    bigDataUrl http://myorg.edu/mylab/myVcf.gz
    hapClusterEnabled false
    maxWindowToDraw 3000000
      ...

The data for this VCF track is stored in the remote file, "myVcf.gz". That file is paired with a tabix-generated index file named "myVcf.gz.tbi" found in the same remote location.

vcfPhasedTrio: VCF+tabix with extra metadata

After preparing a VCF file as noted in the VCF section, if your data contains information on trios, you may want to use the vcfPhasedTrio track type to obtain a haplotype display. For more information on this display, please see the VCF Trio documentation for a full explanation of the vcfPhasedTrio track type.

type vcfPhasedTrio

blah

vcfChildSample <sampleName|altName>

The VCF Genotype column ID of the "child" sample, followed optionally by a "|" character and an alias for the display. This sample will become the center haplotype if parents are also specified.

vcfParentSamples <sampleName|altName,sampleName|altName>

A comma separated (no spaces) list of the VCF Genotype column IDs of the "parents", followed optionally by a "|" character and an alias for the display. This setting is optinonal, and supports one or both parents.

vcfUseAltSampleNames <on/off>

Make the display use the aliases as the default labels for each haplotype lane instead of the ID from the VCF.

Example of a VCF Phased Trio track

    track myVcf
    type vcfPhasedTrio
    bigDataUrl http://myorg.edu/mylab/myVcf.gz
    vcfChildSample NA123456|son
    vcfParentSamples NA654321|mother,NA321654|father
    vcfUseAltSampleNames on
      ...

The data for this VCF track is stored in the remote file, "myVcf.gz". That file is paired with a tabix-generated index file named "myVcf.gz.tbi" found in the same remote location. "NA123456" is the ID of one of the Genotype columns in the VCF, and the parent haplotypes will displayed relative to their similarity to this sample.

pgSnp: Personal Genome SNP format

NOT FOR HUBS. (None of the settings in this section apply to hubs.)

This format is used to display SNPs from personal genomes. It is used for the Genome Variants and Population Variants tracks. Please refer to the FAQ for information on how to prepare personal genome SNP datasets.

type pgSnp

Personal Genome SNP type tracks are essentially in "bed 4 + 3" format. The fourth column, name, is filled with one or more variants (including insertions and deletions) delimited with a '/' character. The fifth column contains the number of variants found in the name column, while the sixth and seventh columns contain comma-delimited arrays of frequencies and scores respectively. Files in this format can be loaded into MariaDB with hgLoadBed using the "pgSnp.sql" schema.

The browser image displays variants as stacked boxes that show the frequency for each variant, if that information is in the table. The details page for each variant item computes any amino acid change if the variant is in a coding region.

pgPolyphenPredTab <table>

Not supported for custom tracks

Auxiliary table with likelihoods of variant damage to proteins from polyPhen.

pgSiftPredTab <table>

Not supported for custom tracks

Auxiliary table with likelihood of variant damage to proteins from SIFT.

Example of a Personal Genome SNP track

    track mySnps
    type pgSnp
      ...

A personal genome SNPs track displaying single nucleotide polymorphisms from the reference genome.

altGraphX: Alternate splicing gene model tracks

NOT FOR HUBS.

Gene models with alternate splicing can be displayed in the Browser with this type of track. It supports no trackDb settings beyond the common ones.

type altGraphX

Alternate slicing gene models specialized track used to show genome coverage.

Example of an altGraphX track

    track sibTxGraph
    shortLabel SIB Alt-Splicing
    type altGraphX
    url http://ccg.vital-it.ch/cgi-bin/tromer/tromergraph2draw.pl?species=H.+sapiens&tromer=$$
    urlLabel SIB link:
    idInUrlSql select name from sibTxGraph where id=%s
      ...

The Swiss Institute of Biology's alternative splicing track provides an external link via the url setting. But the actual "tromer" term in the value will be filled in with the results of a query to the sibTxGraph table. With enough obscure settings, the Browser accomplishes subtle things.

bedDetail: Text extended bed track

NOT FOR HUBS.

This is an extension of BED format. BED detail uses the first 4 to 12 columns of BED format, plus 2 additional fields that are used to enhance the track details pages. The first additional field is an ID, which can be used in place of the name field for creating links from the details pages. The second additional field is a description of the item, which can be a long description and can consist of html, including tables and lists.

type bedDetail <#>

Extended bed type format that has a text description embedded in the table for each item. The format can vary between 4 and 12 standard bed columns plus two additional ones. The number of columns (including the 2 bedDetail specific columns) must follow the "bedDetail" term in the type setting.

Example can be found below.

Example of a bedDetail track

    track microattrLoci
    type bedDetail 14
    itemRgb on
    url https://www.ncbi.nlm.nih.gov/entrez/viewer.fcgi?db=nucleotide&sendto=t&extrafeatpresent=1&list_uids=$$
      ...

This bedDetail contains details for each item formatted for HTML display. In addition each item has an "id" as distinct from the "name" and that id is used in the outside link url displayed in the item details page.

clonePos: Genome coverage tracks

NOT FOR HUBS.

This is a specialized format track that is only used for showing the coverage in the human genome. It supports no trackDb settings beyond the common ones.

type clonePos

A specialized track used to show genome coverage.

Example of a clonePos track

    track clonePos
    shortLabel Coverage
    longLabel Clone Coverage/Fragment Position
    type clonePos
    altColor 180,180,180
      ...

The Coverage track for the human genome will vary in color between black and light gray, based upon the cloned sequence coverage depth.

ctgPos: Physical map contigs tracks

NOT FOR HUBS.

This is a specialized format track that is used for "physical map contigs" on the human genome. It supports no trackDb settings beyond the common ones.

type ctgPos

A specialized track used to show the locations of contigs on the physical map.

Example of a ctgPos track

    track ctgPos2
    shortLabel GRC Map Contigs
    type ctgPos
    url none
      ...

The GCR Map Contigs track would normally generate a URL to NCBI, but in this case, the URL has been explicitly blocked.

downloadsOnly: Specialized track that contains only downloadable files

NOT FOR HUBS.

The ENCODE tracks all have a special directory and CGI support for downloading files. This can be very helpful for organizing access to the often very large number of downloadble files associated with an ENCODE track. There are a handful of datasets that don't readily lend themselves for visualization in our Browser but are nonetheless a necessary component of the ENCODE data as a whole. Therefore, downloadsOnly type was developed to provide easy access to these sets of downloadable files.

type downloadsOnly

A specialized track that provides access to a set of downloadable files, and is currently ENCODE only. A downloadsOnly type track does not get visualized in the Browser.

Example can be found below.

fileSortOrder ...

The fileSortOrder setting is required for downloadsOnly type tracks. A complete description can be found in composite tracks section of this document. It requires each file to be defined as an object in the metaDb and each of those objects to refer to a "composite" which will be the name of this track and the directory name where the files are located. The "fileSortOrder" defines the column and default sort order. The user will be able to sort and filter the list of files.

Example of a Downloads Only track

    track wgEncodeUmassWengTfbsValid
    type downloadsOnly
    fileSortOrder cell=Cell_Line \
                dccAccession=UCSC_Accession \
                fileSize=Size \
                fileType=File_Type \
                dateSubmitted=Submitted \
                dateUnrestricted=RESTRICTED<BR>Until
    wgEncode 1
      ...

The Browser will not provide visualization of this track but will provide access to downloading any number of files organized into a single group. The downloads page presents those files in a table with a number of columns that are sortable and possibly filterable. Much of the presentation and organization relies upon settings established in the metaDb for this track. However, the fileSortOrder setting has requested six specific columns to be presented in the desired order.

encodeFiveC: Five C Chromatin interaction track

NOT FOR HUBS.

This is a specialized format track that was used for displaying long distance chromatin/chromatin interaction evidence. Essentially a "bed" type track displaying locations in the genome. The details page of each location presents a list of other locations within the genome that may have functional interactions.

type encodeFiveC

A specialized track that was used to show the locations where chromatin may have interactions with other chromatin locations.

interTable <tableName>

Each location found in the track's main table should have associated regions defined in the interactions table named with this setting. The interactions table format is essentially a "bed 7 + 1".

interTableKind <label>

The table of interactions is presented on each item's details page and is titled as "Top ___ interactions"

Example of an encodeFiveC track

    track encodeUw5cGM06990dS9013DhsLoci
    type encodeFiveC
    color 200,100,0
    interTable encodeUw5cGM06990dS9013DhsInter
    interTableKind TSS
      ...

This Five C interactions track will be displayed as colored items. The associated chromatin regions are drawn from a second table. The kind of associations are transcription start sites.

factorSource: Combined items tracks

NOT FOR HUBS.

Factor source is not a group track, but a track that is made from a group of sources, which may themselves be Browser tracks. This is a specialized type of "item" based track of "bed 15" format, the same format used for type expRatio. Its purpose is to display transcription factors as detected in multiple cell lines, though it might be adaptable for any type of item that piles up into overlapping locations and will belong to one of several categories. However, this type was specifically designed for combining transcription factor (TF) binding evidence from multiple cell lines into a single track. As a bed type track, it consists of items or regions where there is evidence of TF binding. To the left of each item, the factor name is displayed, while to the right a coded list of cell types where the evidence has been found is displayed. Unlike most item-based tracks, a second table is required to describe the cell lines. Use the program hgBedsToBedExp to create the tables from a collection of simpler beds, one for each transcription factor/cell interaction.

type factorSource

A bed 15 based table format with overlapping items. This is a specialized track type designed for holding transcription factor binding evidence across multiple cell lines. The format is the same as used for microarray expression.

Example can be found below.

sourceTable <table>

The factorSource type tracks need a secondary table that holds descriptions of the sources. This is where cell line abbreviations are declared and associated with actual cell lines.

inputTrackTable <table>

When viewing the details for a factorSource track item (typically a TF binding site), additional information about the cell line evidence can be displayed. This setting names a table that will hold the additional information. It is used in conjunction with the inputTableFieldDisplay setting.

inputTableFieldDisplay <f1> [f2...]

If there is an inputTrackTable defined with your track, the fields that are to be displayed should be declared with this associated setting.

filterBy <field1:title=[+]option1a...>
                                [field2:title=[+]opt2a...]

This setting provides user filtering of factorSource items by factor name. The simplest use is to include a comma-separated list of all factor names in the track as an argument to the setting. A complete description of this setting can be found in the bed/bigBed item-based track settings.

motifTable <table>

A bed 6 table that holds motif regions to highlight within factorSource items.

motifMapTable <table>

If motif names differ from or are not unique for factorSource item names in the motifTable, this table can used to remap the names. This table has a simple 2 column format: char(255) factor, char(255) motif.

motifPwmTable <table>

When viewing the details of a factorSource track item containing a binding motif in the motifTable, the consensus motif sequence and sequence logo image can be displayed. This setting names the table holding the position weight matrices that provide this information.

motifMaxWindow <integer>

Display of highlighted motifs in a factorSource track can be limited using this setting. In large genomic regions motifs are not well distinguished in the display, and performance is improved by suppressing the feature.

motifDrawDefault <on/off>

If a factorSource track has a motifTable, this setting controls whether motifs are drawn by default. It is also configurable by the user.

Example of a factorSource track

track tfbsByCellLines
type factorSource
sourceTable myCellLines
inputTrackTable myCellLineAssociations
inputTableFieldDisplay cellType treatment lab
motifTable transfacMotif
motifPwmTable transfacMotifPwm
motifMapTable transfacMotifTarget
motifMaxWindow 30000
motifDrawDefault on
    ...

This track will show transcription factor (TF) binding evidence found in multiple cell lines. Each item represents a particular TF, along with the cell lines that show evidence of binding in that location. The secondary sourceTable holds the definitions of each cell line abbreviation. A third table is declared with inputTrackTable and carries details for each cell line that should be seen in the Browser. When viewed in item detail, 3 fields (cellType, treatment and lab) will be seen for each cell associated with the particular TF binding location.

rmsk: Repeat masking tracks

NOT FOR HUBS.

This is a specialized format track that is used only for the repeat-masking track. For completeness it is being briefly described here. These tracks are created created by using Arian Smit's RepeatMasker program, which screens DNA sequences for interspersed repeats and low complexity DNA sequences.

type rmsk

The repeat masker tracks contain uniquely formattted data for the special function of repeat-masking.

Example can be found below.

Example of a Repeat Masking track

    track rmsk
    spectrum on
    type rmsk
    maxWindowToDraw 10000000
      ...

The repeat masker track will have individual repeat items shaded by a measure of how exact a repeated element is withing the stretch of repetition. This track is restricted to display at less than 10 million base resolution.

snake: Self referencing alignment tracks - EXPERIMENTAL

NOT FOR HUBS.

This is a specialized format track that shows the snaking course of bi-directional and overlapping alignments. This format can help illustrate inversion-type rearrangements that align to the plus strand, then the minus strand, and again to the plus strand. It can also be used to illustrate overlapping alignments, such as when a duplication has occurred compared to the reference genome.

type snake <db>
otherDb <otherDb>

A specialized track used to show the path of snaking alignments that represent chromosomal rearrangements, duplications and inversions. Since this type is almost always a mapping between two species or two assemblies of the same species, the type must also declare that species/assembly by database name.

As with chains and netAligns, which typically show mappings between two assemblies, the "otherDb" setting is also needed to declare which other genome and assembly the data in this track represents.

Example of a snake track

    track snakeMm9
    type snake mm9
    otherDb mm9
    color 100,50,0
    altColor 255,240,200
    spectrum on
      ...

This snake track will illustrate chromosome rearrangements that have occurred on the mouse mm9 genome as seen when it is aligned to the human genome.

bigInteract: Pairwise interactions

The bigInteract format stores interactions between pairs of regions in the genome. BigInteract files are created using the program bedToBigBed with a special AutoSQL file that defines the fields. The resulting files are in an indexed binary format that supports efficient remote access, so the file can be hosted on your web accessible server and displayed at UCSC. For the complete bigInteract format definitions please see the bigInteract help page.

interactDirectional <true|offsetSource|offsetTarget|clusterSource|clusterTarget>

This setting is used when the interaction has an orientation (direction of effect). The offset setting shows the source (offsetSource) or target (offsetTarget) below the other end type; that is vertically displaced in the image. The interaction is drawn with dashed lines when the target region precedes the source region (reverse direction) in the genome.

The cluster setting collects all interactions with the same source (clusterSource) or target (clusterTarget) and displays each group as a single linked block display in the browser. This provides an alternate view of an interact file.

interactUp <true|false>

This setting flips the curved full visibility display so that the peak of the curves is 'up' (hills instead of valleys).

interactMultiRegion <true|padding>

This setting causes a link to appear on the details page that appears when an interaction is clicked on. This link will generate a "multi-region" Genome Browser view of the interaction (or interaction cluster) endpoints. Use padding to specify non-default padding at the edges of each region. The default value is 200 base pairs.

Example of an interact/bigInteract track

    track snpGeneInteractions
    type bigInteract
    interactDirectional true
    maxHeightPixels 300:150:20
    bigDataUrl http://...

bigLolly: Lollipop Charts

Lollipop graphs are usually used to display data that is local to a single base that has one to three data values assigned to it which can be displayed using the lollipop height, the color, and the size of the circle at the top of the lollipop. For examples visit the bigLolly help page.

Example of a bigLolly track

hic: Hi-C contact matrices

The hic track type is for displaying chromatin-chromatin interaction data via heat maps. Currently this track type supports one file format: the .hic file format created by the Aiden Lab at Baylor College of Medicine. This is an indexed binary format that supports remote access, so the file can be hosted on any web accessible server and displayed at UCSC. For more information on the .hic file format and the Juicer tool that generates these files, see the documentation on github.

drawMode <triangle|square|arc>

This setting controls the default display mode for the hic track. In arc mode, an interaction between two regions is drawn as an arc between the centers of those two regions. In square mode, interactions are represented by a square in a heatmap. The interacting regions for any square can be identified by projecting the sides of the square onto the diagonal axis of the heatmap and seeing where those points fall in the chromosome window being viewed. In triangle mode, interactions are drawn as diamonds. The interaction regions for any diamond can be identified by projecting the sides of the diamond onto the horizontal axis of the heatmap and seeing where those points fall in the chromosome window.

normalization <NONE|VC|VC_SQRT|KR>

This setting controls which method is the default for normalizing the raw scores from the .hic file. Scores for all of these methods are computed during the creation of the .hic file. For more information on these methods, see the Juicer documentation linked above.

resolution <Auto|integer>

This setting controls the default size of the bins that the Hi-C contact results are grouped into. The list of available resolutions depends on the file, but common values include numbers like 5000 and 10000. In addition to an integer value, the string Auto can also be provided (Auto is also the default if this setting is not specified). In Auto mode, the browser will dynamically choose a resolution that seems to provide a good amount of detail depending on the size of the chromosome window currently being viewed.

saturationScore <float>

The saturationScore setting is part of how the color shades of the heatmap are displayed. Colors in the heatmap correlate with the score of each interaction - a higher interaction score corresponds to a higher color intensity. At some point, however, maximum color saturation is reached and higher interaction scores don't change the color any further. This setting determines what the default score is for the point at which that maximum color saturation is reached.

hicDistanceMin <integer>

Hi-C tracks have a setting that controls the minimum interaction distance in nucleotides for the heatmap. If a portion of the heatmap represents an interaction closer than the value of the minimum distance setting, that portion of the heatmap simply isn't drawn. This setting, hicDistanceMin, controls the default value for that minimum (without this setting, the default is 0). A value of 0 means that no filter is applied.

hicDistanceMax <integer>

Hi-C tracks have a setting that controls the maximum interaction distance in nucleotides for the heatmap. If a portion of the heatmap represents an interaction farther than the value of the maximum distance setting, that portion of the heatmap simply isn't drawn. This setting, hicDistanceMax, controls the default value for that maximum (without this setting, the default is 0). A value of 0 means that no filter is applied.

Example of a hic track

    track myHiCData
    type hic
    drawMode arc
    color 0,0,255
    saturationScore 12
    normalization KR
    bigDataUrl http://...

bigBarChart: Bar charts of variables displayed on genomic regions

The bigBarChart format stores values of a set of variables for each genomic region in the file. BigBarChart files are created using the program bedToBigBed with a special AutoSQL file that defines the fields. The resulting files are in an indexed binary format that supports efficient remote access, so the file can be hosted on your web accessible server and displayed at UCSC. For the complete bigBarChart format definitions please see the bigBarChart help page.

barChartBars <label1 label2...>

This setting is a list of labels for the categorical variables (bars). It is required for this track type.

barChartUnit <unit>

The unit label is attached to values in the display, charts and plots of the track.

barChartLabel <label>

This setting provides a label for the category selection list.

barChartMaxSize <small/medium/large>

BarChart track display selects one of three sizes (small, medium, or large) to display barCharts, based on size of the genomic region in the current window. For dense data, it is helpful to reduce the barChart sizes, even when in relatively small genomic regions. This setting limits the size of the largest barChart to the selected value. When unset, the default value is "large".

barChartSizeWindows <largeMax> <smallMin>

This setting provides a way to choose the basepair thresholds which determine the barChart sizes (small, medium, or large charts). The default basepair window size is 50000 and 500000 bases, which is intended for one chart per gene in vertebrate genomes. This setting can be used to flexibly customize chart sizes based on the basepair window size being visualized when densely annotating a sequence.

large	window size < largeMax
medium	window size >= largeMax and < smallMin
small	window size >= smallMin

Example:

   barChartSizeWindows 500 8000

In this example, used when displaying barCharts on a 30,000 basepair viral genome, large charts appear in windows up to 499 bases, medium in windows from 500 to 7999 in size, and small when 8000 or more bases are shown in browser window.

barChartStretchToItem on

This setting extends the barCharts to cover the entire horizontal space available in the graph. This setting is typically used with bar charts with large number of bars so that it is possible to zoom in to see better the individual bars.

barChartMetric <metric>

This setting provides a label for details page information about the barChart values presented. These are typically summary values, derived from many samples (often the median value).

barChartColors <color1 color2...>

This setting is a list of colors, one for each category (bar). Colors are specified as RGB values (255,255,255 or #FFFFFF) or by name (the 16 HTML color names defined in HTML 4.01). The named HTML colors are:

black,

silver,

gray,

white,

maroon,

red,

purple,

fuchsia,

green,

lime,

olive,

yellow,

navy,

blue,

teal,

aqua.

barChartMatrixUrl <url>

Specifies a data matrix file that provides data values for all samples. Used together with barChartSampleUrl to generate a box plot on the details page.

barChartSampleUrl <url>

Specifies a tab-separated file that provides categories for samples in the barChartMatrixUrl file. Used for generating a box plot on the details page.

barChartCategoryUrl <url>

Specifies a tab-separated file that provides labels and optionally colors for the categories (bars). This setting can replace the barChartBars and barChartColors settings, and is particularly useful for tracks with large numbers of categories.

barChartFacets <column1,column2,...columnN>

This setting turns on the faceted selection on the track details and configure page which is useful for selecting which bars out of a large number to display. It works with the barChartStatsUrl. The comma-separated list of columns refer to column names in the tab-separated-value file specified by barChartStatsUrl. See an example with images of barChartFacets on the barChart help page.

barChartStatsUrl <url>

This setting associates a table in tab-separated-values with the barchart, with one line per bar. The first line of the file contains the table column names. The first column contains the name of the bar. The other columns can be in any order. If a color column is present it will be used for the colors of the bars using the hexadecimal #RRGGBB format. (Currently the same names and colors should also be specified in a URL associated with barChartCategoriesUrl tag.) The count column is required, and contains the number of samples represented in the bar. Other columns can contain additional data associated with each bar. Typically these are used in coordination with the barChartsFacets tag to specify metadata such as cell types or tissue of origin. See an example with images of barChartStatsUrl on the barChart help page.

barChartMerge on

This setting enables the merge button inside of the faceted selections. It is particularly useful when there are many bars and many facets. It allows bars that differ only in that one facet to be merged together. See an example with images of barChartMerge on the barChart help page.

barChartBarMinPadding <num>

Sets the minimum pixel width between bars to <num> pixels. Typically, this padding is a dynamic calculation dependent on the current window size, the width of the item, and the number of bars for the item. If present, the maximum of this setting and the dynamically calculated padding is used for the display. See an example with images of barChartBarMinPadding on the barChart help page.

barChartBarMinWidth <num>

Sets the minimum pixel width of the bars in the chart to <num> pixels. Typically, this width is a dynamic calculation dependent on the current window size, the width of the item, and the number of bars for the item. If present, the maximum of this setting and the dynamically calculated width is used for the display. See an example with images of barChartBarMinWidth on the barChart help page.

Example of a bigBarChart track

    track brainRegionRna
    type bigBarChart
    maxLimit 8000
    barChartUnit RPKM
    barChartLabel Brain Regions
    barChartMetric median
    barChartBars Amygdala Cerebellum Cortex Hippocampus
    barChartColors #ff0000 0,255,0 maroon navy
    shortLabel Brain RNA
    longLabel Brain Gene Expression
    spectrum on
    labelFields gene, name
    defaultLabelFields gene
    bigDataUrl http://...
    barChartMatrixUrl http://...
    barChartSampleUrl http://...

Predefined major track groupings

NOT FOR HUBS.

The simplest grouping:

group <groupId>

All tracks belong to one of several groups. Hub tracks belong to the group that encompasses their hub. Other tracks belong to one of the predefined groups. For hg19 the following groups are defined:

map - "Mapping and Sequence"
phenDis - "Phenotype and Disease Associations"
genes - "Genes and Gene Prediction"
rna - "mRNA and EST"
expression - "Expression"
regulation - "Regulation"
compGeno - "Comparative Genomics"
neandertal - "Neandertal Assembly and Analysis"
varRep - "Variation and Repeats"

If no group is set for a built-in track, then the track will end up in the Experimental Tracks section at the bottom.

Example of a track belonging to a predefined group

    track myTrack
    group regulation
      ...

Supertrack settings

The first hierarchical container is called the supertrack, which may be thought of as a folder that holds other tracks that by default are closed, unless the setting show is added. The Browser currently supports only one level of supertrack folders. Generally the subtracks of a supertrack are of differing types. If all the children are of the same type, it is often better to use the compositeTrack grouping described below. If all of the children are wig or bigWig tracks, it may be of interest to use a signal overlay "container multiWig" grouping. Signal overlay tracks display the signal data from several subtracks as colored transparencies, making it possible to see the data of several tracks together in a condensed view. See the multiWig section for more information.

Supertracks can contain composite tracks and container multiWigs, but not vice versa. With supertracks, composite tracks, and container multiWigs, children will inherit the settings from their parents, but can override their parent settings within their own stanzas.

superTrack on show

To declare a supertrack, simply add this setting to a track definition that will hold a few standard settings. To set a supertrack to display as default add the word show, superTrack on show, to the end of the statement. To have the supertrack not display by default use only superTrack on. It may help to think of the original declaring supertrack stanza as a light switch that by default is off, and can be flipped on by adding show.

All tracks that claim membership to the supertrack should set their own visibilities in lower stanzas by declaring settings such as parent superTrack1 and also by having a separate visibility dense line. If no visibility setting is defined for a track, the default setting of hide is assigned. This can cause confusion if one mistakenly tries to set visibilities only at the top supertack stanza, not allowed, and leaves them out for each child.

Do not confuse the parent line with how it is used in composites. For example, in supertracks DO NOT follow the example of ~~parent superTrack1 [off/on]~~, where [off/on] will only work with composite tracks. When attempting to debug visibility settings, it may be helpful to read the note about inheritance found below.

parent <superTrack>

Membership in a supertrack, composite, or aggregate track is declared by the child, not the supertrack itself with a line such as parent superTrack1.

Do not confuse the parent line with how it is used in composites. For example, in supertracks DO NOT follow the example of parent compositeTrack1 [off/on], which will only work with composite tracks.

Any number of children may belong to one supertrack, but ten is a suggested number for usability considerations. Stylistically, children's stanzas within the trackDB typically are indented directly under the stanza of the parent. However, this is less frequently the case with supertracks, because the children are often scattered in other places within the trackDb file, or the supertrack children are themselves composites containing additional indentation that makes enforcement of the supertrack indentation impractical.

All tracks that claim membership to the supertrack should set their own visibilities in lower stanzas by declaring separate settings such as visibility dense.When attempting to debug visibility settings, it may be helpful to read the note about inheritance found below.

Example of a Supertrack

Example 1

    track myFolder
    superTrack on show
    shortLabel My Folder
    longLabel My folder keeps my tracks together
      ...

        track myFirstTrack
        parent myFolder
        visibility dense
          ...

        track mySecondTrack
        parent myFolder
        visibility hide
          ...

The track called "My Folder" is declared as a supertrack and contains two children who claim membership with parent lines. Notice that the first track, track myFirstTrack, is visible by default with visibility dense (because the supertrack itself, myFolder, has the light-switch-like setting of show to display all the contents of the supertrack). The second track, track mySecondTrack, is not displayed, however, with visibility hide and will require clicking a box on the Track Setting page to display.

Note: do not confuse the parent line with how it is used in composites. For example, in supertracks DO NOT follow the example of ~~parent superTrack1 [off/on]~~, which will only work with composite tracks. See the Quick Start Guide to Organizing Track Hubs into Groupings for more examples.

Composite Tracks

Composite tracks are another level of hierarchy and are meant to group very similar tracks (called "subtracks") together such that they can all share the same configuration settings. In its simplest form a composite holds tracks all of the same type (such as bigBed). Initially, all track within the set are configured identically. Usually only some of the subtracks are visible by default, and these will have the same display mode (e.g., dense) and optional settings (e.g., viewLimits). While default settings cover the entire composite of related tracks, in most cases individual subtracks can be configured by the user independently of the composite settings. However, once individual subtrack settings are made, they can be overridden by new choices made at the composite level. It may be helpful to read the "Note about inheritance" found below.

Currently only the following track types can be organized into a composite: item-based tracks (bed, bigBeg, broadPeaks, etc.), signal-based tracks (wig, bigWig, etc.), other remote file-based tracks (bams, vcf, etc.), chains/nets, genePred, psl, and wigMaf-type tracks.

Composite Tracks

compositeTrack on

To declare a composite, simply add this setting to a track definition, along with a few standard settings. The subtrack stanzas always follow immediately after the composite track delaration and are indented from it.

Note that since children of composites inherit their parent's settings, many more trackDb settings will be found at the composite level than at the supertrack level.

parent <composite> [off/on]

Membership in a composite is declared by the subtrack child, not the composite itself, through this setting. Any number of subtracks may belong to one composite, but display performance degrades significantly beyond a few hundred. Set the parent setting to "on" to indicate whether a subtrack should be visible (checked, selected) by default. Visibility settings in composite subtracks are directly inherited from the parent. Therefore, any visibility lines added at the child subtrack level of a composite will be ignored.

allButtonPair on

When a simple composite track presents a short list of subtracks, it can be convenient for the user to have an easy way to select or deselect all of them. Include this setting to display an "All " (plus and minus button pair) for the user's convenience. If the list contains more than 10 subtracks, other methods may be more useful for organizing and selecting subtracks (described below).

centerLabelsDense <off/on>

By default, only the composite track's single center label is shown when the subtracks are displayed together in the Browser dense mode. If centerLabelsDense is set to "on", the Browser will display a center label for each subtrack.

dragAndDrop subTracks

When you have many subtracks in a composite track, it may be useful on the Track Setting page, also known as the hgTrackUi configuration page, to rearrange the subtracks. One avenue of rearranging many subtracks is to employ the sortOrder setting, as described below, or by allowing the user to drag and drop the subtracks to a new order on the Track Setting page. The dragAndDrop subTracks setting will enable dragging by clicking on the check mark next to the subtrack on the configuration page. Tracks can thereby be rearranged into a final desired order, that will then be seen when browsing the tracks. However, the order of tracks can also be rearranged on the hgTracks Browser image by directly dragging and dropping the displayed track data. Yet reordering subtracks in the Browser image in hgTracks will not be reflected back on the hgTrackUi configuration page. Note: This setting will not work correctly if 'container multiWig' is specified.

hideEmptySubtracks <on/off>

When you have many subtracks in a composite track, it may be useful to limit the display to only those with data in the current viewing window. This track setting produces a checkbox on the track configuration page allowing the user to enable or disable this feature. if on is specified, the feature is on by default (the checkbox is checked).

hideEmptySubtracksMultiBedUrl file.bb

For large composites, especially those where each subtrack may be sparse, substantial performance improvements can be gained by creating an index file of the intersections of items in all subtracks ("multiBed"). This file, and an accompanying sources file, are optional settings for the hideEmptySubtracks feature. Instructions for creating these files are at the MultiBed help page (TBD).

NOTE: These settings are required to use the hideEmptySubtracks feature with multi-view composites.

hideEmptySubtracksSourcesUrl file.tab

This setting is used in conjunction with the hideEmptySubtracksMultiBedUrl setting, described above.

hideEmptySubtracksLabel <label>

This setting is used in conjunction with the hideEmptySubtracks setting to customize the label preceding the selection checkbox on the track configuration page. Default wording is "Hide empty subtracks". Custom wording is useful to distinguish affected tracks in multi-view composites (e.g. "Hide empty Peaks subtracks").

Example of a Composite track

    track myComposite
    compositeTrack on
    parent myFolder
    shortLabel My Composite
    type bigWig 0 1.0
    viewLimits 0.0:0.2
    allButtonPair on
      ...

        track myFirstSubtrack
        parent myComposite on
          ...

        track mySecondSubtrack
        parent myComposite
          ...

The composite with two subtracks shown. All subtracks are of type bigWig and all have a default viewLimits of 0 - 0.2. Notice the first subtrack is checked by default, but the second is not (parent setting). However, the Browser will display two buttons (allButtonPair setting) that allow the user to select all subtracks, or deselect all of them and then check only those of interest.

Subgroups

Within a composite track, two different grouping styles can be used to allow the user to select tracks for display in the Browser. This section describes the configuration of "subgroups"; "views" are discussed in a subsequent section.

The subgroup can be used for selecting sets of subtracks for display based on certain characteristics of the data. For instance, if "cell" and "antibody" are defined as subgroups within a composite track, the user will be able to select subtracks based on specific cell types and antibodies to display in the Browser. Up to 9 subgroup types can be defined for a composite. However, to minimize the complexity, it is strongly recommended that only two subgroups be defined for a given composite track. These will be presented in a simple X/Y matrix that is easy for the user to understand and navigate. It is possible to define more subgroups in additional "abc" dimensions that will be presented to the user as drop-down multi-select dialogs, but use of these should be avoided or minimized.

subGroup1 <gTag1> <gTitle1> <mTag1a=mTitle1a>
                        [mTag1b=mTitle1b…]

subGroup2 <gTag2> <gTitle2> <mTag2a=mTitle2a>
                        [mTag2b= mTitle2b…]

Up to 9 subgroups may be declared, one per line. Each subgroup declaration must include a whitespace-delimited tag, title, and one or more tag/title membership pairs joined by an '=' equals sign.

tag: Used in the code to select and sort subtracks based upon their membership. Tag names must be alphanumeric, begin with a letter, not contain a period, and be formed such that the desired sort order of the member subtracks will result.
title: Label of the subgroup as it appears on the selection matrix that is displayed to the user, e.g.,"Antibody". Spaces within titles must be replaced by '_'. A limited amount of HTML is allowed in titles, such as the insertion of Greek letters using an HTML code. Any use of HTML should be tested to ensure that it displays correctly.

Because subgroup settings are often lengthy, it is recommended that the '\' line continuation character be used to break up the setting over multiple lines for easier reading.

subGroups <gTag1=mTag1?> [gTag2= mTag2?]

The subtracks themselves declare their membership in a group with the subGroups setting. Each subtrack must declare its membership in all of its composite's subgroups. Notice that membership is declared by pairs of tags: the group tag (e.g. gTag1) is paired with that group's member tag (e.g. mTag1b) as gTag1=mTag1b (cell=K562).

dimensions <dimX=gTag#> [dimY=gTag#] [dimA=gTag# ...]

In order to define the type of UI desired for selecting subtracks based upon groups, additional settings are needed at the composite level. For a one- or two-dimensional array of checkboxes, declare the dimensions X and Y. Additional dimensions (called "abc") can be declared with this setting as dimA, dimB, etc.

Note that the order of the subgroups in a dimension is exactly the same as the order they appear in the subGroup# setting, regardless of whether the subtrack list is sorted by tags. Please also note that if a hub is not going to use the X,Y matrix, dimX should be the first dimension defined rather than dimA. Also, the setting allButtonPair on will prevent the matrix from displaying.

filterComposite <dim[A/B/C][=one]> [dimB dimC ...]

For the "abc" dimensions, rows of checkboxes will be shown by default. However, this UI can be confusing, especially combined with a one- or two-dimensional matrix. Instead, it is recommended that you organize "abc" dimensions as drop-down multi-selects, often referred to as "filter" boxes due to their similarity to the filterBy setting discussed above. Declare the subtrack filter boxes with the filterComposite setting. Filter composites may work with or without the X/Y matrix, but are restricted to the "abc" dimensions.

By default, the filter box for selecting subtracks is multi-select, meaning more than one choice is allowed. It is possible to restrict this to a single choice by adding the "=one" option to the filter box definition. This might make sense when there are only 2 choices. The choice of "all" is always available, while choosing nothing is an invalid case. Please note that if a hub is not going to use the X,Y matrix, then dimX should be the first dimension defined rather than dimA.

dimension<?>checked <mTag1a>
                                [mTag1b …]

One more complication in the selection process is determining which subgroup options are selected by default. In the case of the X/Y matrix this can be determined by what subtracks are currently checked. But, "abc" dimensions must have their selected state declared explicitly using the dimension<?>checked setting.

controlledVocabulary <pathToFile> <gTag#=mdbVar>
                            [gTag#=mdbVar …]

NOT FOR HUBS. Currently used only by ENCODE

In ENCODE, subgroups are often based on metadata terms declared in the metaDb table and defined in the "controlled vocabulary", which is stored as an ra file. In this situation, the labels of these terms, as they are displayed in the track configuration page, can be linked to the controlled vocabulary definitions. These links can be quite useful, as the term definition may include protocol documents and validation evidence. In order to establish the links, each subGroup's tag must be tied to the actual metaDb term.

sortOrder <gTag#=+/-> [gTag#=- …]

When declaring subgroups, it is often useful to sort the subtrack list by those subgroups. By including a sortOrder setting, long sets of subtracks are more easily organized and navigated by the user. If there are only a few subtracks in the composite, sorting may be of little value and dragAndDrop may be a better option. Currently only subgroups can be defined in the sortOrder, but it is anticipated that this will expand to include short and long labels as well. Sorting will occur on the tag values defined in the subGroup# and subGroups settings. By sorting on tags, non-alphanumeric orders can be defined.

fileSortOrder <var=val> [var=val ...]

NOT FOR HUBS. Currently used only by ENCODE

Some composite track sets have their own directories of downloadable files and a special CGI for accessing those files. In order to see the CGI interface for the download directory, the composite needs an object for each file defined in the metaDb. The trackDb stanza for the composite also needs to have the fileSortOrder setting defined. The setting is defined as a set of variable=value pairs, which defines the default sort order on metaDb variables. The "var" portion of the each pair is a term defined in the metaDb for all of the file objects in the directory. The "var" may also be "fileType" or "fileSize", which are not defined in the metaDb. The "val" is the title that the user will see as the column header for the sortable table of files. This value can contain and '_' for spaces and limited HTML codes and special characters. As always, you are encouraged to experiment. The '\' continuation character should be used to break up this long setting into readable lines.

Examples of Composite tracks with Subgroups

    track myComposite
    compositeTrack on
    subGroup1 cellLine Cell_Line \
            A1GM12=GM12878 \
            CD14=CD14+ …
    subGroup2 ab Antibody \
            H3K04ME3=H3K4me3 \
            H3K36ME3=H3K36me3 …
    dimensions dimX=ab dimY=cellLine
    sortOrder cell=+ ab=+
      ...

        track myFirstSubtrack
        parent myComposite on
        subGroups cellLine=CD14 ab=H3K04ME3
          ...

This examples shows a composite with one subtrack and two subgroups. The dimensions setting declares X and Y dimensions, which will display a 2D matrix on the composite's configuration page. Notice that the title of the cellLine subgroup contains a blank space filled in with '_'. The second cell line, "CD14+", includes an HTML encoding for '+' in its title, The two subgroups participate in the default sort order of subtracks, but they each have non-standard sort orders. In the cellLine subgroup, GM12878 sorts first by starting its tag with "A". The antibodies have numbers in their titles, but the tags expand the number with "0" to pad the spacing. This ensures H3K4me3 sorts before H3K36me3.

    track myCompositeIs3D
    compositeTrack on
    subGroup1 cellLine Cell_Line \
            A1GM12=GM12878 \
            CD14=CD14+ …
    subGroup2 ab Antibody \
            H3K04ME3=H3K4me3 \
            H3K36ME3=H3K36me3 …
    subGroup3 treat Treatment \
            TNFA=TNF-alpha \
            ZNONE=None …
    dimensions dimX=ab dimY=cellLine dimA=treat
    filterComposite dimA
    dimensionAchecked ZNONE
    controlledVocabulary encode/cv.ra cellLine=cell \
                                    ab=antibody \
                                    treat=treatment
    sortOrder cell=+ ab=+ treat=-
    fileSortOrder cell=Cell_Line \
                antibody=Antibody \
                fileSize=Size
      ...

        track myFirstSubtrackIn3D
        parent myCompositeIs3D on
        subGroups cellLine=CD14 ab=H3K04ME3 treat=ZNONE
          ...

In this second example composite, one subtrack and three subgroups are shown. As in the previous example, the dimensions setting declares X and Y dimensions, resulting in a 2D matrix of "Antibody" and "Cell Line" options. A third "Treatment" subgroup is declared as the "A" dimension; the user will be able to select subtracks for this dimension via a dropdown multi-select filter box. All three subgroups participate in the default sort order of subtracks, and the treatment subgroup is sorted in reverse order by default. The "None" treatment sorts before all others (in reverse order) by beginning the tag with a "Z". Note that for this "A" dimension, the "None" treatment will be selected by default. By declaring the proper settings, using subGroups to organize a composite can be quite powerful.

This example illustrates that subgroups, dimensions, and (in the case of ENCODE) controlled vocabulary and metadata all must be linked together for the composite to fully work. Further, the actual terms, programmatic "tags" and user visible titles all have different constraints and roles to play in establishing this cohesion. Subgroup tags are used to organize subtracks, while lettered dimensions organize the configuration page to more easily select subgroups of subtracks. For ENCODE tracks, the subgroups may be represented as metadata "terms" (distinct from tags) that are often carefully defined by a controlled vocabulary. In the example above, the tag "ab" is used to organize subtracks into subgroups but is also tied to dimension X. This ensures that antibodies will appear as the horizontal dimension in the 2D matrix on the configuration page, and the selection of an antibody will select the associated subtracks. Of course the user does not see the antibody as "ab" but "Antibody". Going further, the term as defined in controlled vocabulary is "antibody", so that for all the tables and files associated with this composite track, their metaDb objects should contain an "antibody" var and a given antibody (e.g. H3K4me3) will be found in the controlled vocabulary with a validation document. All the relationships can be confusing, but the trackDb settings, if done correctly, can tie all these elements together in a nice cohesive package.

Examples of Composite tracks with Subgroups

    track myComposite
    compositeTrack on
    subGroup1 cellLine Cell_Line \
            A1GM12=GM12878 \
            CD14=CD14+ …
    subGroup2 ab Antibody \
            H3K04ME3=H3K4me3 \
            H3K36ME3=H3K36me3 …
    dimensions dimX=ab dimY=cellLine
    sortOrder cell=+ ab=+
      ...

        track myFirstSubtrack
        parent myComposite on
        subGroups cellLine=CD14 ab=H3K04ME3
          ...

    track myCompositeIs3D
    compositeTrack on
    subGroup1 cellLine Cell_Line \
            A1GM12=GM12878 \
            CD14=CD14+ …
    subGroup2 ab Antibody \
            H3K04ME3=H3K4me3 \
            H3K36ME3=H3K36me3 …
    subGroup3 treat Treatment \
            TNFA=TNF-alpha \
            ZNONE=None …
    dimensions dimX=ab dimY=cellLine dimA=treat
    filterComposite dimA
    dimensionAchecked ZNONE
    sortOrder cell=+ ab=+ treat=-
      ...

        track myFirstSubtrackIn3D
        parent myCompositeIs3D on
        subGroups cellLine=CD14 ab=H3K04ME3 treat=ZNONE
          ...

Views

In addition to subgroups, a single composite can be divided into multiple "views". Recall that a composite should be made up of subtracks of the same type. However, different types of subtracks can be combined into the same composite track if they are in separate "views". While views are like subgroups in many ways, they can carry their own settings. This is necessary because the views within a composite may be for different types that have their own distinct configuration settings, for example bigBeds and bigWigs.

The "view" (or "multi-view") organization is typically used when the same basic data is stored in multiple formats and granularities. For example, a collection of views may include short read sequence alignments (type bam), signals representing pile-ups of aligned reads (type bigWig), and the peaks (type bigBed) that are called in regions where the evidence of experimental result is deemed significant. These three "views" of the same experimental data can be seen more informatively as a cohesive set within a multi-view composite track.

Views are declared both as a subgroup and as a separate track stanza. A composite with multiple views has only views as children, and each view will have one or more subtracks as children. The three levels must be defined together with indenting to make the hierarchy obvious.

A note about inheritance. Subtracks will inherit settings from their parents (both from composites and from views). This is true when the setting is inheritable, which is generally the case. Obvious exceptions are settings that are relevant only to the higher level. Inheritance follows the "closest to home" paradigm in which a setting at the subtrack level takes precedence, followed by the view level setting, and finally the composite level setting. This inheritance applies to both the trackDb default settings and the choices made by a user. Settings made by the user involve a timing element as well: a change to a parent-level setting will override all settings of the same type for its children. If the user subsequently makes a subtrack setting, it will override the inherited setting for that one subtrack.

An anomaly within the inheritance scheme is the "visibility" (display mode) setting. Unlike other settings, visibility is cumulatively restrictive from the supertrack level. That is, if the parent has a visibility of "dense" and the child's visibility is "pack", the child will be displayed as "dense". If the parent is subsequently changed to "full" display mode, the child will now be shown in "pack" mode. At the trackDb level, default visibility is always cumulatively restrictive. However, when a user explicitly changes a subtrack visibility to be greater than what was inherited from parents, that subtrack's visibility will override the inheritance. While the subtleties of inheritance can be hard to explain, they are often intuitive in practice. In composite subtracks, visibility settings are directly inherited from the parent composite, therefore, any visibility lines added at the child subtrack level of a composite will be ignored. Also note the parent line should be referenced as parent myComposite on if one desires the child subtrack in a composite to be visible (checked, selected) by default.

subGroup1 view <Views> <vTag1a=vTitle1a> [vTag1b=vTitle1b…]
track <viewName>
view <viewTag>

A view is always declared both as a subgroup and in a track stanza itself. The subgroup declaration is like previous declarations, but the view subgroup must have the tag view and be declared as the first subgroup. Note that the view stanza follows the composite stanza with one level of indentation. Subtracks will follow their view with an additional level of indentation.

subGroups view=<vTag1>…
parent <viewName> [off/on]

A subtrack declares its membership in a view both as subgroup membership and with a parent setting that refers to the view track name. Note that a track can only have one parent. When the subtrack's parent is a view, the composite track is its implicit grandparent.

viewUi on

If subtracks within a view are configurable, then the view will have the configuration controls for it in a box beneath the view's visibility drop down. That box filled with configuration controls is hidden by default so that the UI is not too cluttered. The user must first open the box before its contents are seen. If there is only one view with configuration settings, or if the view is the most important one, the box can be open by default. Use this setting in the view stanza of settings to default the configuration box as open.

configurable <off/on>

Tracks are configurable by default if their track type supports this, and views and composites are configurable if their children's track type supports this. Finally individual subtracks are configurable by default if their track type supports it. Sometimes it is desirable to turn off configuration. Configuration may be turned back on when it has been turned off at a higher level. For example, this might be useful in a situation with a multi-view composite where the composite level would normally be configurable, but you want only one of the views and not all of the children of that view to be configurable. While this setting might be rarely needed, it can help restrict the user from viewing your data in inappropriate ways.

Example of a Composite track with Views

    track myMultiViewComposite
    compositeTrack on
    visibility dense
    subGroup1 view Views PK=Peaks SIG=Signals
    subGroup2 cell Cell_Line \
            A1GM12=GM12878 \
            CD14=CD14+ …
    subGroup3 ab Antibody \
            H3K04ME3=H3K4me3 \
            H3K36ME3=H3K36me3 …
    dimensions dimX=ab dimY=cell
    sortOrder cell=+ ab=+ view=+
    type bed 3
      ...

        track myViewPeaks
        parent myMultiViewComposite
        shortLabel Peaks
        view PK
        visibility pack
        type bigBed 6 +
        scoreFilter 0
        scoreFilterLimits 0:1000
        viewUi on
          ...

            track myFirstPeakSubtrack
            parent myViewPeaks on
            subGroups cell=CD14 ab=H3K04ME3 view=PK
              ...

The composite has two views, one of which is shown, along with a single subtrack belonging to that view. Notice that the view does not participate in the dimensions setting, as it is an implicit dimension controlled by a row of visibility dialogs at the top of the composite configuration page. Notice that the view does participate in the sortOrder setting like other subgroups. In this example, the peaks view contains bigBed subtracks that all share the scoreFilter defaults defined at the view level. Almost any setting that is common to the whole tree can be defined at the composite level; any setting that is common to the view can be set at the view level; and any setting that is specific to one subtrack should be set at that level. Remembering inheritance, we can see that the subtrack shown inherits its track type from the view, but has its default visibility limited by the composite. That is, it inherits packed visibility from the view but the composite will show all visible subtracks as dense.

One additional thing to note is that this composite track is "type bed 3". Composites do not need a type to define their data format, since all data is associated with subtracks. Further, multi-view composites almost always have multiple data formats. But the "type" also controls what configuration options may be offered for a track. Typically, a single level composite has the same type as all of its subtracks and offers user configuration options at the top level. But a multi-view composite is most often given the bare-bones "type bed 3", and offers user configuration options at the view level. Exceptions to this pattern do exist but they are rare.

Aggregate or Overlay Tracks: multiWig

In some instances, data from multiple tracks is so closely related that it makes sense to view it as a single track. The premiere example of this is the signal overlay track (i.e. "multiWig"). Signal overlay tracks display the signal data from several subtracks combined in several different ways, making it possible to see the data of several tracks together in a condensed view. The default overlay method for multiWigs is as colored transparencies, in which all the graphs are drawn on top of one other in such a way that overlapping regions are a different color. Another choice is solid overlay, where all the graphs are still drawn overlapping each other, but without transparency. A third choice is stacked where the values of the subtracks are stacked on top of one another with no overlap such that the total height of the wiggle is the sum of all the values in the subtracks. The value of the overlay track surpasses simply condensing the image. Occasionally this is the most effective way to identify hidden relationships in the underlying data. The overlay track should not be overused, however. Attempts to overlay too many subtracks can hide important information as regions with many layered signals become too dark to interpret. More than eight subtracks in a single overlay may prove less than ideal. As with composites, it is important for the multiWig tracks to have the same data dimensions, i.e. a signal height of 100 should be interpretable in the same way for the whole set of tracks. While this is true for a composite or view, it is especially important for overlay tracks. You cannot reasonably overlay a signal from 0-1 with another signal from 0-1000.

container multiWig

Signal overlay tracks are declared much like simple composites. However, instead of a "composite" setting, they declare themselves as a "container" of "type multiWig". Like simple composites, all subtrack types should be identical and the container itself should be declared as the same type (e.g. "bigWig"). Also like a composite, the container parent should have common settings for all children. Unlike composites, containers can have neither subgroups nor views. Additionally, all subtracks within a container are configured as one; there is no independent configuration of individual subtracks. Even when the user sets the overlay method to none and the subtracks are viewed as separate signals, they are still configured as a set.

parent <containerTrack>

Membership in a container track is declared at the subtrack level. The subtracks should be defined with indent beneath their container parent.

aggregate <transparentOverlay/stacked/solidOverlay/none>

It is important to declare an aggregation method; otherwise, this set of tracks displays as a composite would, with additional restrictions. Of the four options, the preferred setting is transparentOverlay. The setting stacked will draw the graphs in stacked mode. The setting solidOverlay should not be used if there are more than a couple of tracks, and none should never be the default. The aggregation method is a configurable option, however, so the user may wish to temporarily set it to none in order to see subtleties hidden in overlay mode.

showSubtrackColorOnUi on

Subtracks in an overlay have individual colors. Use this setting to show the color associated with each on the track configuration page.

Example of an Aggregate track

    track myMultiWig
    container multiWig
    aggregate transparentOverlay
    showSubtrackColorOnUi on
    type bigWig 0 1000
    viewLimits 0:10
    maxHeighPixels 100:32:8
      ...

        track myFirstOverlaySig
        table myFirstWig
        parent myMultiWig
        color 255,128,128
        wig 0 1139
          ...

        track myFirstBigWig
        parent myMultiWig
        color 120,235,204
          ...

This container is for a transparent overlay of signal tracks with 2 subtracks shown. The tracks are of type "bigWig", though the first subtrack is a wig. Such mixtures are allowed. Notice that the wig has a slightly larger range than the others. The signal dimensions are close enough in this case, and the default viewLimit applied to all subtracks suggests that any signal above 10 is interpreted as strong. Note that each subtrack must define its color, and in this example, that color will be seen in the track configuration page as well as in the image. Also notice that the first subtrack declares a table as distinct from its track name. Usually the table (or remote file root) name is the same as the track name. The track name is a unique key. But it is frequently the case that a table or remote data file may be displayed as an individual track or subtrack, as well as part of a signal overlay track. Setting the table name here suggests that a track named "myFirstWig" also exists and is displaying the same data used in this overlay track.

Example of an Aggregate track

    track myMultiWig
    container multiWig
    aggregate transparentOverlay
    showSubtrackColorOnUi on
    type bigWig 0 1000
    viewLimits 0:10
    maxHeighPixels 100:32:8
      ...

        track myFirstOverlaySig
        parent myMultiWig
        color 255,128,128
        type bigWig 0 1139
          ...

        track myFirstBigWig
        parent myMultiWig
        color 120,235,204
          ...

This container is for a transparent overlay of signal tracks with 2 subtracks shown. The tracks are of type "bigWig". Notice that the first subtrack has a slightly larger range than the others. The signal dimensions are close enough in this case, and the default viewLimit applied to all subtracks suggests that any signal above 10 is interpreted as strong. Note that each subtrack must define its color, and in this example, that color will be seen in the track configuration page as well as in the image.

Custom Tracks

NOT FOR HUBS.

Custom tracks are tracks that get loaded into the Browser through the hgCustom CGI. Unlike locally hosted tracks, or even Data Hub tracks, they do not have a trackDb.ra stanza to define their format and behavior in the Browser. Nevertheless, they will support most of the settings as a locally hosted track of the same type. There are a few additional settings that are needed to fully support custom tracks.

genome

Filled with genome/assembly db name.

offset

Used only once, to apply an offset to bed type data of a custom track.

browserLines

Internal only – user does not set. Filled with all trackDb.ra style lines from hgCustom input.

dataUrl

Internal only – user does not set. Filled if custom tracks is loaded via URL.

dbTrackType

Internal only – user does not set.

Not sure how it is distinguished from tdbType.

fieldCount

Internal only – user does not set. Filled with number of bed columns as determined in hgCustom CGI.

firstItemPos

Internal only – user does not set. Filled with first bed item in bedList in hgCustom CGI.

htmlFile

Internal only – user does not set. Filled with name if trash file that contains HTML description for custom track.

htmlUrl

Internal only – user does not set. Filled with user entered URL for track

initialPos

Internal only – user does not set. Filled with position from hgCustom input.

inputType

Internal only – user does not set. Filled with custom factory name as determined in hgCustom CGI.

itemCount

Internal only – user does not set. Filled with bed item slCount in hgCustom CGI.

mafFile

Internal only – user does not set. Filled with name of trash file that contains maf data as loaded in hgCustom CGI.

maxChromName

Internal only – user does not set. Obsolete: Filled with minimum index size for db that won't "smoosh" together chromNames.

origTrackLine

Internal only – user does not set. Filled with "track" line as entered by user in hgCustom CGI.

tdbType

Internal only – user does not set.

Holds the type that should go into tdb->type.

wibFile

Internal only – user does not set. Filled with name of trash file that contains wib binary data as loaded in hgCustom CGI.

wigFile

Internal only – user does not set. Filled with name of trash file that contains wig data as loaded in hgCustom CGI.