Versioned Track Hubs
Overview
This page exists as a reminder to engineers on how to approach the new versioned track hub documentation. This is in relation to the "Hub Track Database Definition" page.
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 and when to version from v# to v#+1
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.
For versioning the file, the consensus is to be conservative and only rollover the trackDbHub.v#.html version with a major feature addition, or deprecation of an existing feature. It was suggested that the driver of versioning should really be the needs of the hub user and hub-display community.
There are helpful steps in cat ~kent/src/hg/htdocs/goldenPath/help/trackDb/README.txt
for the person who will likely have to step back the file with something like
git checkout abadcafe-last-commit-before-newstuff-efefg133 trackDbHub.v3.html(see note below)
to get the page in it's pre_v#+1 state.
Don't forget to update goldenPath/help/trackDb/makefile to point to the new page too.
See step 1 in the README.txt for details.
(note: if you want to undo your git checkout, just git checkout abadcafe-most-recent-commit trackDbHub.v3.html)
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 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. Angie shares JQuery's CSS-like selectors make it easy to identify elements by class in JavaScript, and that's what trackDbDoc.js is doing.
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>
NOTE: Look at that "types all" definition, that will be used in the Table of Contents sections for both pages.
<DIV class="spectrum"><span class="types all"></span>
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).
IMG class='toggle detail'
This little required detail is what allows the + - box to toggle opening and closing your section.
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.
unusual span class= differences
Most of the time the above will work, you will be adding class="level-something" in the first new setting< bracket.
This spectrum example was picked, however, because it is unusual. It is a situation where one entry in trackDbLibrary.shtml (spectrum) has multiple settings, (scoreMax and scoreMin as well). This is one reason why both the trackDbDoc and trackDbHub have the multiple name anchors so items land here. Let's look again at the differences of these two lines:
Here's the trackDbDoc.html version:
<code>scoreMax <integer></code><BR>
<code>scoreMin <integer></code></div>
And here is the trackDbHub.v#.html version:
<span class="scoreMax"><code class="level-full">scoreMax <integer></code></span><BR>
<span class="scoreMin"><code class="level-full">scoreMin <integer></code></span></div>
You see that there are the class="level-full" on each of these entries under the <code section, but there is also the span class= entries. The reasons for this are so we can appropriately get those assignments of level onto the scoreMax and scoreMin as items to display in the TOC, otherwise they would appear as having no assigned level.
Again this is an unusual circumstance, only happening when there is a trackDbLibrary.shtml setting (like spectrum) that has multiple settings within it's Library text (scoreMax and scoreMin in this case).
Summary about example of trackDbLibrary.shtml around spectrum
This one example around spectrum in no way encompasses all the confusing things taking place with these pages due to the JavaScript controlling it, but tries to give a glimpse of solutions. Take away points are:
- Always be sure there is a name= to a new setting added to the page so the TOC links will work.
- Always be sure there is a class="level-full/new/" added to new settings under the class="format" section
- Note for the unusual case of multiple settings defined in only one trackDbLibrary.shtml entry you can use the span approach to ensure those settings get assigned values in the TOC by the page's JavaScript.
