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 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.. 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
    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// 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/trackDbSettings.yaml src/hg/htdocs/goldenPath/help/trackDb/trackDbSettings.yaml index ed148214e8d..5222804486e 100644 --- src/hg/htdocs/goldenPath/help/trackDb/trackDbSettings.yaml +++ src/hg/htdocs/goldenPath/help/trackDb/trackDbSettings.yaml @@ -24,33 +24,37 @@ - track myFirstTrack - name: type_for_hubs types: - all roles: - super - composite - view - leaf category: Common Settings context: trackDb level: required required: true summary: Declares the format of the data and is used to determine display methods and options. description: 'Declares the format of the data and is used to determine display methods and options. - Valid settings for a hub: bam/cram , bigBarChart , bigBed , bigChain , bigGenePred , bigInteract , - bigLolly , bigMaf , bigNarrowPeak , bigNet , bigPsl , bigWig , halSnake , hic , vcfTabix , vcfPhasedTrio - . Detailed descriptions of each type can be found below. In many cases the type setting includes additional + + Valid settings for a hub: + + bam/cram , bigBarChart , bigBed , bigChain , bigGenePred , bigInteract , bigLolly , bigMaf , bigNarrowPeak + , bigNet , bigPsl , bigWig , halSnake , hic , vcfTabix , vcfPhasedTrio . + + 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.' format: type examples: - type bigBed 6 + - name: shortLabel types: - all roles: - super - composite - view - leaf category: Common Settings context: trackDb @@ -101,39 +105,41 @@ - bam - hic - vcfTabix - vcfPhasedTrio roles: - super - composite - view - leaf category: Common Settings context: trackDb level: required required: true summary: The location of a remote data file containing the bulk of the data for the track. description: '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, bigNet, bigPsl, bigGenePred, bigMethyl, - bigNarrowPeak, bigWig, vcfTabix, or hic. 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.' + 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, bigNet, bigPsl, bigGenePred, bigMethyl, bigNarrowPeak, bigWig, vcfTabix, or hic. 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.' format: bigDataUrl examples: - bigDataUrl http://vizhub.wustl.edu/VizHub/hg19/biBrainH3K4me1.bb - bigDataUrl biBrainH3K4me1.bb - name: html types: - all roles: - super - composite - view - leaf category: Common Settings context: trackDb level: base @@ -143,66 +149,104 @@ description: '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 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. + Or with full path: html https://path/to/location/docs/explainMyData.html + + 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 + 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.' + 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.' format: html examples: - html docs/myFirstTrack.html - html https://path/to/location/docs/explainMyData.html - name: visibility types: - all roles: - super - composite - view - leaf category: Common Settings context: trackDb level: required required: false summary: Visibility (i.e. description: '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. The one exception is a faceted composite , where the parent''s visibility is a maximum rather than a value the subtracks inherit, and subtrack visibility lines are honored up to that maximum. Be sure to experiment with this setting to verify that it works as expected - for your track type and track structure. Valid settings:' + 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.' format: visibility examples: - visibility dense - name: meta types: - all roles: - super - composite - view - leaf category: Common Settings context: trackDb level: full required: false @@ -216,34 +260,36 @@ examples: [] - name: color types: - all roles: - super - composite - view - leaf category: Common Settings - less frequent context: trackDb level: base required: false summary: Many track types allow the color of the data displayed in the image to be specified with this setting. - description: Many track types allow the color of the data displayed in the image to be specified with + description: '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. + + This example sets the color to red.' format: color examples: - color 255,0,0 - name: priority types: - all roles: - super - composite - view - leaf category: Common Settings - less frequent context: trackDb level: base required: false @@ -261,35 +307,37 @@ - priority 50 - name: canPack types: - all roles: - super - composite - view - leaf category: Common Settings - less frequent context: trackDb level: deprecated required: false summary: Deprecated. description: 'Deprecated. The track type usually implies whether pack and squish are offered, so this - setting is rarely needed. 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.' + setting is rarely needed. + + 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.' format: canPack examples: - canPack on - name: configureByPopup types: - all roles: - super - composite - view - leaf category: Common Settings - less frequent context: trackDb level: full required: false @@ -327,36 +375,38 @@ examples: - origAssembly hg18 - name: altColor types: - all roles: - super - composite - view - leaf category: Common Settings - less frequent context: trackDb level: full required: false summary: Many track types allow setting a color range that varies from color to altColor . - description: 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 + description: '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. + + This example sets the alternate color to blue.' format: altColor examples: - altColor 0,0,255 - name: boxedCfg types: - all roles: - super - composite - view - leaf category: Common Settings - less frequent context: trackDb level: full required: false @@ -430,102 +480,152 @@ types: - all roles: - super - composite - view - leaf category: Common Settings - less frequent context: trackDb level: full required: false summary: By default, items shown in the Browser image can be linked to a details page giving information about that item. description: '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: 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.' + 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.' format: directUrl examples: - directUrl http://mygenes.org/cgi-bin/geneView/%s - name: downloadUrl types: - all roles: - super - composite - view - leaf category: Common Settings - less frequent context: trackDb level: full required: false summary: While description HTML pages can contain download instructions, having external file download links directly specified in trackDb makes it possible show thes... - description: While description HTML pages can contain download instructions, having external file download + description: 'While description HTML pages can contain download instructions, having external file download links directly specified in trackDb makes it possible show these links outside the description HTML pages. The URLs here are shown above the description page, right under the "data format" link. The label can be any string and the URL should be absolute, including the server. Either one can contain - spaces, but they must be double-quoted then. This is one of the few statements that can be specified - multiple times. In this case, all statements must have a .number suffix, e.g. .1, .2, ... + spaces, but they must be double-quoted then. + + This is one of the few statements that can be specified multiple times. In this case, all statements + must have a .number suffix, e.g. .1, .2, ...' format: downloadUrl