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/trackDbSettings.yaml src/hg/htdocs/goldenPath/help/trackDb/trackDbSettings.yaml index a43af6f836c..a2c9f30b1d1 100644 --- src/hg/htdocs/goldenPath/help/trackDb/trackDbSettings.yaml +++ src/hg/htdocs/goldenPath/help/trackDb/trackDbSettings.yaml @@ -1,4720 +1,5179 @@ # Generated by trackDbSettingsGen.py --import, which rewrites the whole file. # Edit the trackDb help docs instead, then run 'make settings'. # 'roles' is a guess from which doc table a setting sits in; check the # container-only ones. - name: track types: - all roles: - super - composite - view - leaf category: Common Settings context: trackDb level: required required: true summary: This is the name of the dataset and must be unique within the Genome Browser or dataHub. description: 'This is the name of the dataset and must be unique within the Genome Browser or dataHub. Typically this is the MariaDB table name or remote data file root name (without path or suffix). Must begin with a letter and contain only the following chars: [ a-zA-Z0-9_- ].' format: track examples: - track myFirstTrack -- name: type +- 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: altGraphX , bam , bed , bed5FloatScore , bedGraph , bedRnaElements , bigBarChart , - bigBed , bigInteract , bigLolly , bigPsl , bigChain , bigMaf , bigWig , broadPeak , chain , clonePos - , coloredExon , ctgPos , downloadsOnly , encodeFiveC , expRatio , factorSource , genePred , gvf , - hic , ld2 , narrowPeak , netAlign , peptideMapping , psl , rmsk , snake , vcfTabix , wig , wigMaf - Not all track types are supported in hubs. The types specifically supported are called out at the - top of the Hub Track Database Definition page. In many cases the type setting includes additional + Valid settings for a hub: bam/cram , bigBarChart , bigBed , bigChain , bigGenePred , bigInteract , + bigLolly , bigMaf , bigNarrowPeak , 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 bed 6 + + - type bigBed 6 + - name: shortLabel types: - all roles: - super - composite - view - leaf category: Common Settings context: trackDb level: required required: true summary: Specifies the track's "short label", which is used in a number of places in the Browser to identify the track. description: Specifies the track's "short label", which is used in a number of places in the Browser to identify the track. For example, the short label is displayed alongside the track in the Browser image. This label must be brief and is limited to 17 printable characters. Some special characters are allowed in the shortLabel. format: shortLabel examples: - shortLabel Human mRNAs - name: longLabel types: - all roles: - super - composite - view - leaf category: Common Settings context: trackDb level: required required: true summary: Specifies the track's "long label", which is also used in numerous places in the Browser to identify a track. description: Specifies the track's "long label", which is also used in numerous places in the Browser to identify a track. For instance, the long label is displayed above the track's data in the Browser image. This label should be descriptive enough to allow users to uniquely identify the track within the Browser. It is limited to 76 printable characters. Some special characters are allowed in the longLabel. format: longLabel examples: - longLabel Human mRNAs from GenBank - name: bigDataUrl types: - bigBarChart - bigBed - bigChain - bigInteract - bigLolly - bigMaf - bigPsl - bigWig - 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, 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 required: false summary: Use the html path/to/explain.html to specify the file that contains the complete description of a track in HTML format. 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. 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.' 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:' format: visibility examples: - visibility dense - name: meta types: - all roles: - super - composite - view - leaf category: Common Settings context: trackDb level: full required: false summary: Meta specifies the metadata tag for this track. description: Meta specifies the metadata tag for this track. This tag is a key into the metadata table specified in either metaDb or metaTab in the genomes.txt file. The meta tag can be any alphanumeric string. Each meta tag should appear in a trackDb stanza AND in either the tab-separated file specified by metaTab, or tagStorm file specified by metaDb in the hub's genomes.txt file. Examples on how to include metadata in your hubs can be found on the following metadata guide . format: meta 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 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. 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 summary: The priority is used to define the order of a track within its track group or data hub, as well as its default order within the Browser image. description: 'The priority is used to define the order of a track within its track group or data hub, as well as its default order within the Browser image. The order within the image can be dynamically changed by the user and will always depend upon which other tracks are currently visible. Typically the priority is set only for tracks that are on by default in order to move them ahead of other tracks. Prioritized tracks within a group or data hub are displayed in ascending priority order, followed by unprioritized tracks sorted alphabetically by short label. Tracks of the same priority within a group or hub are sorted by short label. Priority is a floating point number. Default: 0.' format: priority examples: - 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.' + 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 + summary: Most track displays that can be configured by a user can also be configured from directly within + the Browser image through a right-click option that pops up... + description: 'Most track displays that can be configured by a user can also be configured from directly + within the Browser image through a right-click option that pops up a configuration dialog. While this + functionality works on the majority of track types, some configuration dialogs are too complex or + have too much embedded javascript control to be reliably configured through a pop-up. To turn off + the ability to configure the track via right-click, change this setting to "off". The user will still + be able to configure the track on the track''s configuration page. DEFAULT: on.' + format: configureByPopup + examples: + - configureByPopup off +- name: origAssembly + types: + - all + roles: + - super + - composite + - view + - leaf + category: Common Settings - less frequent + context: trackDb + level: full + required: false + summary: The original assembly version for which the dataset was generated. + description: The original assembly version for which the dataset was generated. Datasets generated by + mapping to one genome assembly may prove useful enough to map to a more recent assembly. Ideally datasets + will be regenerated to map to the new assemblies coordinates, but sometimes this is not practical + or expedient. Therefore, the dataset may have its genome coordinates "lifted over" to the more recent + assembly. In some cases this results in an inferior but nevertheless useful representation. Such datasets + should have their original assembly defined with this setting. + format: origAssembly + 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 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. 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 summary: Configuration controls can be placed inside a box on the configuration page. description: 'Configuration controls can be placed inside a box on the configuration page. This setting is decorative only, but can make a busy page look more cohesive. Not all track types currently support this feature, but the most common types do, including wig, bigWig, bed, and bigBed. DEFAULT: off.' format: boxedCfg examples: - boxedCfg on - name: chromosomes types: - all roles: - super - composite - view - leaf category: Common Settings - less frequent context: trackDb level: full required: false summary: Some datasets do not contain data for all chromosomes of a genome. description: Some datasets do not contain data for all chromosomes of a genome. When this is true, use this setting as a comma-separated list of the chromosomes that are covered. The system displays a message that no data is available when the user browses chromosomes not included in this list. format: chromosomes examples: - chromosomes chr1,chr7,chr18,chr19,chr22,chrX,chrM - name: darkerLabels types: - all roles: - super - composite - view - leaf category: Common Settings - less frequent context: trackDb level: full required: false summary: If this setting is "on", the color of the left labels on the track display will have a somewhat darker color than the track display itself. description: If this setting is "on", the color of the left labels on the track display will have a somewhat darker color than the track display itself. This can be useful where the track color (which may have been chosen to adhere to external conventions) is too light for readable labels. format: darkerLabels on examples: [] - name: dataVersion types: - all roles: - super - composite - view - leaf category: Common Settings - less frequent context: trackDb level: full required: false summary: Many tracks undergo multiple revisions over time. description: Many tracks undergo multiple revisions over time. In some cases, the older versions should be retained, but even if they are not, it can be useful to declare the current version of the track. Use this setting to display a version statement on the track configuration page and item details page of a track. The string will support limited HTML. For native tracks, not track hubs, this setting can also be a local absolute filename to read the version string from. format: dataVersion examples: - dataVersion May 2011 beta - name: directUrl_for_hubs 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.' 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 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, ... format: downloadUrl