6e51c97b0bc6b5a95059f53c95c0478563c96650
mspeir
  Mon Sep 22 14:07:01 2025 -0700
adding new simplified hub help page, refs #29810

diff --git src/hg/htdocs/goldenPath/help/hubBasics.html src/hg/htdocs/goldenPath/help/hubBasics.html
new file mode 100755
index 00000000000..68d0659fb9f
--- /dev/null
+++ src/hg/htdocs/goldenPath/help/hubBasics.html
@@ -0,0 +1,381 @@
+<!DOCTYPE html>
+<!--#set var="TITLE" value="UCSC Genome Browser: Hub Basics" -->
+<!--#set var="ROOT" value="../../" -->
+
+<!--#include virtual="$ROOT/inc/gbPageStart.html" -->
+
+<h1>Track Hub Basics</h1>
+
+<p>
+Track Hubs are web-accessible directories of genomic data that can be viewed on
+the UCSC Genome Browser.  They allow you to display a set of custom annotations
+on an assembly (or assemblies) of your choice and offer several advantages over
+custom tracks, including more display configuration options, more track
+organization options, more control over your data, and easier updates to that
+data.
+</p>
+
+<p>
+This page covers the basics of setting up your own hub:
+<ol>
+  <li>Creating your hub.txt
+  <li>Common track types and their configuration
+  <li>Grouping tracks
+  <li>Creating description pages
+  <li>Sharing and linking to your hub
+</ol>
+</p>
+
+<p>
+As you build your hub, use the "Hub Development" tab on the <a
+href="../../cgi-bin/hgHubConnect">Track Data Hub</a> page to
+check your hub for errors or to disable file caching to
+see your changes immediately rather than after the 300ms refresh
+rate.
+</p>
+
+<h2>Example hub.txt</h2>
+<p>
+To begin, we want to provide an example hub.txt that has been created in a way
+to make it easy to swap in your data URLs in place of our examples. It
+indicates what settings are required and includes many optional settings that
+can help elevate your tracks beyond the basics. Alongside these settings, it
+includes short explanations of how those settings work and how to configure
+them, but there is also a version provided without these.
+
+<p>
+<ul>
+  <li><a href="examples/hubExamples/hubBasicSettings/hub.txt"
+  target="_blank"><b>Example hub.txt with explanations</b></a></li>
+  <li><a href="examples/hubExamples/hubBasicSettings/hub.simple.txt"
+  target="_blank"><b>Example hub.txt no explanations</b></a></li>
+  <li><a href=""
+  target="_blank">Visualize this example hub.txt</a></li>
+</ul>
+
+<h2>Creating your own hub.txt</h2>
+<p>
+The first step in creating a track hub is to create your hub.txt file. Download the example hub.txt
+and use this as a starting point, changing our default values to those for your hub. But, we'll also
+provide the necessary settings here. These settings control how your hub is labeled in the interface
+and contact information:
+<pre><code>hub myExampleHub # a short, unique identifier for your hub, no spaces
+shortLabel Example Hub
+longLabel Example Hub for useOneFile option
+useOneFile on
+email genome-www@soe.ucsc.edu
+
+genome hg38
+</pre></code>
+<p>
+If you have tracks across multiple assemblies,
+see the <a href="hgTrackHubHelp.html">full track hub documentation</a>.</p>
+
+<h2>Common Track Types</h2>
+<p>
+The most common track types are bigBed and bigWig, compressed, binary versions of
+corresponding plain-text formats. Together they should cover much
+of what you might want to display in the Genome Browser, from transcription peaks to
+RNA-seq results.
+
+<h2>bigBed Tracks</h2>
+<p>
+You can use <a href="bigBed.html">bigBed</a> tracks to display discrete annotations, such as genes, transcription
+start sites, or conserved genomic elements. The bigBed format builds off the
+plain-text <a href="FAQ/FAQformat.html#format1">BED format</a> and is thus flexible in terms of what fields are included.
+Your file must start with a set of 12 standard fields (though not necessarily all of them), but
+can also extend the format with any number of additional fields.
+
+<h3>Building a bigBed</h3>
+<p>
+Next, we'll discuss how to build a bigBed from a bed file. 
+
+<ol>
+  <li>Download the <code>bedToBigBed</code> utility for your system type from
+      our <a href="https://hgdownload.soe.ucsc.edu/downloads.html">download
+      server</a>.
+  <li>Use <code>bedToBigBed</code> to build your bigBed:
+      <pre><code>bedToBigBed -sort in.bed chrom.sizes myBigBed.bb</code></pre>
+    <ul>
+      <li>If your assembly is a UCSC-hosted assembly (e.g. hg38), chrom.sizes can
+          be a URL (replace &quot;genNom&quot; with the assembly name (e.g. hg38)):
+          http://hgdownload.soe.ucsc.edu/goldenPath/genNom/bigZips/genNom.chrom.sizes.
+          If you're working with a GenArk assembly hub, then the chrom.sizes
+          file can be found under the "Data file downloads" section on the
+          <a href="../../cgi-bin/hgGateway" target="_blank">assembly gateway page</a>.
+      <li>If you have custom fields in your bed file, you will need to create a custom .as file.
+          You can download the <a href="">basic BED .as</a> and modify this by adding new fields 
+          below those in your file. 
+    </ul>
+  <li>Put your bigBed file alongside your hub.txt in a web-accessible location
+  <li>You will use the file name (e.g. &quot;myBigBed.bb&quot;) with the <code>bigDataUrl</code> setting in your hub.txt
+</ol>
+
+<h3>bigBed track hub configuration</h3>
+<p>
+Once you have built your bigBed files, it is time to create a stanza in your
+hub.txt file for that track. Here is what the required settings discussed above
+might look like for a basic bigBed track:
+<p>
+<pre><code>track bigBedRequiredSettings
+shortLabel bigBed Required Settings
+longLabel A bigBed Example with Required Settings
+visibility pack
+type bigBed 12 +
+bigDataUrl gtexCaviar.chr7_155799529-155812871.bb
+</code></pre>
+<p>The type line consists of three parts: 
+<ul>
+  <li>&quot;bigBed&quot; is the basic track type
+  <li>&quot;12&quot; indicates how many standard BED fields are included in
+  your file. You may need to change this to match the number of standard BED
+  fields in your file.
+  <li>&quot;+&quot; tells the genome browser there are extra fields beyond the
+  standard fields. If your file has no extra fields, replace this with a
+  &quot;.&quot;.
+</ul>
+<p>Here is a screenshot of what this basic bigBed track looks like displayed in the Genome Browser:
+<br>
+<img src="../../images/bigBedReqSettings.png">
+
+<p>
+The bigBed format also offer a wide range of customization options for the
+display, from decorators to highlights. Additionally, they offer extensive
+filter controls, searching options, and mouseover configurations. Our <a
+href="trackDb/trackDbHub.html"
+target="_blank">trackDb documentation</a> contains a full listing of
+settings available for the format.
+
+<p>
+Here is the bigBed configuration with some commonly used settings, including
+filtering and mouseover configuration.
+<p><pre><code>track bigBedCommonSettings
+shortLabel bigBed Common Settings
+longLabel A bigBed Example with Commonly Used Settings
+visibility pack
+type bigBed 12 +
+bigDataUrl gtexCaviar.chr7_155799529-155812871.bb
+filterLabel.cpp CPP (Causal Posterior Probability)
+filter.cpp 0
+filterLabel.geneName Gene Symbol
+filterText.geneName *
+mouseOver $name; CPP: $cpp
+</code></pre>
+
+<p>
+And here is what that track looks like in the Genome Browser:
+<br>
+<img src="../../images/bigBedCommonSettings.png">
+
+<p>
+These common settings added options to the track configuration pop-up:
+<br>
+<img src="../../images/bigBedCommonSettingsPopUp.png">
+
+<h2>bigWig Tracks</h2>
+<p>
+You can use <a href="bigWig.html">bigWig</a> to tracks to display continuous
+annotations, such as RNA-seq expression, conservation scores, or other
+genome-wide scores. You can build a bigWig using one of two plain-text formats:
+<a href="wiggle.html" target="_blank">wiggle</a> or
+<a href="bedgraph.html" target="_blank">bedGraph</a>. 
+
+<h3>Building a bigWig</h3>
+<p>
+Next, we'll discuss how to build a bigWig from a wig or bedGraph file. 
+
+<ol>
+  <li>Download the <code>wigToBigWig</code> utility for your system type from our <a href="">download server</a>.
+  <li>Use this utility to build your bigWig:
+      <pre><code>wigToBigWig in.bedGraph chrom.sizes myBigWig.bw</code></pre>
+    <ul>
+      <li>If your assembly is a UCSC-hosted assembly (e.g. hg38), chrom.sizes can
+          be a URL (replace &quot;genNom&quot; with the assembly name (e.g. hg38)):
+          http://hgdownload.soe.ucsc.edu/goldenPath/genNom/bigZips/genNom.chrom.sizes.
+          If you're working with a GenArk assembly hub, then the chrom.sizes
+          file can be found under the "Data file downloads" section on the
+          <a href="../../cgi-bin/hgGateway" target="_blank">assembly gateway page</a>.
+    </ul>
+  <li>Place your bigWig file in a web-accessible location alongside your hub.txt
+  <li>You will use the file name (e.g. &quot;myBigWig.bw&quot;) with the <code>bigDataUrl</code> setting
+</ol>
+
+<h3>bigWig track hub configuration</h3>
+<p>
+The basic trackDb configuration for a bigWig track is similar to a bigBed track as
+all tracks required the same basic settings (<code>track, shortLabel, longLabel, type, bigDataUrl</code>). 
+This is what the configuration for a bigWig track might look like (the example
+hub.txt includes other useful settings):
+<p><pre><code>track bigWigExample
+shortLabel bigWig Example
+longLabel A bigWig Example with Commonly Used Settings
+visibility pack
+type bigWig -20 10.003
+bigDataUrl hg38.phyloP100way.chr7_155799529-155812871.bw
+color 60,60,140
+</code></pre>
+<p>The type line consists of two parts: 
+<ul>
+  <li>&quot;bigWig&quot; is the basic track type
+  <li>&quot;-20 10.003&quot; indicates the minimum and maximum of the data in the bigWig
+</ul>
+
+<p>
+Here is what this looks like visualized in the Genome Browser:
+<br>
+<img src="../../images/bigWigReqSettings.png">
+
+<h2>Grouping tracks</h2>
+<p>
+Next, we'll provide a basic overview of how to group your tracks using
+composite tracks and super tracks. This will allow you to pull similar data
+together under a single track.
+
+<h3>Composite Tracks</h3>
+<p>
+Composite tracks can hold multiple tracks of the same type. For example, you
+use a composite to group together a set of RNA-seq experiments including
+replicates.
+
+<p>
+Here's what the configuration might look like for a composite containing two
+bigWig tracks. There are two key components of a composite: (1) the line
+"compositeTrack on" in the parent track stanza, and (2) including "parent
+compositeName" for each track that will be part of the composite.
+<p><pre><code>track compositeExample
+shortLabel Example Composite Track
+longLabel Example composite track using bigWigs
+visibility dense
+type bigWig
+compositeTrack on
+
+    track compositeBigWig1
+    bigDataUrl a.chr7_155799529-155812871.bw
+    shortLabel bigWig #1
+    longLabel bigWig in Composite Track Example #1
+    parent compositeExample
+    type bigWig 0 1
+    color 255,0,0
+    autoScale group
+    visibility dense
+
+    track compositeBigWig2
+    bigDataUrl c.chr7_155799529-155812871.bw
+    shortLabel bigWig #2
+    longLabel bigWig in Composite Track Example #2
+    parent compositeExample
+    type bigWig 0 1
+    color 0,255,0
+    autoScale group
+    visibility dense
+</code></pre>
+<p>
+This composite track configuration will display like so:
+<br>
+<img src="../../images/compositeBigWig.png">
+
+<h3>Super Tracks</h3>
+<p>
+Super tracks are a more general type of container. They can contain tracks of
+different types and even composites. 
+
+<p>
+Configuring a basic super track is quite similar to composite tracks. 
+There are two key components of a composite: (1) the line
+"superTrack on" in the parent track stanza, and (2) including "parent
+superTrackName" for each track that will be part of the super track.
+<p><pre><code>track superTrackExample
+shortLabel Super Track Example
+longLabel A super-track of related data of various types together: individual, multiWig, and composite
+superTrack on show
+html examplePage
+    
+    track superTrackbigBed
+    parent superTrackExample
+    bigDataUrl gtexCaviar.chr7_155799529-155812871.bb
+    shortLabel ST bigBed example
+    longLabel A super-track-contained bigBed
+    type bigBed 12 +
+    visibility squish
+    priority 30
+    
+    track superTrackCompositeBigWig
+    parent superTrackExample
+    compositeTrack on
+    shortLabel ST Composite bigWig
+    longLabel A composite track in a super track grouping bigWigs
+    visibility dense
+    type bigWig
+    priority 60
+        
+        track superTrackCompositeBigWig1
+        bigDataUrl a.chr7_155799529-155812871.bw
+        shortLabel ST bigWig composite #1
+        longLabel A composite-contained bigWig in a super track example #1
+        parent superTrackCompositeBigWig on
+        type bigWig 0 1
+        
+        track superTrackCompositeBigWig2
+        bigDataUrl c.chr7_155799529-155812871.bw
+        shortLabel ST bigWig composite #2
+        longLabel A composite-contained bigWig in a super track example #2
+        parent superTrackCompositeBigWig on
+        type bigWig 0 1
+</code></pre>
+
+<p>
+Loading the example hub with this super track onfiguration looks like this:
+<br>
+<img src="../../images/superTrackEx.png">
+
+<h2>Creating description pages</h2>
+<p>
+If you plan to share your track hub more widely, you will want to create a description page for your tracks.
+A description page could contain a short description of what the data represents, how the data was generated,
+a link to the associated paper, or a contact email for questions regarding the data.
+
+<p>
+We provide an <a href="examples/hubExamples/templatePage.html">example description html</a> that you can modify with
+the details for your track. Once you've modified this example html for your
+track add an <code>html</code> to the corresponding track stanza:
+<p><pre><code>track bigWigExample
+shortLabel bigWig Example
+longLabel A bigWig Example with Commonly Used Settings
+type bigWig -20 10.003
+bigDataUrl hg38.phyloP100way.chr7_155799529-155812871.bw
+html bigWigDescription.html
+</code></pre>
+
+
+<h2>Sharing your hub</h2>
+<p>
+Once you have a functional hub that you would like to share with others, you
+can create links that you give to others in two ways.
+
+<p>
+The first option is to create a <a href="hgSessionHelp.html">session</a> link,
+which requires a <a href="../../cgi-bin/hgLogin">Genome Browser account</a>. 
+Load your hub, configure the genome browser as you'd like (e.g. position and
+data tracks), select "My Sessions" under "My Data", and use the option to save
+the current settings as a session. You will then be provided with a URL that
+you can share with others. 
+
+<p>
+The other option is to create a URL to the Genome Browser that loads your hub 
+on the assembly of interest. There are three URL parameters you will want to use:
+<ul>
+  <li><code>db</code> - UCSC assembly name (e.g. hg38)
+  <li><code>position</code> - chromosome position to load
+  <li><code>hubUrl</code> - URL to your hub
+</ul>
+<p>
+You will then append these to a genome browser URL. For example, this url with load the example hub:
+<pre><code>https://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&position=chr7:155799529-155812871&hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubExamples/hubBasicSettings/hub.txt
+</code></pre>
+
+<!--<h2>Making it a Public Hub</h2>
+<p>
+-->
+
+<!--#include virtual="$ROOT/inc/gbPageEnd.html" -->
+