7302f9df405d8697c5a050c03bc148218e80dc11 dschmelt Tue Jun 30 12:40:03 2020 -0700 Updating documentation #25805 diff --git src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html index a490796..d82583d 100755 --- src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html +++ src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html @@ -630,49 +630,57 @@ <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=1</strong></em> into the Genome Browser URL, which will reduce the delay to one second. 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 <em>http://genome.ucsc.edu/cgi-bin/hgTracks?<b>udcTimeout=1&</b></em> (with the remainder of the URL following the ampersand). To restore the default timeout, a warning message will appear on hgTracks with a link to clear the udcTimeout variable.</p> <a name="validate"></a> -<h3>Check hub settings using Validate Hub tool</h3> +<h3>Check hub settings using Hub Development tool</h3> <p> Hubs can be checked for valid file configuration, trackDb keywords, and composite or super track -settings with the Validate Hub tool. This tool can be accessed from the Track Hub page under -<a href="../../cgi-bin/hgHubConnect?#validateHub">the -Validate Hub tab</a>. After entering your URL in the search box, -the tool runs hubCheck like so:</p> +settings with the Hub Development tool. This tool can be accessed from the Track Hub page under +<a href="../../cgi-bin/hgHubConnect?#hubDeveloper">the +Hub Development tab</a>. After entering your URL in the search box, +the tool runs the <a href="http://hgdownload.soe.ucsc.edu/downloads.html#utilities_downloads" +target="_blank">hubCheck utility</a> program equivalent to:</p> <pre>hubCheck -noTracks http://url.to.hub.txt</pre> <p> The noTracks setting speeds up the validation process but does not check for -the presence of your remotely hosted data track files. This tool checks your hub.txt, -genome.txt, and trackDb.txt settings and displays errors in bright red font, such -as "<font color="red">Missing required setting...</font>" and "<font color="red">Cannot open...</font>". The following picture shows +the presence or validity of your remotely hosted data track files. This tool checks your hub.txt, +genome.txt, and trackDb.txt settings and displays warnings and errors in bright red font, such +as "<font color="red">Missing required setting...</font>" and +"<font color="red">Cannot open...</font>". The "Display load times" and "Enable +hub refresh" optional settings show the load timing at the bottom of the Genome Browser page +and allow instant hub refresh instead of 5 minute refresh. These options can be checked and +activated by clicking "View Hub on Genome Browser". The following picture shows <a href="examples/hubExamples/hubGroupings/hub.txt">the example track grouping hub</a> -with no configuration errors:</p> +with the warning that the hub has no hub description page, no configuration errors, +and "Dispay load times" checked:</p> <p class='text-center'> - <img class='text-center' src="../../images/validateHub.png" alt="Validate hub tool checks config setting" width="749" height="249"> - <p class='gbsCaption text-center'>The Validate Hub tool checks for proper configuration files and track hub settings.</p> + <img class='text-center' src="../../images/hubDevelopment.png" +alt="The Hub Development tool checks config setting" width="749" height="249"> + <p class='gbsCaption text-center'>The Hub Development tool checks for proper configuration +files and track hub settings, and allows access to debugging settings.</p> </p> <h3>Check hub settings using hubCheck utility</h3> <p> It is a good practice to run the command-line utility <em>hubCheck</em> on your track hub when you first bring it online and whenever you make significant changes. This utility by default checks that the files in the hub are correctly formatted, but it can also be configured to check a few other things including that various trackDb settings are correctly spelled and that they are supported by the UCSC Genome Browser. You can read more about using hubCheck to check the compatibility of your hub with other genome browsers <a href="#Compatibility"</a>below</a>. <p> Here is the usage statement for the hubCheck utility: <pre><code>hubCheck - Check a track data hub for integrity. usage: @@ -738,40 +746,40 @@ <p> By making your session file available over the Internet, you can build a URL that will load the session automatically by adding "<b>&hgS_loadUrlName=</b>" to the hgTracks CGI followed by the URL location of the saved session file. The location of the saved session file should be in the same directory that holds your hub.txt file. Finally add "<b>&hgS_doLoadUrl=submit</b>" to the URL to inform the browser to load the session.</p> <p> There are four required variables for your URL to load a session with a hub and an example URL:</p> <pre><code><strong>db</strong> - name of the assembly (e.g. hg19 or mm10) <strong>hubUrl</strong> - URL to your track hub <strong>hgS_loadUrlName</strong> - URL to your session file <strong>hgS_doLoadUrl</strong> - value should be "submit" </code></pre> <pre>http://genome.ucsc.edu/cgi-bin/hgTracks<strong>?db=</strong>hg19<strong>&hubUrl=</strong>http://myLab.org/myHub.txt<strong>&hgS_loadUrlName=</strong>http://mySession<strong>&hgS_doLoadUrl=submit</strong> </pre> <p> Another feature one can use in place of "<strong>&hubUrl=</strong>" is -"<strong>&hubClear=</strong>", which will load a hub while simultaneously disconnecting +"<strong>&hubClear=</strong>", which will load a hub while simultaneously disconnecting or clearing, hubs located at the same location. For example adding <code>&hubClear=http://university.edu/lab/folder/hub10.txt</code> would connect the referenced hub10.txt while simultaneously disconnecting any hubs that might be displayed from the same <code>http://university.edu/lab/folder/</code> directory (for example, hub1.txt, hub2.txt, ect.). This feature can be useful for dynamically generated hubs that might collect in the browser otherwise.</p> <p> -Beyond the URL options of "<strong>&hubUrl=</strong>" and "<strong>&hubClear=</strong>" +Beyond the URL options of "<strong>&hubUrl=</strong>" and "<strong>&hubClear=</strong>" there are many other <a href="../../FAQ/FAQlink.html" target="_blank">ways to link to the Browser</a> including a list of <a href="../help/customTrack.html#optParams" target="_blank">URL optional parameters</a> described in the the Custom Tracks User's Guide.</p> <!-- ========== Registering a Track Hub with UCSC ==================== --> <a name="Register"></a> <h2>Registering a Track Hub with UCSC</h2> <p> If you would like to share your track hub with other Genome Browser users, you can register your hub with UCSC by contacting the Genome Browser technical support mailing list at <a href="mailto:genome@soe.ucsc.edu">genome@soe.ucsc.edu</a>. Please include the URL of your hub.txt file in the message. Once registered, your hub will appear as a link on the Public Hubs tab on the Track Hubs page. To assist developers of Public Hubs, there is a <a href="http://genomewiki.ucsc.edu/index.php/Public_Hub_Guidelines">Public Hubs Guidelines</a> page. The page shares pointers and preferred style approaches, such as the need for creating