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 @@ -10,55 +10,52 @@ - 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 @@ -249,30 +246,97 @@ 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 @@ -1125,30 +1189,44 @@ - bigBarChart roles: - leaf category: bigBarChart context: trackDb level: new required: false summary: This setting turns on the faceted selection on the track details and configure page which is useful for selecting which bars out of a large number to display. description: This setting turns on the faceted selection on the track details and configure page which is useful for selecting which bars out of a large number to display. It works with the barChartStatsUrl. The comma-separated list of columns refer to column names in the tab-separated-value file specified by barChartStatsUrl. See an example with images of barChartFacets on the barChart help page . format: barChartFacets examples: [] +- name: barChartMatrixUrl + types: + - bigBarChart + roles: + - leaf + category: bigBarChart + context: trackDb + level: full + required: false + summary: Specifies a data matrix file that provides data values for all samples. + description: Specifies a data matrix file that provides data values for all samples. Used together with + barChartSampleUrl to generate a box plot on the details page. + format: barChartMatrixUrl + examples: [] - name: barChartStatsUrl types: - bigBarChart roles: - leaf category: bigBarChart context: trackDb level: new required: false summary: This setting associates a table in tab-separated-values with the barchart, with one line per bar. description: 'This setting associates a table in tab-separated-values with the barchart, with one line per bar. The first line of the file contains the table column names. The first column contains the name of the bar. The other columns can be in any order. If a color column is present it will be used for the colors of the bars using the hexadecimal #RRGGBB format. (Currently the same names and colors @@ -1570,55 +1648,64 @@ visualization is rendered by an ES6 module loaded on demand when the details page is viewed. The setting name has three dot-separated parts: The value is a JSON object with configuration for the visualization, such as titles and axis labels. Its keys are merged into the data object passed to the JavaScript function. Multiple fields can be visualized by using multiple detailsScript settings with different field names. Fields sharing the same are grouped together and passed to a single JavaScript function call. The currently available plot type is histogram , which draws an SVG bar chart from data encoded as space-separated key=value pairs (logfmt format). The histogram plot type accepts the following JSON config keys: title (chart heading) and xLabel (x-axis label).' format: detailsScript.. examples: - 'detailsScript.histogram.afrHist {"title":"AFR Allele Frequencies","xLabel":"Allele size (repeat copies)"} detailsScript.histogram.eurHist {"title":"EUR Allele Frequencies","xLabel":"Allele size (repeat copies)"}' - name: exonArrows types: - - genePred - bed + - bigBed + - genePred + - bigGenePred + - psl + - bigPsl + - chain + - bigChain + - narrowPeak + - bigNarrowPeak - broadPeak roles: - leaf category: bigBed - Item or Region Track Settings context: trackDb level: full required: false summary: On tracks that show exons or blocks within features, exon arrows allow the user to jump to the next exon or block outside the image. description: On tracks that show exons or blocks within features, exon arrows allow the user to jump to the next exon or block outside the image. Exon arrows are typically shown by default in these types of tracks, with the exception of tracks in the Regulation group. The arrows can be explicitly shown or hidden using this setting. format: exonArrows examples: - exonArrows off - name: exonNumbers types: - genePred + - bigGenePred - bed - - psl - bigBed - - bigGenePred + - psl + - bigPsl roles: - leaf category: bigBed - Item or Region Track Settings context: trackDb level: full required: false summary: A mouseover that shows the exon and intron numbers can be explicitly shown or hidden using this setting. description: A mouseover that shows the exon and intron numbers can be explicitly shown or hidden using this setting. The default is "on" for the track types genePred and bigGenePred. format: exonNumbers examples: - exonNumbers off - name: scoreFilter types: @@ -1659,127 +1746,135 @@ summary: Maximum number of items to display individually in full or pack or squish mode. description: 'Maximum number of items to display individually in full or pack or squish mode. When the maximum is exceeded, the track switches to coverage mode. Default: 1000. For type bigBed tracks, this setting can never be larger than the hg.conf setting bigBedMaxItems, which by default is 100,000 at UCSC. bigBedMaxItems is configured globally for a Genome Browser server and sets an upper limit on how many features can be loaded at most from a bigBed file, to avoid a single track making a Genome Browser view unusable at high zoom levels so it the upper limit for all maxItems settings of any tracks shown on a Genome Browser. If you have feedback on these values, please do not hesitate to contact us.' format: maxItems examples: - maxItems 25 - name: maxWindowCoverage types: - bed + - bigBed - genePred - - bam - - rmsk + - bigGenePred + - psl + - bigPsl + - chain + - bigChain - narrowPeak + - bigNarrowPeak - broadPeak - - bigWig + - bam + - rmsk - bedLogR + - vcf + - vcfTabix roles: - leaf category: bigBed - Item or Region Track Settings context: trackDb level: full required: false summary: When too many individual bed items might be shown in the Browser image (such as might occur when a large region of a chromosome is viewed), maxWindowCoverage... description: When too many individual bed items might be shown in the Browser image (such as might occur when a large region of a chromosome is viewed), maxWindowCoverage will switch the track into density coverage plot when the window contains more than the specified number of bases. format: maxWindowCoverage examples: - maxWindowCoverage 10000000 - name: maxWindowToDraw types: - - bed - - genePred - - bam - - rmsk - - narrowPeak - - broadPeak - - bigWig - - bedLogR + - all roles: - leaf category: bigBed - Item or Region Track Settings context: trackDb level: full required: false summary: When too many individual bed items might be shown in the Browser image (such as might occur when a large region of a chromosome is viewed), maxWindowToDraw w... description: When too many individual bed items might be shown in the Browser image (such as might occur when a large region of a chromosome is viewed), maxWindowToDraw will trigger a choice to display a message asking users to zoom in to a smaller region. Depending on the current visibility of the bed track and which other tracks are being shown concurrently, the Browser may automatically reduce the display to pack or dense mode in some cases. The maxWindowToDraw setting allows you to force users to zoom in as an overriding message will block out the data display. Unlike the maxItems setting, which controls the display of vertical space and forces a display to dense when the maximum number of items is exceeded, the maxWindowToDraw setting dictates the number of bases to be displayed in a window before the track is obscured with a message explaining the requirement for zooming-in. Even without this setting, there are browser operations that will ultimately prevent too many items from being displayed by forcing a visualized summary in dense mode as noted. format: maxWindowToDraw examples: - maxWindowToDraw 10000000 - name: minGrayLevel types: - bed + - bigBed - broadPeak - narrowPeak + - bigNarrowPeak - bedLogR - - bigBed + - bigInteract roles: - leaf category: bigBed - Item or Region Track Settings context: trackDb level: full required: false summary: When a bed track contains the standard field score , and when that score is used to present items in gray or color scale (see spectrum ), this setting specif... description: When a bed track contains the standard field score , and when that score is used to present items in gray or color scale (see spectrum ), this setting specifies the lightest shade to be used. This prevents the lowest scores from being displayed in too light of a color to easily view. Set the value in the range 1 - 9, lightest to darkest. format: minGrayLevel <1-9> examples: - minGrayLevel 4 - name: noScoreFilter types: - bed + - bigBed - bedGraph - bedLogR - gvf roles: - leaf category: bigBed - Item or Region Track Settings context: trackDb level: full required: false summary: By default, bed tracks with 5 or more standard bed fields that contain either a ' . description: By default, bed tracks with 5 or more standard bed fields that contain either a ' . ' or a ' + ' in the type setting will be filterable on score ; that is, they will have an assumed setting of " scoreFilter 0 ". To turn this old-style default off, include the " noScoreFilter " setting. format: noScoreFilter on examples: - "type bigBed 6 +\n noScoreFilter on" - name: spectrum types: - - all + - bed + - bigBed + - bigGenePred + - psl + - bigPsl roles: - leaf category: bigBed - Item or Region Track Settings context: trackDb level: base required: false summary: Replaces useScore . description: 'Replaces useScore . If your track is a bed 5 or greater, then the standard bed score field exists. This score, which is expected to vary from 0-1000, can be used to control the shading of bed items drawn in the Browser image. To activate this feature, set spectrum on . Lower scores will be shaded in light gray by default, while higher scores will trend towards black. This can be modified in a number of ways: Note: The file type must be type bigBed x where x is at least bigBed 5. If only type bigBed is used, the setting will not work as it is assumed to be a bigBed 3.' format: spectrum on examples: @@ -2089,30 +2184,65 @@ disable that default filter In order for filters to work, the track must be " type bigBed N + " or " type bigBed N . ". Including the "+" (for bigBed+ tracks) or a "." (for non-extended bigBed tracks) is required Filters are not supported in bed3 or bed4 files, even bed 3+x. The file must be at least a bed5 There should not be any white spaces between declared items after commas, e.x. "itemOne,itemTwo,itemThree" The default label can be customized with the filterLabel. parameter When using filter values in a field that incudes commas, an additional comma can be used to escape it. E.x. "fieldOne,fieldTwo,,fieldTwo,fieldThree"' format: filterValues. examples: - filterValues.fieldName fieldValue1|alternativeName1,fieldValue2|alternativeName2... - filterValues.OddEven Odd,Even - "filterValues.OddEven Odd,Even\n filterType.OddEven singleList" - "filterValues.OddEven Odd,Even\n filterType.OddEven singleList\n filterValuesDefault.OddEven\ \ Odd" - filterValues.annotationType DNA-BR,AS,BS,BSi - filterValues.annotationType DNA-BR|DNA-binding region,AS|active site,BS|beta strand,BSi|binding site +- name: filterBy + types: + - bed + - bigBed + - genePred + - bigGenePred + - psl + - bigPsl + - bigLolly + - factorSource + roles: + - leaf + category: bigBed - Item or Region Track Settings + context: trackDb + level: full + required: false + summary: Another method of filtering items relies upon discrete values. + description: 'Another method of filtering items relies upon discrete values. One or more fields such + as name or score may contain a limited number of discrete values that can be filtered on. These discrete + values will be displayed in a dropdown list from which the user can choose one or more options. While + the maximum number of options in the list is not limited, displaying too many options can be confusing + for the user. Setting complexities: Because of this complexity, please remember to use the '' \ '' + continuation line to ensure the setting is readable: It is probable that this setting will be redefined + at some point, given that it is very complicated. However, this current format will be supported until + entirely replaced. The best way to understand this setting is with an example. This is an operational + example in the hg19 "Open Chrom Synth" track.' + format: "filterBy \n [field2:title=[+]opt2a...]" + examples: + - "filterBy {field1}[:{Title1}]=[+]\\\n option1a[|label1a[{style1a}]],\\\n option1b[|label1b[{style1b}]],...\ + \ \\\n [{field2}[:{Title2}]=[+]\\\n option2a[|label2a[{style2a}]],,...]" + - "filterBy color:Validation_Level=\\\n 0|Validated_(OC_1){color:#000000},\\\n \ + \ 255|Open_Chromatin_(OC_2-3){color:#0000FF},\\\n 39168|DNase_low_(OC_2){color:#009900},\\\ + \n 10027008|FAIRE_low_(OC_3){color:#990000},\\\n 16711935|ChIP-seq_(OC_4){color:#FF00FF}\ + \ \\\n ocCode:OC_Code=+\\\n One:_Validated_(all),\\\n Two:_DNase_(all),\\\ + \n Three:_FAIRE_(all),\\\n Four:_ChIP_(all)" - name: filterLabel types: - bed - bigBed roles: - leaf category: bigBed - Item or Region Track Settings context: trackDb level: full required: false summary: When a user clicks on a track item in the Browser image, the item detail page is shown. description: 'When a user clicks on a track item in the Browser image, the item detail page is shown. This setting specifies an alternate label for the filter on that page. Without this setting, the label will be the description of the field as specified by the autoSql (.as) file. Some of the parameters modified by this are: filter. filterText. filterValues.' @@ -2275,46 +2405,58 @@ - leaf category: Item or Region Track Settings - less frequent context: trackDb level: full required: false summary: When a user clicks on a bed track item in the Browser image, the item detail page is shown. description: When a user clicks on a bed track item in the Browser image, the item detail page is shown. This setting specifies an alternate label for the item name on that page. Without this setting, the label will be "Item:". format: bedNameLabel