12d5cbaaa39bb6a0f59f5ee9c25d9cfeacf0ccc0 mspeir Mon Mar 9 10:44:36 2026 -0700 Redoing initial section of page based on feedback, refs #37080 diff --git src/hg/htdocs/goldenPath/help/trackDb/trackDbHub.v3.html src/hg/htdocs/goldenPath/help/trackDb/trackDbHub.v3.html index dda2c794fed..8fe401321f0 100755 --- src/hg/htdocs/goldenPath/help/trackDb/trackDbHub.v3.html +++ src/hg/htdocs/goldenPath/help/trackDb/trackDbHub.v3.html @@ -45,65 +45,75 @@ <!--Content Tables--> <!--outer table is for border purposes--> <div class="contentBorder"> <div class="lightBlueBar"> <div class="lightBlueBarTitle"> Track Database Definition</div> </div> <!-- Finally to the content --> <div class="borderGuard"> <DIV class="trackDbHub_intro"> <H1>Hub Track Database Definition (<SPAN id="trackDbHub_version">v3</SPAN>)</H1> <H2>How to declare Dataset Display Settings in Genome Browser Hubs</H2> <p> This page describes all of the settings one might use in creating a track or assembly hub. +Hubs display your own data in the Genome Browser by hosting your files on a web +server and connecting them with a simple text configuration file, giving you +more control and permanence than custom tracks. This initial section touches on the files and settings needed in creating a hub before providing a listing of settings separated by track type.</p> <p> For those new to creating hubs: Our <a href="/docs/hubs/hubBasics.html" -target"_blank">Hub Basics</a> page provides an introduction to creating hubs.</p> +target"_blank">Hub Basics</a> page provides a simple introduction to creating hubs.</p> <p> For returning readers: We keep a <a href="changes.html">list of changes</a> to the trackDb specification below.</p> <h3 id="hub_txt">Start with a hub.txt</h3> <p> All hubs must include a top-level hub.txt file. This file contains general settings that identify your hub in our internal databases and in the Genome Browser interface. The URL to the hub.txt is used to load your hub. Our <a href="/docs/hubs/hubBasics.html" target"_blank">Hub Basics</a> describes how to create a hub.txt. A full listing of hub.txt settings can be found in the <a HREF="#hubGeneral">General hub configuration settings</a> section below.</p> <p> If your hub contains tracks on a single genome assembly, then you can put all of the hub, genome, and track configuration settings into a single file with <code><a href="hgTracksHelp.html#UseOneFile" target="_blank">useOneFile</a></code>. <h3 id="genomes_txt">Defining your hub's genomes</h3> <p> A genomes.txt is only necessary if you are <b>NOT</b> using the <code>useOneFile</code> setting -as described <a href="#useOneFile">below</a>. If your hub contains tracks for more than one +as described <a href="#useOneFile">below</a>. When using <code>useOneFile</code>, one only needs +to include the <code><a href="#genome">genome</a></code> line. This line will reference +a UCSC assembly name (e.g. hg38) or a GenBank assembly available through our +<a href="https://hgdownload.gi.ucsc.edu/hubs" target="_blank">GenArk archive</a> +beginning with GCF or GCA (e.g. GCF_000891275.1). + +<p> +If your hub contains tracks for more than one genome, you will need to define a <a target="_blank" href="../hgTrackHubHelp.html#genomes.txt"><code>genomes.txt</code></a>. A full listing of genomes.txt settings, including those needed for an <a href="#assembly_hubs">assembly hub</a>, settings can be found in the <a -href="#assembly">Assembly hub "genome" settings</a> section below. +href="#assembly">Assembly hub "genome" settings</a> section below.</p> <h3 id="useOneFile">Use <b><code>useOneFile on</code></b> for hubs with only one genome</h3> <p> If your hub is only displaying one genome, one can use the <a target="_blank" href="../hgTracksHelp.html#UseOneFile"><code>useOneFile on</code></a> setting to put all hub, genome, and track configuration settings into a single file. Load a working example <a target="_blank" href="../examples/hubExamples/hubUseOneFile/singleFileHubExample.txt">here</a>.</p> <h3 id="trackDb_txt">Declaring track settings</h3> <P>This document describes how to set dataset display characteristics using "track database" or "trackDb" settings through name-value pair associations used in a Track Hub's trackDb.txt file. @@ -136,82 +146,76 @@ longLabel The data in this track is format "bigBed 3". </pre> <P>Every track stanza should have these five settings (<code>track type bigDataUrl shortLabel longLabel</code>). The first line's <code>track</code> key value (<code>myFirstTrack</code>) is the identifier for the dataset given to the Browser and it must be unique for each track within your data hub. After the <code>track</code> key, the most important setting is the <code>type</code> key. This value (<code>bigBed 3</code>) tells the Browser the type of format the data is in, defines how to display it, and determines which options are available for fine control of that display. For some configurable features, like <a href="#filter">filters</a>, an additional period or plus may be needed (<code>bigBed 5 .</code>) or (<code>bigBed 9 +</code>). </P> -<P>While there are over 100 settings (providing a high level of flexibility for track -display) defined in this document and supported at UCSC, only the above five -are <font class="level-required">required</font> -to define a track. The other support levels are: -<table style="margin-left: 50px;"> - <tr><td class="level-required">required</td><td>required settings</td></tr> - <tr><td class="level-base">base</td><td>common settings supported - at other sites</td></tr> - <tr><td class="level-deprecated">deprecated</td><td>settings that - are being retired (replacement is listed in details section)</td></tr> - <tr><td class="level-new">new</td><td>new settings not yet assigned - a level (may be replaced)</td></tr> - <tr><td class="level-full">full</td><td>other settings</td></tr> -</table> -</P> -<p>See the <a href="changes.html">list of changes</a> to see -recent additions. -</p> <p> -You can use the <code>hubCheck</code> utility to check the compatibility of your hub and its -trackDb settings with the UCSC Genome Browser or other genome browsers, such as Ensembl. -Our <a href="../hgTrackHubHelp.html#Compatibility">track hub help page</a> -provides some examples of how you might use <code>hubCheck</code> to do this and -you can read more in this related +Running hubCheck on your <code>hub.txt</code> file identifies errors in settings, file +paths, and formatting that could prevent your hub from loading correctly. Download hubCheck from the <a +href="https://hgdownload.soe.ucsc.edu/admin/exe/">utilities download page</a> and +see the <a href="/goldenPath/help/hgTrackHubHelp.html#Compatibility">hubCheck +documentation</a> and related <a href="https://genome-blog.gi.ucsc.edu/blog/how-portable-is-your-track-hub-use-hubcheck-to-find-out/" -target="_blank">blog post.</a></p> +target="_blank">blog post</a> +for more information on validating hubs.</p> + <h3 id="includes">Using trackDb include statements</h3> <p> Hubs also support the use of <a href="../hgTrackHubHelp.html#Includes">include statements</a>, allowing one to insert a file containing a set of trackDb stanzas into a primary trackDb. Use this when you have the same track across several assemblies, or several large, complex tracks. <h3 id="assembly_hubs">Assembly Hubs</h3> <p> Assembly hubs can display novel genome assemblies and annotations in the UCSC -Genome Browser. Most genome assemblies deposited in GenBank are also available through -our <a href="https://hgdownload.gi.ucsc.edu/hubs" target="_blank">GenArk archive</a> -and can be <a href="/goldenPath/help/hgTracksHelp.html#GenArkTrackHubs" -target="_blank">referenced in your hub configuration</a>.</p> - -<p> +Genome Browser. Note: Many genome assemblies available in GenBank are also available in our +<a href="https://hgdownload.gi.ucsc.edu/hubs" target="_blank">GenArk archive</a>. However, if your genome is not available in GenBank, you can make a custom assembly hub. -This involves creating a <a href="#assembly">genomes.txt</a> -using several settings described below in addition to a trackDb file for each -genome assembly. To create an assembly hub, refer to our +To create an assembly hub, refer to our <a href="../assemblyHubUserGuide.html" target="_blank">Assembly Hub User Guide</a> or our <a href="../hubQuickStartAssembly.html" target="_blank">Quick Start Guide to Assembly Hubs</a>.</p> +<h3 id="includes">Page Contents</h3> + <P>The remainder of this document is divided into the following sections and should be -used as a ready reference.</P> +used as a ready reference. Settings are colored based on their support level: +<table style="margin-left: 50px;"> + <tr><td class="level-required">required</td><td>required settings</td></tr> + <tr><td class="level-base">base</td><td>common settings supported + at other sites</td></tr> + <tr><td class="level-deprecated">deprecated</td><td>settings that + are being retired (replacement is listed in details section)</td></tr> + <tr><td class="level-new">new</td><td>new settings not yet assigned + a level (may be replaced)</td></tr> + <tr><td class="level-full">full</td><td>other settings</td></tr> +</table> +</P> +<p>See the <a href="changes.html">list of changes</a> to see +recent additions. +</p> <IMG class='toggle all' /> <I>Expand/close descriptions of settings in the sections below.</I> <OL> <LI><A HREF="#commonSettings">Common trackDb settings</A></LI> <LI><A HREF="#settingsByType">Settings by track type</A> – with examples <UL> <LI><A HREF="#bam">bam/cram</A>: Compressed Sequence Alignment/Map tracks</LI> <LI><A HREF="#bigBed_-_Item_or_Region_Track_Settings">bigBed</A>: Item or region tracks</LI> <LI><A HREF="#bigBarChart">bigBarChart</A>: Bar charts of categorical variables displayed over genomic regions</LI> <LI><A HREF="#bigChain_-_Pairwise_Alignments">bigChain</A>: Genome-wide Pairwise Alignments</LI> <LI><A HREF="#bigGenePred_-_Gene_Annotations">bigGenePred</A>: Gene Annotations</LI> <LI><A HREF="#bigInteract">bigInteract</A>: Pairwise interactions</LI> <LI><A HREF="#bigLolly">bigLolly</A>: Lollipops</LI> <LI><A HREF="#bigNarrowPeak_-_Peaks">bigNarrowPeak</A>: Peaks</LI> @@ -1615,31 +1619,31 @@ <div class="format"><code class="level-base">useOneFile <on></code></div> </TD></TR> <TR class="examples" VALIGN=TOP><TD class="hub_txt_example"> <IMG class='toggle detail'> <div class="format"><B>Example of an opening hub stanza</B></div> </TD></TR> </TABLE> <BR><BR> <A name="assembly"></A> <TABLE class="settingsTable" id="genomes_file_settings"> <THEAD><TR><TD><DIV ID="genomes_file_intro" class="intro"></DIV></TD></TR></THEAD> <TR VALIGN=TOP><TH><IMG class='toggle oneSection'> Assembly hub "genome" settings </TH></TR> - <TR VALIGN=TOP><TD class="hubGenome"><IMG class='toggle detail'> + <TR VALIGN=TOP><TD class="genome"><IMG class='toggle detail'> <div class="format"><code class="level-base">genome <str></code></div> </TD></TR> <TR VALIGN=TOP><TD class="trackDbFile"><IMG class='toggle detail'> <div class="format"><code class="level-base">trackDb <url/relativePath></code></div> </TD></TR> <TR VALIGN=TOP><TD class="groupsFile"><IMG class='toggle detail'> <div class="format"><code class="level-base">groups <url/relativePath></code></div> </TD></TR> <TR VALIGN=TOP><TD class="description"><IMG class='toggle detail'> <div class="format"><code class="level-base">description <str></code></div> </TD></TR> <TR VALIGN=TOP><TD class="twoBitPath"><IMG class='toggle detail'> <div class="format"><code class="level-base">twoBitPath <url/relativePath></code></div> </TD></TR> <TR VALIGN=TOP><TD class="chromAlias"><IMG class='toggle detail'>