4a87b1269ea7ed40e2904c15bafda61f62d4f567 mspeir Wed Jan 7 11:33:28 2026 -0800 Adding information about include statements to hub docs, refs #20909 diff --git src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html index 7e78ea86769..4450c877db2 100755 --- src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html +++ src/hg/htdocs/goldenPath/help/hgTrackHubHelp.html @@ -6,30 +6,31 @@ <!--#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="#Includes">Using include statements for large Track Hubs</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. <li> <a href="assemblyHubHelp.html" target="_blank">Assembly Hub User Guide</a></li> <li> @@ -1078,30 +1079,73 @@ <!-- ========== Adding Filters to Track Hub ============================== --> <a name="Filters"></a> <h2>Adding Filters to your Track Hub</h2> <p> The Genome Browser supports three varieties of data filter options for bigBed data. These can improve data usability in many ways, such as displaying specific data by default (e.g. only items that pass certain quality scores), allow for filtering based on pre-specified categories (e.g designate only LINE repetitive elements from a list of options) and more.</p> <p> For more information on the options available and examples on how to set up filters, see our <a href="hubQuickStartFilter.html" target="_blank">Track Hub Filters Quick Start Guide</a> and the filter entries in the <a href="trackDb/trackDbHub.html#filter" target="_blank"> Track Database Definition Document</a>.</p> +<!-- ========== Using include statements for large Track Hubs ============================== --> +<a name="Includes"></a> +<h2>Using include statements for large Track Hubs</h2> +<p> +Track Hubs also support the use of include statements, which allow one to insert a file +containing a set of trackDb stanzas into the primary trackDb. This can be useful when you +have a hub where you have the same track across several assemblies, e.g. you're creating +a new gene annotation pipeline and have generated predictions across several species to +compare. You can also use include statements for breaking up large, complex track configurations, +such as those with several large <a href="trackDb/trackDbHub.html#groupingTracks" +>container tracks</a>. You can put the trackDb configuration stanzas for each container +track into a separate file and then use an include statement in the primary trackDb.txt +to pull them all into your hub. Include statements also function with the +<a href="hgTracksHelp.html#UseOneFile">useOneFile setting</a>.</p> + +<p>Here's an example of what your hub directory structure might look like: +<pre><code>myHub/ - directory containing track hub files + +hub.txt +genomes.txt +trackDb.geneAnnotations.txt +hg38/ + trackDb.txt + gene_annotations.bigBed + trackDb.cell_type_rnaseq.txt + rnaseq_files/ + ... +mm10/ + trackDb.txt + gene_annotations.bigBed +</code></pre> +<p> +To include these two trackDb files for hg38, you would add +the following lines to your <code>hg38/trackDb.txt</code>: +<pre><code>include ../trackDb.geneAnnotations.txt +include trackDb.cell_type_rnaseq.txt +</code></pre> +<p><b>Note:</b> Using include statements may cause slower load times on high-latency +connections due to our software checking the time of all included files. +If this is the case, you should avoid include statements and instead concatenate your +trackDb files. This shouldn't be a problem on low-latency connections. +</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="publicHubGuidelines.html" target="_blank">Public Hub 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