0e4e0c0af65eea70f64edbc68348ce0972c4bbf4 braney Fri Aug 28 16:45:00 2026 -0700 Correct the track types listed for trackDb settings, and the hub settings list The "For Types" list in the trackDb docs was wrong for about sixty settings, so the docs named the wrong track types for settings that have always worked. Most named only the older type and left out its big* counterpart. The clearest case is the multiple-alignment family: a bigMaf track is drawn and configured by the same code as a wigMaf track, but only speciesOrder said so, while irows, itemFirstCharCase, speciesGroups, speciesCodonDefault, speciesDefaultOff, treeImage, pairwiseHeight and speciesUseFile all claimed wigMaf alone. The hapCluster settings said vcf and not vcfTabix. noScoreFilter said bed while its own example uses type bigBed 6 +. Six settings said "all" for something that only works on item tracks. Two documented settings do not exist. pslSequence describes a variable that was replaced by the baseColor family long before the setting was listed, and nothing has read either spelling since; it is removed. noStems is renamed to lollyNoStems, which is what the Browser actually reads. That one mattered: hubCheck builds its list of valid settings from trackDbHub.html, so it accepted the spelling that does nothing and rejected the one that works. Fourteen settings that work in hubs had no entry in the hub spec, so hubCheck reported them as unrecognized. They are listed now: chainColor, chainNormScoreAvailable, pairwiseHeight, barChartMatrixUrl, mouseOverFunction, intronGap, filterBy, baseColorTickColor, speciesGroups, speciesDefaultOff, speciesCodonDefault, itemFirstCharCase, irows, and canPack with configureByPopup and origAssembly. The last three, along with filterBy and baseColorTickColor, were marked "NOT FOR HUBS", which was wrong: the Browser reads them from a hub's trackDb the same way it reads them from ours. The type setting on the hub page listed every type the Browser knows, including ones that only work for tracks loaded into our own databases. It now shows only the types a hub can use. A hub-specific blurb for this already existed and had never been referenced. Three settings had no blurb at all, so the generated trackDbSettings.json never saw them: metadata, noInherit and useScore. Written, and the five hand-written copies in trackDbDoc.html that had drifted from the library are brought back into line. The library's header told the reader to always check their work in trackDbTestBlurbs.html, which was deleted in November 2025. It now points at "make settings" instead. That target regenerates trackDbSettings.yaml and .json, which are updated here, and its name map gains an entry so the hub-specific type blurb is still keyed as "type". refs #37908 diff --git src/hg/htdocs/goldenPath/help/trackDb/changes.html src/hg/htdocs/goldenPath/help/trackDb/changes.html index 62ba038339b..a91db488194 100755 --- src/hg/htdocs/goldenPath/help/trackDb/changes.html +++ src/hg/htdocs/goldenPath/help/trackDb/changes.html @@ -1,233 +1,332 @@ UCSC Track Database Definition History
  Track Database Definition Change History

Track Database Definition

This document summarizes the changes to the UCSC Genome Browser Hub TrackDb specification.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Date Track Types Link to Doc Change
2026-08-28bigLollylollyNoStemsRenamed in the documentation, from noStems. The Browser has always + read lollyNoStems, so a track that set noStems drew its + stems as usual. hubCheck takes its list of valid settings from this + page, so it accepted the spelling that did nothing and rejected the one that works. + If your hub sets noStems, change it to lollyNoStems.
2026-08-28alltypeThe list of valid types on this page now shows only the types a hub can use. + It had been showing the full list, which includes types that only work for tracks + loaded into our own databases. The three hub types missing from the shorter list, + bigGenePred, bigNarrowPeak and vcfPhasedTrio, + have been added.
2026-08-28allcanPack, + configureByPopup, + origAssemblyNow listed on this page, and no longer marked as unavailable to hubs. The Browser + reads all three from a hub's trackDb the same way it reads them from ours, so the old + note was wrong. canPack is still marked deprecated: the track type + usually decides whether pack and squish are offered, so you rarely need to set it.
2026-08-28bigMaf, bigGenePredspeciesGroups, + speciesDefaultOff, + speciesCodonDefault, + itemFirstCharCase, + irows, + intronGapNow listed on this page. A bigMaf track is drawn and configured by the same code + as a wigMaf track, so the five multiple-alignment settings have always worked on it, + but only speciesOrder was documented that way. intronGap is + read for every track type that draws linked features, bigGenePred included. Nothing + about their behavior changed.
2026-08-28bigBed, bigGenePred, bigPsl, bigLollyfilterByNow listed on this page, and no longer marked as unavailable to hubs. The + Browser applies filterBy to bigBed-backed tracks when it loads them, so + it has worked in hubs for some time. If you avoided it because of the old note, you + can use it now.
2026-08-28bigBed, bigPslbaseColorTickColorNow listed on this page, and no longer marked as unavailable to hubs. It has + always worked in hubs. The entry now also states the requirement that was missing: + the tick color is worked out from each item's own color, so the setting does nothing + unless the track sets colorByStrand. itemRgb does not + satisfy it.
2026-08-28bigChain, bigMaf, bigBarChart, bigWigchainColor, + chainNormScoreAvailable, + pairwiseHeight, + barChartMatrixUrl, + mouseOverFunctionNow listed on this page. All five have worked in hubs for years, but none had an + entry here, so hubCheck reported them as unrecognized settings. + Nothing about their behavior changed.
2026-08-28bigBed, bigGenePred, bigPsl, bigChain, bigNarrowPeak, bigMaf, vcfTabixspectrum and 25 othersDocumentation fix: the "For Types" list was wrong for 26 settings, so the docs + named the wrong track types for settings that have always worked. Most named only the + older type and left out its big* counterpart, for example + noScoreFilter said bed while its own example uses + type bigBed 6 +, and the hapCluster* settings said + vcf and not vcfTabix. Six others said "all" for a setting + that only works on item tracks. No browser behavior changed.
2026-08-28bigPslpslSequenceRemoved. This setting has never done anything. The variable it described was + replaced by the baseColorUseSequence + family long before the setting was listed here. Use + baseColorUseSequence and + baseColorDefault instead.
2026-07-31 faceted composite maxCheckboxes Documentation fix: this setting was previously listed here as maxCheckBoxes, with a capital B. Setting names are case sensitive and the browser has always read it as maxCheckboxes, so hubs that used the capitalized spelling fell back to the default of 20 facet values. If your hub sets maxCheckBoxes, change it to maxCheckboxes.
2026-07-08 genomes.txt setting codonTable New codonTable genome-stanza setting (an assembly hub genomes.txt setting, not a track setting) assigns NCBI genetic codes to individual sequences for amino acid display, e.g. codonTable default=1 NC_017929.1=13. Affects the base position track three-frame translation, codon-colored tracks such as gene predictions, and details pages. Sequences named chrM/chrMT still default to the vertebrate mitochondrial code.
2026-06-02 bigBed, bigGenePred colorFields New colorFields setting adds a Color by: dropdown to the track controls page, letting users switch among multiple pre-computed color schemes stored as extra bigBed fields containing R,G,B strings. The special name default="label" renames the standard itemRgb option. When a non-default scheme is selected, a (Coloring by: label) suffix appears in the track long label.
2026-05-08 bed, bigBed filterPriority / highlightPriority New filterPriority.<fieldName> setting controls the display order of filter controls on the track configuration page. A companion highlightPriority.<fieldName> setting orders highlight controls.
2026-04-22 faceted composite tracks subtrackUrls An update for the subtrackUrls option for faceted composites, which enables links out to other resources in the faceted table.
2026-04-10 vcf, vcfTabix, vcfPhasedTrio sampleMetadataFile Add per-sample metadata columns to the VCF genotype details table. Points to a tab-separated file with a #sample header line; columns are appended to the genotype table on the item details page.
2026-04-08 bigBed detailsScript Add custom JavaScript visualizations (e.g. histograms) to the item details page. An ES6 module is loaded on demand and renders into the extra fields table. First plot type: histogram, for logfmt-encoded allele frequency data.
2026-03-09 bigBed faceted composite An alternate UI for composite tracks with a very large number of subtracks.
2026-01-12 bigBed style Activates the positional heatmap display mode for a track that meets the schema.
2026-01-11 hic hicArcLimit Limit the number of arcs displayed in a Hi-C plot, favoring those with the highest scores
2025-03-31 interact, bigInteract detailBoxesEnabled Used to suppress the link/boxes in interact tracks that would go to a details page.
2025-03-06 hic bigDataUrl Added hic to the list of supported file types for bigDataUrl.
2024-06-11 bigBed, bigGenePred, bigChain, bigPsl highlightValues.* Allow user to highlight certain features in yellow, if they contain certain values in an extraField
2024-01-22 bigWig setColorWith Color a signal plot from a bigWig file by the ranges in a bigBed file
2023-11-08 bigBed, bigGenePred, bigChain, bigPsl decorator.* Semi-transparently overlay annotations, e.g. protein domains on transcripts, mutations on exons, or summits on chip-seq peaks
2023-10-16 bigGenePred, bigChain, bigPsl mouseOver, mouseOverField mouseOver works for all bigBed-based file formats
2023-06-27 all maxItems Change: maxItems, increased default to 10,000, 10x more items can be shown.
2023-04-04 all downloadUrl New: downloadUrl <fileType> <URL>
Shows a link where user can download a file. On the UCSC browser, the link is shown above the description page. Right now this is used for GFF files on gene tracks.
2022-09-30 bigBed, BAM doWiggle New: doWiggle on
Instead of showing the features, show coverage of features, as a 'wiggle' (signal) style track. Can be switched off by the user on the track config page.
2022-09-22 bigGenePred colorByStrand Change: colorByStrand can now be used by bigGenePred-type tracks.
2022-06-30 bigPsl, bigChain otherTwoBitUrl New: otherTwoBitUrl <URL>
This statement allows one to store query sequences in a separate twoBit file rather than in the annotation file itself, which can reduce the size of the annotation file.
2022-05-14 bigWig logo New: logo on
Motif logo of the genome sequence, as a "dynseq" display, see the example.
2022-05-11 genomes.txt setting chromAuthority New chromAuthority genome-stanza setting (an assembly hub genomes.txt setting, not a track setting) chooses which chromAlias name column is displayed by default for the assembly's sequences, e.g. chromAuthority ucsc.
2022-05-05 bigMaf, maf logoMaf New: logoMaf on
Motif logo on MAF/bigMaf alignment tracks. Zooming in on alignment shows nucleotides scaled by phyloP conservation.
2019-05 all useOneFile useOneFile on
Adding the 'useOneFile on' line to the hub.txt section of a hub allows the contents of all three files to be referenced inside of one file.