4772aea49f07259fd10114bb6da14bc93a49176d gperez2 Tue Aug 20 14:28:00 2024 -0700 Incorporated Mark's feedback for the hub groups documentation, refs #33580 diff --git src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html index da11064..88f7773 100755 --- src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html +++ src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html @@ -816,96 +816,121 @@ <p> The track description file must have the same name as the symbolic name for the track (defined by the <em>track</em> tag in the trackDb.txt file) with a suffix of <em>.html</em>. For instance, a description file associated with the track named "dnaseSignal" in <em>Example 4</em> would be named "dnaseSignal.html". The description file must reside in the same directory as the trackDb.txt file.</p> <p> Both parent and child tracks within a super-track can have their own description files. If the description file is not present, the corresponding sections of the track settings and details pages are left blank. Only one description page can be associated with composite and multiWig tracks; the file name should correspond to the symbolic name of the top-level track in the composite.</p> <!-- ========== Adding Groups to a Track hub ==================== --> <a name="Group"></a> <h2>Adding groups to a Track Hub</h2> - -<p>You can add groups to your track hub by using the groups setting, which points to a separate -text document that defines the track groups under the primary genome browser image display. As an -example using the -<a href="examples/hubExamples/epdHub/epdHub.txt" target="_blank">EPD Viewer Hub</a>, -here is how the track hub displays without the groups setting:</p> +<p> +To organize tracks within your track hub, you can utilize the <b>groups</b> setting, which references a +separate text file that defines track groups for display under the genome browser graphic.</p> <div class="text-center"> - <img class='text-center' width="95%" src="../../images/epdHubEx.png"> + <img class='text-center' width="95%" src="../../images/groupsEx.png"> </div> +<p> +The <b>groups</b> setting can be applied to a UCSC genome, a GenArk assembly, or an assembly hub. +These track hub groups are kept separate from other track hubs and the native UCSC Genome Browser +track groups, allowing for greater organizational flexibility. For instance, you can add a +"genes" group without causing conflicts or confusion.</p> +<p> +You can define groups with names like "Category 1", "Category 2", and +"Category 3". These group names are specified in the "groups.txt file ", which +defines the track groups. Below is an example stanza demonstrating how to define these groups:</p> -<p>Groups such as Histone, CAGE, RAMPAGE, and Fantom5 groups can be added. The text document that -defines the track groups can be named groups.txt and specifies the groups such as the following: -</p> -<pre><code>name histone -label Histone +<pre><code>name category1 +label Category 1</code></pre> + +<pre><code>name category2 +label Category 2 priority 1</code></pre> -<pre><code>name cage -label CAGE -priority 2 </code></pre> +<pre><code>name category3 +label Category 3 +defaultIsClosed 1</code></pre> + -<pre><code>name rampage -label RAMPAGE -priority 3 </code></pre> +<p> +You can access the complete "groups.txt " file containing these group definitions here: +<a href="/goldenPath/help/examples/hubExamples/hubGroupings/groupsExample/groups.txt" +target="_blank">groups.txt</a>.</p> -<pre><code>name fantom5 -label Fantom5 -priority 4 -defaultIsClosed 1</code></pre> +<p> +Within this file:</p> <ul> - <li>The <b>name</b> is used in the trackDb.txt track definition group, to assign a particular track to - a group.</li> - <li>The <b>label</b> is displayed on the genome browser as the title of the group under the primary - genome browser image display</li> - <li>The <b>priority</b> orders the track group with the other track groups</li> - <li>The <b>defaultIsClosed</b> determines if the track group is expanded or closed by default. Values to use are 0 or 1</li> + <li>The <b>name</b> setting is used in the trackDb.txt file to associate specific tracks with a + group.</li> + <li>The <b>label</b> setting specifies the title of the group in the genome browser. By default, + groups are sorted alphabetically based on the label.</li> + <li>The <b>priority</b> setting dictates the display order of the track groups, with lower + numbers shown first.</li> + <li>The <b>defaultIsClosed</b> setting controls whether the group is initially expanded or + collapsed (0 for expanded, 1 for collapsed).</li> </ul> +<p> +After defining the "groups.txt" file, tracks can be assigned to a specific group +within the "trackDb.txt" file using the <b>group</b> setting. For example, to assign the +"bigBed1" track to the "bigBed" group, you could use the following stanza: +</p> + +<pre><code>track bigBed1 +bigDataUrl https://hgdownload.soe.ucsc.edu/gbdb/hg38/ncbiRefSeq/ncbiRefSeqGenomicDiff.bb +shortLabel bigBed example 1 +longLabel This bigBed file is an example from the NCBI RefSeq Diffs Track +type bigBed +<strong>group</strong> category1 +visibility dense</code></pre> + +<p> +The full "trackDb.txt" file, which includes the "bigBed1" track and additional examples, can be viewed here: +<a href="/goldenPath/help/examples/hubExamples/hubGroupings/groupsExample/hg38/trackDb.txt" +target="_blank">trackDb.txt</a>.</p> + +<p> +Next, incorporate the "groups.txt" file with the <b>groups</b> setting into the genome stanza. This can be for a UCSC +genome, a GenArk assembly, or an assembly hub. Below is an example using the hg38 genome:</p> -<p>You would then add the group name to your tracks in the trackDb stanza. For example, adding the -Histone Marks track to the Histone group:<p> -<pre><code>track 1histone -type bigWig -longLabel Selected Histone Marks -autoScale on -smoothingWindow 10 -priority 1 -compositeTrack on -allButtonPair on -windowingFunction mean -shortLabel Histone Marks -visibility full -<strong>group</strong> histone</code></pre> - -<p>The groups.txt file then needs to be added to the genome stanza. The genome can be a UCSC genome or an assembly hub. The hg38 genome will be used as an example: <pre><code>genome hg38 trackDb hg38/trackDb.txt -groups groups.txt</code></pre> +<strong>groups</strong> groups.txt</code></pre> + +<p> +An example "genomes.txt" file, which includes the hg38 genome, a GenArk assembly, and an +assembly hub, is available here: +<a href="/goldenPath/help/examples/hubExamples/hubGroupings/groupsExample/genomes.txt" +target="_blank">genomes.txt</a>.</p> + +<p> +By attaching the hub with these group settings, the tracks will be displayed within the specified groups. Below are URLs showing the group settings for the hg38 genome, a GenArk assembly, and an assembly hub:</p> +<ul> + <li><b>hg38</b>: <a href="../../cgi-bin/hgTracks?hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubExamples/hubGroupings/groupsExample/hub.txt&db=hg38" +target="_blank">hg38 Genome</a>.</p></li> + <li><b>GCF_000951035.1</b>: <a href="../../cgi-bin/hgTracks?hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubExamples/hubGroupings/groupsExample/hub.txt&db=GCF_000951035.1" +target="_blank">GenArk Assembly</a>.</p></li> + <li><b>Arabidopsis thaliana Assembly Hub</b>: <a href="../../cgi-bin/hgTracks?hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubExamples/hubGroupings/groupsExample/hub.txt&genome=araTha1" +target="_blank">Assembly Hub</a>.</p></li> +</ul> -<p>Attaching the -<a href="examples/hubExamples/hubGroupings/epdHub/epdHub.txt" target="_blank">EPD Viewer Hub</a>, -with these group settings will then display the tracks within the groups:</p> -<div class="text-center"> - <img class='text-center' width="95%" src="../../images/epdHub_Groups.png"> -</div> <!-- ========== Debugging and Updating Track Hubs ============================== --> <a name="Debug"></a> <h2>Debugging Track Hubs</strong></h2> <h3>Not updating? Change udcTimeout</h3> <p> As part of the track hub mechanism, UCSC caches data from the hub on the local server. The hub utility periodically checks the time stamps on the hub files, and downloads them again only if they have a time stamp newer than the UCSC one. For performance reasons, UCSC checks the time stamps every 300 seconds, which can result in a 5-minute delay between the time a hub file is updated and the change appears on the Genome Browser. Hub providers can work around this delay by inserting the CGI variable <em><strong>udcTimeout=5</strong></em> into the Genome Browser URL, which will reduce the delay to five seconds. To add this variable, open the Genome Browser tracks page and zoom or scroll the image to display a full browser URL in which the CGI variables visible. Insert the CGI