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 -settings to 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?