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 MySQL
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 Settings |
---|
track |
type |
shortLabel |
longLabel |
visibility |
html |
Many settings are valid only for certain types of tracks. These track types are described below along with the settings specific to their types.
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, maxWindowToDraw, showDiffBasesAllScales, showDiffBasesMaxZoom |
Examples of genePred tracks
|
bam - Compressed Sequence Alignment track settings |
---|
type bam |
bigDataUrl <url/relativePath> |
Related settings:
bamColorMode <strand/gray/tag/off> |
bamGrayMode <aliQual/baseQual/unpaired> aliQualRange <min:max> baseQualRange <min:max> |
bamColorTag <XX> |
noColorTag . |
bamSkipPrintQualScore . |
indelDoubleInsert <off/on> indelQueryInsert <off/on> indelPolyA <off/on> |
minAliQual <#> |
Related settings:
pairEndsByName . |
pairSearchRange <#> |
showNames <on/off> |
Additional settings found in the "Item or region tracks" section are also available for displaying bam tags. baseColorUseSequence, baseColorDefault, maxWindowToDraw, showDiffBasesAllScales, showDiffBasesMaxZoom |
Example for bam 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> |
Related settings:
hapClusterEnabled <true|false> |
hapClusterColorBy <altOnly|refAlt|base> |
hapClusterTreeAngle <triangle|rectangle> |
hapClusterHeight <N> |
Related settings:
applyMinQual <true|false> |
minQual <Q> |
minFreq <F> |
Additional settings found in the "Item or region tracks" section are also available for displaying Variant Call Format tracks. maxWindowToDraw |
Example of a VCF track:
|
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, maxWindowToDraw, showCdsAllScales, showCdsMaxZoom, showDiffBasesAllScales, showDiffBasesMaxZoom, spectrum |
Examples of psl alignment 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. maxWindowToDraw |
Example of a snp track:
|
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, urlLabelTODO: 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:
|
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:
|
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:
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 |
Example of a Composite track:
|
Aggregate or Overlay track settings |
---|
container multiWig |
parent <containerTrack> |
aggregate <transparentOverlay/stacked/solidOverlay/none> |
showSubtrackColorOnUi on |
Example of an Aggregate track:
|
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
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, 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:
|
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 MySQL 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:
|
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 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. |