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 "genNom" 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. "myBigBed.bb") 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>"bigBed" is the basic track type + <li>"12" 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>"+" tells the genome browser there are extra fields beyond the + standard fields. If your file has no extra fields, replace this with a + ".". +</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 "genNom" 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. "myBigWig.bw") 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>"bigWig" is the basic track type + <li>"-20 10.003" 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" --> +