61547c79190553a311776b9a309bcb5dafada237 gperez2 Mon Jul 1 01:23:58 2024 -0700 Adding documentation on adding groups to a Track Hub, refs #33580 diff --git src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html index 429be55..0cd7e0f 100755 --- src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html +++ src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html @@ -2,30 +2,31 @@ <!--#set var="TITLE" value="Track Hubs" --> <!--#set var="ROOT" value="../.." --> <!-- Relative paths to support mirror sites with non-standard GB docs install --> <!--#include virtual="$ROOT/inc/gbPageStart.html" --> <h1>Using UCSC Genome Browser Track Hubs</strong></h1> <h2>Contents</h2> <h6><a href="#Intro">What Are Track Hubs?</a></h6> <h6><a href="#Assembly">What Are Assembly Hubs?</a></h6> <h6><a href="#View">Viewing Track Hubs</a></h6> <h6><a href="#Sharing">Sharing Track Hubs</a></h6> <h6><a href="#Setup">Setting up a Track Hub</a></h6> +<h6><a href="#Group">Adding Groups to a Track hub</a></h6> <h6><a href="#Debug">Debugging Track Hubs</a></h6> <h6><a href="#Search">Setting up item search</a></h6> <h6><a href="#Filters">Adding filters to your Track Hub</a></h6> <h6><a href="#Register">Registering a Track Hub with UCSC</a></h6> <h6><a href="#Compatibility">Checking Hub settings and compatibility</a></h6> <h6><a href="#Hosting">Where to host your data</a></h6> <h6><a href="https://genome.ucsc.edu/goldenPath/help/trackDb/trackDbHub.html" target = _blank>Track Hub Database Definition Document</a></h6> <hr> <p> <strong>Additional resources</strong></p> <ul> <li>Raney BJ, et al. <a href="https://doi.org/10.1093/bioinformatics/btt637" target="_blank">Track Data Hubs enable visualization of user-defined genome-wide annotations on the UCSC Genome Browser</a>. <em>Bioinformatics</em>. 2014 Apr 1;30(7):1003-5. @@ -190,43 +191,43 @@ <a href="hgSessionHelp.html#Create"> backing up custom data</a>.</p> <a name="hubUrl"></a> <h3>Creating a URL for a Track Hub</h3> <p>Hubs can be loaded into the URL using the <code>hubUrl=</code> parameter. This parameter takes input similar to the <a href="../cgi-bin/hgHubConnect#unlistedHubs">track hub input box</a>. Native UCSC supported genomes can be loaded into the URL using the <code>db=</code> parameter while non-natively supported genomes such as assembly hubs or GenArk hubs use the <code>genome=</code> parameter. URL parameters can be combined by using <code>&</code>. </p> <p>The following example links to the hg19 genome database and an example track hub using the <code>db=</code> and the <code>hubUrl=</code> parameters:</p> -<pre><a href=../cgi-bin/hgTracks?db=hg19&hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hub.txt>http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg19&hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hub.txt</a></pre> +<pre><a href=../../cgi-bin/hgTracks?db=hg19&hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hub.txt>http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg19&hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hub.txt</a></pre> <p>Track hubs' track visibility can also be changed from the URL parameters. As an example, the following link specifies: <ul> <li> the genome database (db=hg38)</li> <li> loads a track hub (hubUrl=http://hgdownload.soe.ucsc.edu/hubs/gtex/hub.txt)</li> <li> hides all tracks (hideTracks=1)</li> <li> hides the subtrack kids of a particular track (gtexRnaSignalMaleYoung_hideKids=1)</li> <li> sets a specific subtrack to be displayed (gtexRnaSignalSRR1311243=full)</li> <li> ignores user settings (ignoreCookie=1).</p></li> </ul> -<pre><a href="../cgi-bin/hgTracks?db=hg38&hubUrl=http://hgdownload.soe.ucsc.edu/hubs/gtex/hub.txt&hideTracks=1>exRnaSignalMaleYoung_hideKids=1>exRnaSignalMaleYoung=full>exRnaSignalSRR1311243=full&ignoreCookie=1">https://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hubUrl=http://hgdownload.soe.ucsc.edu/hubs/gtex/hub.txt&hideTracks=1&gtexRnaSignalMaleYoung_hideKids=1&gtexRnaSignalMaleYoung=full&gtexRnaSignalSRR1311243=full&ignoreCookie=1</a></pre> +<pre><a href="../../cgi-bin/hgTracks?db=hg38&hubUrl=http://hgdownload.soe.ucsc.edu/hubs/gtex/hub.txt&hideTracks=1>exRnaSignalMaleYoung_hideKids=1>exRnaSignalMaleYoung=full>exRnaSignalSRR1311243=full&ignoreCookie=1">https://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hubUrl=http://hgdownload.soe.ucsc.edu/hubs/gtex/hub.txt&hideTracks=1&gtexRnaSignalMaleYoung_hideKids=1&gtexRnaSignalMaleYoung=full&gtexRnaSignalSRR1311243=full&ignoreCookie=1</a></pre> <h6>Optional parameters that can be added to the URL:</h6> <ul> <li><code>guidelines=on/off</code> - activate or deactivate the blue guidelines</li> <li><code>hgFind.matches=<listOfNames></code> - highlight features given their names</li> <li><code>hgt.reset=1</code> - show only the default tracks</li> <li><code>hgt.toggleRevCmplDisp=1</code> - show the reverse-complement</li> <li><code>hgt.labelWidth=<number></code> - set the size of the left-side label area</li> <li><code>hideTracks=1</code> - hide all tracks</li> <li><code>hideTracks=1&<trackName>=full|dense|pack|hide</code> - hide all tracks and show other tracks</li> <li><code>highlight=<db>.<chrom>:<chromStart>-<chromEnd>#<color>|...</code></li> - highlight one or more regions in a given color on the image. Note that the arguments have to be @@ -812,30 +813,99 @@ track configuration page that displays when the user clicks on the track's short label. It also displays on the track details page that is shown when the user clicks on a feature in the track image.</p> <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="https://epd.expasy.org/epd/ucsc/epdHub/epdHub.txt" target="_blank">EPD Viewer Hub</a>, +here is how the track hub displays without the groups setting:</p> + <img width="95%" height="120px" src="../../images/epdHubEx.png"> + +<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 +priority 1 +defaultIsClosed 0 </code></pre> + +<pre><code>name cage +label CAGE +priority 2 +defaultIsClosed 0 </code></pre> + +<pre><code>name rampage +label RAMPAGE +priority 3 +defaultIsClosed 0 </code></pre> + +<pre><code>name fantom5 +label Fantom5 +priority 4 +defaultIsClosed 0</code></pre> + +<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> +</ul> + + +<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> + +<p>Attaching the EPD Viewer Hub with these group settings will then display the tracks within +the groups:</p> + <img width="95%" height="350px" src="../../images/epdHubGroups.png"> + + <!-- ========== 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 variable just after the "hgTracks" portion of the URL so that it reads