Versioned Track Hubs
Overview
This page exists as a reminder to engineers on how to approach the new versioned track hub documentation.
How to work with the 'versioned' track hub settings
1) Since every trackDb setting in the doc is now assigned a level (described in the intro of the trackDbHub doc)...
-> When you add a new setting, you will need to set it to 'level-new'.
Next time the doc is versioned, we will evaluate the new settings for assignment to a level.
2) As the doc is now parsed by hubCheck to verify settings...
-> After adding a setting to the doc, you will need to run
hubCheck -settingsto see if your addition is formatted correctly.
To list all settings (with levels) on genome-test, run
hubCheck -settings -test
The README.txt in the trackDb docs dir has been extended to include these steps with the new information in step 3.
cat ~kent/src/hg/htdocs/goldenPath/help/trackDb/README.txt
Also see the long comment at the top of trackDbLibrary.shtml for details
head -n 125 ~kent/src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml
Discussion
The versioning applies to the hub spec only. If
a new setting is added, the 'meat' is indeed in the
trackDbLibrary.shtml file, but the level is set in the
trackDbHub.html file (only needed if we are supporting the
setting for hub use). All new hub-able settings should be set
at (surprisingly) 'level-new'. And developer should validate
their doc file changes for correct format using 'hubCheck -settings -version=<your-file>
such as http://hgwdev-<user>/goldenPath/help/trackDb/trackDbHub.v1.html
The option -test will use the version on dev.
Examples
Layout
Here's a way to try to help show how these pages work:
(shared text)
trackDbLibrary.shtml-----> trackDbDoc.html
\------------------> trackDbHub.v#.html
/|\ /|\
trackDbDoc.css -----------------| |
trackDbDoc.js------------------------|
(shared style & JavaScript)
The page uses JavaScript Classes making things a bit more confusing than a normal page. Because of this, one is often left wondering what is exactly happening, reading Tim's intro to the trackDbLibrary.shtml page attempts to provide some context. This example below will attempt to help. What is at issue is that in the trackDbDoc.js there is code that is taking these classes and building the html pages of trackDbDoc.html and trackDbHub.v#.html in ways that are not obvious.
Specific example of spectrum on
This section will look at how the text for the spectrum setting propagates from trackDbLibrary.shtml when referenced in the trackDbDoc.html Doc and the trackDbHub.v#.html Hub page.
trackDbLibrary.shtml source of spectrum text
In the trackDbLibrary.shtml you will find this text that defines a class="spectrum" with the below code. The text in this section will be shared in the trackDbDoc.html and trackDbHub.v#.html documents.
<DIV class="spectrum"><span class="types all"></span>
<div class="format">
<code>spectrum on</code><BR>
<code>scoreMax <integer></code><BR>
<code>scoreMin <integer></code></div>
<P>Replaces <code>useScore</code>.</P>
<P>If your track is a
<code>bed 5</code> or greater, then the standard bed <code>score</code>
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 <code>spectrum on</code>.
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:</P>
<UL>
<!-- The below statement about color and altColor is not accurate and removed 1/4/17
<LI> <code><A onclick="jumpTo(this)" HREF="#">color</A></code>
can be used to replace gray scale with a color scale</LI>
<LI> <code><A onclick="jumpTo(this)" HREF="#">altColor</A></code>
with <code><A onclick="jumpTo(this)" HREF="#">color</A></code> can vary items from
color to altColor</LI>
-->
<LI><code><A onclick="jumpTo(this)" HREF="#">minGrayLevel</A></code>
can be used to set the level of the lightest shade</LI>
<LI> <code>scoreMin</code>
and <code>scoreMax</code> can be used to define the lower and upper limits of
the range that will receive graded shading</LI>
</UL>
<P><B>Example:</B></P>
<pre>
spectrum on
scoreMin 700
scoreMax 900
color 0,0,128 < / pre>
<P>In this example, the track description will be
displayed in blue, but the track will remain a gray scale.
Items with scores less than or equal to 700 will be shown in very
light gray, those with scores between 700 and 900 will display
in increasingly darker shades of gray, and items with
scores greater than or equal to 900 above will display in black.</P>
</DIV>
trackDbDoc.html reference to the spectrum text
In the trackDbDoc.html document the class="spectrum" information is referenced in two spots.
Under the bed section link to trackDbDoc.html bed section.
<A name="bed"><A name="bigBed"></A>
...
<TR VALIGN=TOP><TD class="spectrum">
<A name="spectrum"></A>
<A name="scoreMax"></A>
<A name="scoreMin"></A><IMG class='toggle detail'>
<div class="format">
<code>spectrum on</code><BR>
<code>scoreMax <integer></code><BR>
<code>scoreMin <integer></code></div>
</TD></TR>
And under the chain section link to trackDbDoc.html chain section
<A name="chain"><A name="netAlign"></A>
...
<TR VALIGN=TOP><TD class="spectrum"><IMG class='toggle detail'>
<div class="format"><code>spectrum on</code></div>
</TD></TR>
name= definition differences:
NOTE name=definition differences: Only the first reference under bed gets the name="spectrum" definitions, missing from the example in chain. This means that links to #spectrum will only go to the bed section: http://genome.ucsc.edu/goldenPath/help/trackDb/trackDbDoc.html#spectrum Also note that the scoreMax and scoreMin name= definitions will make this same location be the result for those links: scoreMax and scoreMin So the text under the chain section, which displays, will not be where a link will jump to for these items. There is JavaScript code in trackDbDoc.js that also builds a Table of Contents (TOC) that needs these name= definitions in at least one place on the page to have links to jump somewhere.
class="format" differences:
NOTE class="format" differences: Notice that in the first bed section there are lines for all spectrum on and scoreMax <integer> and scoreMin <integer>, while in chain there are is just spectrum on used in the class format division. If you navigate to these two sections you will see what is different. At the bed section all of these items display, but at chain section (scroll down) only spectrum on displays. Now click the spectrum on section in chain. Do you see how it changes? This is because it has now sourced what is written in trackDbLibrary.shtml, Tim's intro to trackDbLibrary.shtml explains a rational for this (so the authority of trackDbLibrary.shtml is respected).
trackDbHub.v#.html reference to the spectrum text
In the trackDbHub.v#.html document the class="spectrum" information is referenced in one spot under bigBed.
<A name="bigBed"></A>
...
<TR VALIGN=TOP><TD class="spectrum">
<A name="spectrum"></A>
<A name="scoreMax"></A>
<A name="scoreMin"></A><IMG class='toggle detail'>
<div class="format">
<code class="level-base">spectrum on</code><BR>
<span class="scoreMax"><code class="level-full">scoreMax <integer></code></span><BR>
<span class="scoreMin"><code class="level-full">scoreMin <integer></code></span></div>
</TD></TR>
class=level-required/base/full/new differences
Look up above to the earlier trackDbDoc.html document code that references spectrum, do you see what is different? Under the class="format" section there is now differences. Let's first look at the spectrum line:
In the trackDbDoc.html the line is just:
<code>spectrum on</code><BR>
But in the trackDbHub.v#.html the line is:
<code class="level-base">spectrum on</code><BR>
This new class="level-base" allows the page to define that this setting is at base used in the Table of Contents and when you open the spectrum section under bed, which displays Support level: base.
