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 @@ -33,30 +33,129 @@ <DIV class="trackDbDoc_intro"> <H1>Track Database Definition</H1> <p>This document summarizes the changes to the <a href="trackDbHub.html">UCSC Genome Browser Hub TrackDb specification</a>.<p> <TABLE class="settingsTable" id="Common_Settings"> <tbody> <tr valign="TOP"> <th width="100">Date</th> <th width="15%">Track Types</th> <th width="15%">Link to Doc</th> <th>Change</th> </tr> +<tr> + <td>2026-08-28</td> + <td>bigLolly</td> + <td><a href="trackDbHub.html#lollyNoStems">lollyNoStems</a></td> + <td>Renamed in the documentation, from <code>noStems</code>. The Browser has always + read <code>lollyNoStems</code>, so a track that set <code>noStems</code> drew its + stems as usual. <code>hubCheck</code> 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 <code>noStems</code>, change it to <code>lollyNoStems</code>.</td> +</tr> +<tr> + <td>2026-08-28</td> + <td>all</td> + <td><a href="trackDbHub.html#type">type</a></td> + <td>The 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, + <code>bigGenePred</code>, <code>bigNarrowPeak</code> and <code>vcfPhasedTrio</code>, + have been added.</td> +</tr> +<tr> + <td>2026-08-28</td> + <td>all</td> + <td><a href="trackDbHub.html#canPack">canPack</a>, + <a href="trackDbHub.html#configureByPopup">configureByPopup</a>, + <a href="trackDbHub.html#origAssembly">origAssembly</a></td> + <td>Now 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. <code>canPack</code> is still marked deprecated: the track type + usually decides whether pack and squish are offered, so you rarely need to set it.</td> +</tr> +<tr> + <td>2026-08-28</td> + <td>bigMaf, bigGenePred</td> + <td><a href="trackDbHub.html#speciesGroups">speciesGroups</a>, + <a href="trackDbHub.html#speciesDefaultOff">speciesDefaultOff</a>, + <a href="trackDbHub.html#speciesCodonDefault">speciesCodonDefault</a>, + <a href="trackDbHub.html#itemFirstCharCase">itemFirstCharCase</a>, + <a href="trackDbHub.html#irows">irows</a>, + <a href="trackDbHub.html#intronGap">intronGap</a></td> + <td>Now 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 <code>speciesOrder</code> was documented that way. <code>intronGap</code> is + read for every track type that draws linked features, bigGenePred included. Nothing + about their behavior changed.</td> +</tr> +<tr> + <td>2026-08-28</td> + <td>bigBed, bigGenePred, bigPsl, bigLolly</td> + <td><a href="trackDbHub.html#filterBy">filterBy</a></td> + <td>Now listed on this page, and no longer marked as unavailable to hubs. The + Browser applies <code>filterBy</code> 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.</td> +</tr> +<tr> + <td>2026-08-28</td> + <td>bigBed, bigPsl</td> + <td><a href="trackDbHub.html#baseColorTickColor">baseColorTickColor</a></td> + <td>Now 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 <code>colorByStrand</code>. <code>itemRgb</code> does not + satisfy it.</td> +</tr> +<tr> + <td>2026-08-28</td> + <td>bigChain, bigMaf, bigBarChart, bigWig</td> + <td><a href="trackDbHub.html#chainColor">chainColor</a>, + <a href="trackDbHub.html#chainNormScoreAvailable">chainNormScoreAvailable</a>, + <a href="trackDbHub.html#pairwiseHeight">pairwiseHeight</a>, + <a href="trackDbHub.html#barChartMatrixUrl">barChartMatrixUrl</a>, + <a href="trackDbHub.html#mouseOverFunction">mouseOverFunction</a></td> + <td>Now listed on this page. All five have worked in hubs for years, but none had an + entry here, so <code>hubCheck</code> reported them as unrecognized settings. + Nothing about their behavior changed.</td> +</tr> +<tr> + <td>2026-08-28</td> + <td>bigBed, bigGenePred, bigPsl, bigChain, bigNarrowPeak, bigMaf, vcfTabix</td> + <td><a href="trackDbHub.html#spectrum">spectrum</a> and 25 others</td> + <td>Documentation 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 <code>big*</code> counterpart, for example + <code>noScoreFilter</code> said <code>bed</code> while its own example uses + <code>type bigBed 6 +</code>, and the <code>hapCluster*</code> settings said + <code>vcf</code> and not <code>vcfTabix</code>. Six others said "all" for a setting + that only works on item tracks. No browser behavior changed.</td> +</tr> +<tr> + <td>2026-08-28</td> + <td>bigPsl</td> + <td>pslSequence</td> + <td>Removed. This setting has never done anything. The variable it described was + replaced by the <a href="trackDbHub.html#baseColorUseSequence">baseColorUseSequence</a> + family long before the setting was listed here. Use + <code>baseColorUseSequence</code> and + <a href="trackDbHub.html#baseColorDefault">baseColorDefault</a> instead.</td> +</tr> <tr> <td>2026-07-31</td> <td>faceted composite</td> <td><a href="trackDbHub.html#maxCheckboxes">maxCheckboxes</a></td> <td>Documentation fix: this setting was previously listed here as <code>maxCheckBoxes</code>, with a capital B. Setting names are case sensitive and the browser has always read it as <code>maxCheckboxes</code>, so hubs that used the capitalized spelling fell back to the default of 20 facet values. If your hub sets <code>maxCheckBoxes</code>, change it to <code>maxCheckboxes</code>.</td> </tr> <tr> <td>2026-07-08</td> <td><b>genomes.txt setting</b></td> <td><a href="trackDbHub.html#codonTable">codonTable</a></td> <td>New <code>codonTable</code> genome-stanza setting (an assembly hub