679b48855a32f8ea1e1ea8ca3c095a0c2c7f6c7a max Tue Sep 8 10:08:41 2026 -0700 detailsScript: add a scatterPlot plot type, and use it for pcLAI Clicking a pcLAI window now shows where that window sits in the ancestry space it was placed in: a scatterplot of the 1000 Genomes reference haplotypes with the window's own PCA coordinate and its segment's coordinate marked on it. The numbers were already on the details page and told a reader almost nothing. New plot type scatterPlot (hg/js/hgc.scatterPlot.js), driven the same way as histogram. Background points come from a JSON or TSV file named by dataUrl and may carry a category, which colors them and builds a legend, and a label, which is shown on mouseover. The cloud is drawn on a canvas, since these files hold thousands of points and that many <circle> elements make the page crawl; axes and the highlighted points stay SVG on top. Point lookup for the mouseover goes through a cell index so a large file stays smooth. Two additions serve every plot type, not just this one: - exportFields, a config key listing further bigBed fields whose values are passed to the module as a fieldValues object. Without it a plot needing two coordinates would need them packed into one field, and pcLAI keeps them in pca and pcaSegment. Only fields that exist in the bigBed are exported, at most 32, and the JSON types are checked rather than asserted because jsonListVal and jsonStringVal errAbort and this JSON is written by a hub. - a config key ending in Url is treated as a file, by the convention trackSettingIsFile() already uses, and a relative one is resolved against the track's own bigDataUrl. The module does not fetch it directly; it asks hgTrackUi for it, the route facetedComposite uses for its metadata. That checks the canonicalized path against the hubs on the cart and reads it with udc, so a hub-relative path works even for a hub loaded from a local path (the GenArk /gbdb hubs), no CORS header is needed, and a file outside a connected hub cannot be read. Verified that /etc/passwd, file://, a dot-dot escape, an unattached hub and an unrelated host are all refused with 400. When the session has file caching off, hgc now exports udcTimeout the way hgTrackUi does and the module POSTs, so the browser cannot answer from cache. Fixes a crash reachable from any hub: "detailsScript.<plotType>.<field> null" segfaulted hgc, because jsonObjectVal returns NULL for a JSON null and the hash routines dereference it. This hit the shipped histogram type too. trackDbSettingsGen.py stopped reading a setting's description at the first "Example:" paragraph and never read <ul> at all, so it dropped everything after the first example and every list item. That silently truncated 226 of the 264 descriptions, including spectrum's minGrayLevel/scoreMin/scoreMax bullets, and would have dropped this whole scatterPlot section. It now skips the Example label instead of stopping, and folds list items in. No setting loses a word and none gains or loses an example. pcLAI wiring: the background file is the authors' published reference panel (github.com/AI-sandbox/hprc-pclai reference_pca_metadata.tsv), converted by hprc2annotMakePclaiRefPanel.py -- 3122 haplotypes, 21 populations, 94 KB, one file for the collection since it is the reference space rather than per-assembly data. The four values pcaSegment takes across all 460 assemblies turn out to be the four continental cluster centres, so the highlighted segment dot always lands on one of them. genark: addContrib now rewrites a "...Url" inside a detailsScript value the same way it rewrites bigDataUrl, and symlinks the collection's shared root-level data files next to the docs, so contrib/<name>/<file> resolves in the deeper GenArk layout. It writes the alpha tier only, leaving the assembly's default hub alone, and clears any unmarked copy of the collection's stanzas that the assembly build baked in, which would otherwise leave the hub declaring each track twice. refs #35415 diff --git src/hg/htdocs/goldenPath/help/trackDb/changes.html src/hg/htdocs/goldenPath/help/trackDb/changes.html index f3b99c2075f..ab2646d648a 100755 --- src/hg/htdocs/goldenPath/help/trackDb/changes.html +++ src/hg/htdocs/goldenPath/help/trackDb/changes.html @@ -1,373 +1,386 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <HTML> <HEAD> <META HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=iso-8859-1"> <META name="description" content="UCSC Track Database Definition Changes"> <META name="keywords" content="tracDb, tracks, UCSC, bioinformatics"> <TITLE>UCSC Track Database Definition History</TITLE> <LINK REL="STYLESHEET" HREF="/style/HGStyle.css"> <LINK REL="STYLESHEET" HREF="trackDbDoc.css"> <script type="text/javascript" src="/js/jquery.js"></script> <script type="text/javascript" src="/js/staticDoc.js"></script> <script type="text/javascript" src="/js/utils.js"></script> <script type="text/javascript" src="trackDbDoc.js"></script> </HEAD> <BODY> <A NAME="TOP"></A> <!-- Format everthing inside this narrower "pageWidth" window --> <div class="pageWidth"> <!--#include virtual="../../../cgi-bin/hgMenubar"--> <!--Content Tables--> <!--outer table is for border purposes--> <div class="contentBorder"> <div class="lightBlueBar"> <div class="lightBlueBarTitle"> Track Database Definition Change History</div> </div> <!-- Finally to the content --> <div class="borderGuard"> <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-09-08</td> + <td>bigBed</td> + <td><a href="trackDbHub.html#detailsScript">detailsScript</a></td> + <td>New plot type <code>scatterPlot</code>, which draws a cloud of background points + from a JSON or TSV file named by <code>dataUrl</code> and marks the clicked item's own + coordinates on it. Background points can carry a category, which colors them and builds + a legend, and a label, which is shown on mouseover. Also new for every plot type: the + <code>exportFields</code> config key, listing further bigBed fields whose values are + passed to the module, and hub-relative resolution of any config key ending in + <code>Url</code>. Such a file is read server-side and must sit inside a connected + hub.</td> +</tr> <tr> <td>2026-09-06</td> <td>bigNet</td> <td><a href="trackDbHub.html#bigNet_-_Alignment_Nets">bigNet</a></td> <td>New track type. <code>bigNet</code> holds an alignment net in a bigBed file, so a track hub can show a real net instead of a net rendered as a maf. The type line is <code>type bigNet targetDb chainTrack</code>, where <code>chainTrack</code> names the <a href="/goldenPath/help/bigChain.html">bigChain</a> track in the same hub that holds the alignments. See the <a href="/goldenPath/help/bigNet.html">bigNet format description</a>.</td> </tr> <tr> <td>2026-08-31</td> <td>bigPsl, bigGenePred, bigBarChart, bigLolly</td> <td><a href="trackDbHub.html#searchIndex">searchIndex</a>, <a href="trackDbHub.html#searchTrix">searchTrix</a>, <a href="trackDbHub.html#mouseOver">mouseOver</a>, <a href="trackDbHub.html#mouseOverField">mouseOverField</a>, <a href="trackDbHub.html#indelDoubleInsert">indelDoubleInsert</a>, <a href="trackDbHub.html#indelQueryInsert">indelQueryInsert</a>, <a href="trackDbHub.html#indelPolyA">indelPolyA</a></td> <td>Documentation fix, continuing the "For Types" corrections below. Each of these settings works on types its entry did not name. <code>searchIndex</code> gains <code>bigPsl</code>, <code>bigGenePred</code> and <code>bigBarChart</code>, and <code>searchTrix</code> gains <code>bigGenePred</code>; both are read on the bigBed-backed search path, whatever the flavor. <code>mouseOver</code> and <code>mouseOverField</code> gain <code>bigLolly</code>. The three <code>indel*</code> settings named only <code>bam</code> in the library, though this page has listed them under <code>bigPsl</code> for years; they are read for every track that draws linked features, so <code>psl</code> and <code>bigPsl</code> are named now. <code>searchIndex</code> and <code>searchTrix</code> also drop <code>bed</code>, which never worked: a track in one of our own database tables configures search through the <code>hgFindSpec</code> table instead. No browser behavior changed.</td> </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><a href="trackDbHub.html#pslSequence">pslSequence</a></td> <td>Marked deprecated. 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: <code>pslSequence all</code> is now <code>baseColorDefault itemBases</code>, and <code>pslSequence different</code> is now <code>baseColorDefault diffBases</code>. The entry is kept rather than deleted so that <code>hubCheck</code> tells you the setting is deprecated, instead of reporting it as an unrecognized setting and guessing at a typo.</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 <code>genomes.txt</code> setting, not a track setting) assigns NCBI genetic codes to individual sequences for amino acid display, e.g. <code>codonTable default=1 NC_017929.1=13</code>. 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.</td> </tr> <tr> <td>2026-06-02</td> <td>bigBed, bigGenePred</td> <td><a href="trackDbHub.html#colorFields">colorFields</a></td> <td>New <code>colorFields</code> setting adds a <b>Color by:</b> dropdown to the track controls page, letting users switch among multiple pre-computed color schemes stored as extra bigBed fields containing <code>R,G,B</code> strings. The special name <code>default="label"</code> renames the standard itemRgb option. When a non-default scheme is selected, a <em>(Coloring by: label)</em> suffix appears in the track long label.</td> </tr> <tr> <td>2026-05-08</td> <td>bed, bigBed</td> <td><a href="trackDbHub.html#filterPriority">filterPriority</a> / <a href="trackDbHub.html#highlightPriority">highlightPriority</a></td> <td>New <code>filterPriority.<fieldName></code> setting controls the display order of filter controls on the track configuration page. A companion <code>highlightPriority.<fieldName></code> setting orders highlight controls.</td> </tr> <tr> <td>2026-04-22</td> <td>faceted composite tracks</td> <td><a href="trackDbHub.html#subtrackUrls">subtrackUrls</a></td> <td>An update for the subtrackUrls option for faceted composites, which enables links out to other resources in the faceted table.</td> </tr> <tr> <td>2026-04-10</td> <td>vcf, vcfTabix, vcfPhasedTrio</td> <td><a href="trackDbHub.html#sampleMetadataFile">sampleMetadataFile</a></td> <td>Add per-sample metadata columns to the VCF genotype details table. Points to a tab-separated file with a <code>#sample</code> header line; columns are appended to the genotype table on the item details page.</td> </tr> <tr> <td>2026-04-08</td> <td>bigBed</td> <td><a href="trackDbHub.html#detailsScript">detailsScript</a></td> <td>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.</td> </tr> <tr> <td>2026-03-09</td> <td>bigBed</td> <td><a href="trackDbHub.html#faceted_composite">faceted composite</a></td> <td>An alternate UI for composite tracks with a very large number of subtracks.</td> </tr> <tr> <td>2026-01-12</td> <td>bigBed</td> <td><a href="trackDbHub.html#style">style</a></td> <td>Activates the positional heatmap display mode for a track that meets the schema.</td> </tr> <tr> <td>2026-01-11</td> <td>hic</td> <td><a href="trackDbHub.html#hicArcLimit">hicArcLimit</a></td> <td>Limit the number of arcs displayed in a Hi-C plot, favoring those with the highest scores</td> </tr> <tr> <td>2025-03-31</td> <td>interact, bigInteract</td> <td><a href="trackDbHub.html#detailBoxesEnabled">detailBoxesEnabled</a></td> <td>Used to suppress the link/boxes in interact tracks that would go to a details page.</td> </tr> <tr> <td>2025-03-06</td> <td>hic</td> <td><a href="trackDbHub.html#bigDataUrl">bigDataUrl</a></td> <td>Added hic to the list of supported file types for bigDataUrl.</td> </tr> <tr> <td>2024-06-11</td> <td>bigBed, bigGenePred, bigChain, bigPsl</td> <td><a href="trackDbHub.html#highlight">highlightValues.*</a></td> <td>Allow user to highlight certain features in yellow, if they contain certain values in an extraField</td> </tr> <tr> <td>2024-01-22</td> <td>bigWig</td> <td><a href="trackDbHub.html#setColorWith">setColorWith</a></td> <td>Color a signal plot from a bigWig file by the ranges in a bigBed file</td> </tr> <tr> <td>2023-11-08</td> <td>bigBed, bigGenePred, bigChain, bigPsl</td> <td><a href="../decorator.html">decorator.*</a></td> <td>Semi-transparently overlay annotations, e.g. protein domains on transcripts, mutations on exons, or summits on chip-seq peaks</td> </tr> <tr> <td>2023-10-16</td> <td>bigGenePred, bigChain, bigPsl</td> <td><a href="../decorator.html">mouseOver, mouseOverField</a></td> <td>mouseOver works for all bigBed-based file formats</td> </tr> <tr> <td>2023-06-27</td> <td>all</td> <td><a href="trackDbHub.html#maxItems">maxItems</a></td> <td>Change: <tt>maxItems</tt>, increased default to 10,000, 10x more items can be shown.</td> </tr> <tr> <td>2023-04-04</td> <td>all</td> <td><a href="trackDbHub.html#downloadUrl">downloadUrl</a></td> <td>New: <tt>downloadUrl <fileType> <URL></tt><br>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.</td> </tr> <tr> <td>2022-09-30</td> <td>bigBed, BAM</td> <td><a href="trackDbHub.html#doWiggle">doWiggle</a></td> <td>New: <tt>doWiggle on</tt><br>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.</td> </tr> <tr> <td>2022-09-22</td> <td>bigGenePred</td> <td><a href="trackDbHub.html#colorByStrand">colorByStrand</a></td> <td>Change: <tt>colorByStrand</tt> can now be used by bigGenePred-type tracks.</td> </tr> <tr> <td>2022-06-30</td> <td>bigPsl, bigChain</td> <td><a href="trackDbHub.html#otherTwoBitUrl">otherTwoBitUrl</a></td> <td>New: <tt>otherTwoBitUrl <URL></tt><br>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.</td> </tr> <tr> <td>2022-05-14</td> <td>bigWig</td> <td><a href="trackDbHub.html#logo">logo</a></td> <td>New: <tt>logo on</tt><br>Motif logo of the genome sequence, as a "dynseq" display, see <a href='../bigWig.html#Ex4'>the example</a>.</td> </tr> <tr> <td>2022-05-11</td> <td><b>genomes.txt setting</b></td> <td><a href="../assemblyHubHelp.html#chromAuthority">chromAuthority</a></td> <td>New <code>chromAuthority</code> genome-stanza setting (an assembly hub <code>genomes.txt</code> setting, not a track setting) chooses which <code>chromAlias</code> name column is displayed by default for the assembly's sequences, e.g. <code>chromAuthority ucsc</code>.</td> </tr> <tr> <td>2022-05-05</td> <td>bigMaf, maf</td> <td><a href="trackDbHub.html#logoMaf">logoMaf</a></td> <td>New: <tt>logoMaf on</tt><br>Motif logo on MAF/bigMaf alignment tracks. Zooming in on alignment shows nucleotides scaled by phyloP conservation.</td> </tr> <tr> <td>2019-05</td> <td>all</td> <td><a href="../hgTracksHelp.html#UseOneFile">useOneFile</a></td> <td><tt>useOneFile on</tt><br>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.</td> </tr> </tbody> </table> </div> </div> </BODY></HTML>