04910adfb418b9ad6e9c27c13de57a4c01ee9211 dschmelt Mon Nov 9 12:04:33 2020 -0800 Typo fixes and clarity improve refs #26462 diff --git src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html index 91b8f80..c9016f1 100755 --- src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html +++ src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html @@ -112,31 +112,31 @@ <a name="Assembly"></a> <h2>What Are Assembly Hubs?</h2> <p> Assembly Data Hubs extend the functionality of Track Data Hubs to assemblies that are not hosted natively on the Browser. Assembly Data Hubs were developed to address the increasing need for researchers to annotate sequence for which UCSC does not provide an annotation database. They allow researchers to include the underlying reference sequence, as well as data tracks that annotate that sequence. Sequence is stored in the UCSC twoBit format, and the annotation tracks are stored in the same manner as Track Data Hubs. For more information on how to setup your own Assembly Data Hub, please refer to the <a href="http://genomewiki.ucsc.edu/index.php/Assembly_Hubs">Assembly Hub wiki</a> and see the <a href="hubQuickStartAssembly.html" target="_blank">Quick Start Guide to Assembly Hubs</a>.</p> <!-- ========== Viewing Hub Tracks in the Browser ==================== --> <a name="View"></a> -<h2>Viewing Track Hubs in the browser</h2> +<h2>Viewing Track Hubs</h2> <h3>Public hubs</h3> <p> The Genome Browser provides links to a collection of public track hubs that have been registered with UCSC. To view a list of the public track hubs available, click into the blue navigation bar "My Data" and then "Track Hubs" to reach the <a href="../../cgi-bin/hgHubConnect?#publicHubs">Public Track Hubs page</a>. You can click links in the "Description" column to see details about a particular Hub. To view a hub's data, click on an assembly name on the row of your hub or the "Connect" button. If you clicked the "Connect" button, choose your assembly or click the "Genome Browser" link from the top blue bar to be brought to the default assembly. The selected hub tracks will be listed in a separate track group below the browser image and can be <a href="hgTracksHelp.html#FineTuning">configured</a> just like native browser tracks. Exercise caution when viewing a wide region that requires the Genome Browser to display a large number of track features: the browser display may time out. </p> @@ -155,33 +155,33 @@ <a href="hgSessionHelp.html">sessions</a> and <a href="hgTracksHelp.html#CustomTracks">custom tracks</a> in the same manner as other tracks. The data underlying data hub tracks can be viewed, manipulated, and downloaded using the <a href="../../cgi-bin/hgTables">UCSC Table Browser</a>. To remove a track hub from your Genome Browser display, click the "Disconnect" button on the Track Hubs page.</p> <p> For confidential or private data, please note that unlisted hubs are not secure. The URL helps to hide the location of the data; it is a simple barrier of obscurity. Please also know that hubs can be loaded from local directories when using <a href="hubQuickStartAssembly.html#blatGbib">GBiB</a>.</p> <a name="Sharing"></a> <h2>Sharing Track Hubs</h2> <p>When sharing track hubs on a single assembly, we recommend using <a href="../../cgi-bin/hgSession">Saved Sessions</a> -(for manuscripts, publications). These have the advantage -of being able to save and share configuration settings made on other browser tracks. -If you are just starting, an overview of the proces is to make the hub on +(especially for publications). These have the advantages +of being single-click access and sharing a full browser configuration. +If you are just starting, an overview of the process is to make the hub on your web-accessible server, attach the hub to the Genome Browser, configure browser position and related tracks, then <a href="../../cgi-bin/hgSession"> save your named session</a> and share the session link. Your session links will be in the following format with your chosen username and session name:</p> <ul> <li><a href="http://genome.ucsc.edu/s/ExampleUser/TrackHubSession"> http://genome.ucsc.edu/s/ExampleUser/TrackHubSession</a></li> </ul> <p>We have additional resources about Saved Session <a href="hgSessionHelp.html#HowToShare" target="_blank">sharing</a> and <a href="hgSessionHelp.html#Create" target="_blank"> backup to a file</a>.</p> <p> If you prefer URL manipulation, it is also possible to add or @@ -629,33 +629,33 @@ 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> <!-- ========== Debugging and Updating Track Hubs ============================== --> <a name="Debug"></a> -<h2>Debugging and updating Track Hubs</strong></h2> +<h2>Debugging Track Hubs</strong></h2> -<h3>Changing udcTimeout to debug hub display</h3> +<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=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> @@ -667,31 +667,31 @@ 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 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 the warning that the hub has no hub description page, no configuration errors, -and "Dispay load times" checked:</p> +and "Display load times" checked:</p> <p class='text-center'> <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 @@ -725,31 +725,31 @@ for an import to fail include typos in the URL, a hub server that is offline, or errors in the track hub configuration files. Occasionally, remote track hubs may be missing, off-line, or otherwise unavailable. If a user is already browsing data from the remote hub when it disconnects, a yellow error message will be displayed instead of the expected data.</p> <!-- ========== Setting Up Track Item Search ============================== --> <a name="Search"></a> <h2>Setting up track item search</h2> <p> The Genome Browser supports searching for items within bigBed tracks in track data hubs. To support this behavior you have to add an index to the bigBed file when you initially create the the bigBed file from the bed file input. Indices are usually created on the name field of the bed, but can be created on any field of the bed. Free-text searches can also be enabled by creating a <a href="trix.html">TRIX index file</a> that maps id's in the track to free-text metadata. Further -intructions can be found in the <a href="hubQuickStartSearch.html">Searchable Hub Quick Start +instructions can be found in the <a href="hubQuickStartSearch.html">Searchable Hub Quick Start Guide</a>.</p> <p> See the searchIndex and searchTrix fields in the <a href="trackDb/trackDbHub.html">Hub Track Database Definition document</a> for information on how to set up your bigBed to enable searching. The searchIndex setting requires the input BED data to be case-senstive sorted (<code>sort -k1,1 -k2,2n</code>). You can use either the example UNIX <code>sort</code> command or the <code>bedSort</code> utility available <a href="http://hgdownload.soe.ucsc.edu/admin/exe/" target="_blank">here</a>. See an example <a href="examples/hubExamples/hubIndexedBigBedSearchable/" target="_blank">searchable hub</a>.</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 @@ -757,31 +757,31 @@ <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 description html pages for your data that display any available references and an email contact for further data questions.</p> <p> Alternatively, you can share your track hub with selected colleagues by providing them with the URL needed to load your hub via the My Hubs tab.</p> <!--Note: Probably should add a blurb about (lack of) security here. Maybe just expand this section to be about sharing hub data.--> <!-- ======== Testing hub compatibility between genome browsers ============== --> <a name="Compatibility"></a> -<h2>Testing hub compatibility between genome browsers</h2> +<h2>Checking Hub settings and Compatibility</h2> <p> Due to the growth in popularity of the track hub format, other genome browsers have begun supporting the UCSC track hub format. The hubCheck utility can be used to check the compatibility of your hub with the UCSC Genome Browser and other genome browsers. The following examples describe various settings that may be useful to you as you test this compatibility.</p> <p> <strong><em>Example 1:</em></strong> Listing the trackDb settings and their support levels and filtering them by support level.</p> <p> You can see all of the currently supported trackDb settings and their support level in the UCSC Genome Browser by running hubCheck with the "-settings" option:</p> <pre><code>$ hubCheck -settings </code></pre> @@ -981,31 +981,31 @@ <img height="400px" src="../../images/cyverseSendToGenomeBrowser.png"> </div> <p>And then edit the fields of your <em>hub.txt</em>, <em>genomes.txt</em>, and <em>trackDb.txt</em> files like so:</p> <div class="text-center"> <img height="500px" width="1000px" src="../../images/cyverseEditedPaths.png"> </div> <p>To get the correct links to bigData files, again be sure to use the "Send To: Genome Browser" links in the menu. </p> <p> Please see the <a href="https://wiki.cyverse.org/wiki/display/DEmanual/Viewing+Genome+Files+in+a+Genome+Browser" target="_blank"> Viewing Genome Files in a Genome Browser</a> wiki page on the CyVerse wiki for more information (please note the difference of the Data Commons for final curated publication material, -and the Discovery Envirnoment for developing data). +and the Discovery Environment for developing data). Please direct any questions about CyVerse or the Discovery Environment to their <a href="http://www.cyverse.org/learning-center/ask-cyverse" target="_blank">Ask CyVerse</a> page or contact Cyverse support staff directly via the blue Intercom button on the bottom right of the Discovery Environment page. <!-- Galaxy stub <h3>Hosting Hubs on Galaxy</h3> <p> Galaxy is </p> --> <h3>Hosting Hubs on Github</h3> <p> <a href="https://github.com" target="_blank">Github</a> supports byte-range access to files when they are accessed via the <em><b>raw.githubusercontent.com</b></em> style URLs. To obtain a raw URL to a file already uploaded on Github, click on a file in your repository and click the <em>Raw</em> button:</p>