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 @@ + + + + + + +

Track Hub Basics

+ +

+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. +

+ +

+This page covers the basics of setting up your own hub: +

    +
  1. Creating your hub.txt +
  2. Common track types and their configuration +
  3. Grouping tracks +
  4. Creating description pages +
  5. Sharing and linking to your hub +
+

+ +

+As you build your hub, use the "Hub Development" tab on the Track Data Hub page to +check your hub for errors or to disable file caching to +see your changes immediately rather than after the 300ms refresh +rate. +

+ +

Example hub.txt

+

+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. + +

+

+ +

Creating your own hub.txt

+

+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: +

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
+
+

+If you have tracks across multiple assemblies, +see the full track hub documentation.

+ +

Common Track Types

+

+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. + +

bigBed Tracks

+

+You can use bigBed tracks to display discrete annotations, such as genes, transcription +start sites, or conserved genomic elements. The bigBed format builds off the +plain-text BED format 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. + +

Building a bigBed

+

+Next, we'll discuss how to build a bigBed from a bed file. + +

    +
  1. Download the bedToBigBed utility for your system type from + our download + server. +
  2. Use bedToBigBed to build your bigBed: +
    bedToBigBed -sort in.bed chrom.sizes myBigBed.bb
    + +
  3. Put your bigBed file alongside your hub.txt in a web-accessible location +
  4. You will use the file name (e.g. "myBigBed.bb") with the bigDataUrl setting in your hub.txt +
+ +

bigBed track hub configuration

+

+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: +

+

track bigBedRequiredSettings
+shortLabel bigBed Required Settings
+longLabel A bigBed Example with Required Settings
+visibility pack
+type bigBed 12 +
+bigDataUrl gtexCaviar.chr7_155799529-155812871.bb
+
+

The type line consists of three parts: +

+

Here is a screenshot of what this basic bigBed track looks like displayed in the Genome Browser: +
+ + +

+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 trackDb documentation contains a full listing of +settings available for the format. + +

+Here is the bigBed configuration with some commonly used settings, including +filtering and mouseover configuration. +

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
+
+ +

+And here is what that track looks like in the Genome Browser: +
+ + +

+These common settings added options to the track configuration pop-up: +
+ + +

bigWig Tracks

+

+You can use bigWig 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: +wiggle or +bedGraph. + +

Building a bigWig

+

+Next, we'll discuss how to build a bigWig from a wig or bedGraph file. + +

    +
  1. Download the wigToBigWig utility for your system type from our download server. +
  2. Use this utility to build your bigWig: +
    wigToBigWig in.bedGraph chrom.sizes myBigWig.bw
    + +
  3. Place your bigWig file in a web-accessible location alongside your hub.txt +
  4. You will use the file name (e.g. "myBigWig.bw") with the bigDataUrl setting +
+ +

bigWig track hub configuration

+

+The basic trackDb configuration for a bigWig track is similar to a bigBed track as +all tracks required the same basic settings (track, shortLabel, longLabel, type, bigDataUrl). +This is what the configuration for a bigWig track might look like (the example +hub.txt includes other useful settings): +

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
+
+

The type line consists of two parts: +

+ +

+Here is what this looks like visualized in the Genome Browser: +
+ + +

Grouping tracks

+

+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. + +

Composite Tracks

+

+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. + +

+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. +

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
+
+

+This composite track configuration will display like so: +
+ + +

Super Tracks

+

+Super tracks are a more general type of container. They can contain tracks of +different types and even composites. + +

+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. +

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
+
+ +

+Loading the example hub with this super track onfiguration looks like this: +
+ + +

Creating description pages

+

+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. + +

+We provide an example description html that you can modify with +the details for your track. Once you've modified this example html for your +track add an html to the corresponding track stanza: +

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
+
+ + +

Sharing your hub

+

+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. + +

+The first option is to create a session link, +which requires a Genome Browser account. +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. + +

+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: +

+

+You will then append these to a genome browser URL. For example, this url with load the example hub: +

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
+
+ + + + +