UCSC Genome Bioinformatics

Basic Hub Quick Start Guide

Hubs are a method of displaying remote custom tracks quickly (binary indexed bigBed, bigWig, BAM or VCF formats), while providing more persistence and flexibility than normal custom tracks for any UCSC assembly (or remotely-hosted assembly in twoBit format).

    STEP 1: In a publicly-accessible directory, copy the hub.txt, genomes.txt, trackDb.txt files using the following commands:
    curl -O http://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hub.txt
    curl -O http://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/genomes.txt
    mkdir hg19
    cd hg19
    curl -O http://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hg19/trackDb.txt

    If you do not have curl, you can alternatively use a text editor and directly recreate the above three files.

    STEP 2: Paste your hub.txt link (http://yourURL/hub.txt) into the My Hubs tab of the Track Data Hubs page, then click the "Use Selected Hubs" button. It should work the same as pasting the original hub.txt file: http://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hub.txt

    STEP 3: Congratulations! Your hub should display! If you are not already browsing the hg19 assembly on chr21, change assemblies and navigate to the gene SOD1 to see data displayed for each of the hub's BAM, bigWig, bigBed, and VCF tracks.

    If you are having problems, be sure all your files and the hg19 directory are publicly-accessible. For hubs to work, your server must also accept byte-ranges. You can check using the following command to verify "Accept-Ranges: bytes" displays:
    curl -I http://yourURL/hub.txt

The Three Parts of a Hub
  • Understanding hub.txt
  • Understanding genomes.txt
  • Understanding trackDb.txt
    Example Hub Directory
    Example Hub Directory

    Now that you have a working hub copied from above, you can edit the three main text documents to get an idea of how they work, and also point to your local files.

    Hubs begin with the short hub.txt, which describes your hub and informs the UCSC Browser where to find the underlying assemblies by defining the location of genomes.txt. The genomes.txt file outlines the hub's assemblies and defines the location of each assembly's trackDb.txt, which is basically the heart of your hub, defining the location of all the binary indexed track data for each assembly.

    The hub.txt file can be as short as four lines, and the genomes.txt as short as two. The trackDb.txt file is typically much larger. At its most basic, it defines the tracks in the hub using stanzas about the type, location, and name of the binary files to display. However, it provides real power to tailor your presentation using additional trackDb settings.

    Note that the Browser waits 300 seconds before checking for any changes to these files. When editing hub.txt, genomes.txt,and trackDb.txt, shorten this delay by adding udcTimeout=1 to your URL. For more information, please see the Debugging and Updating Track Hubs section of the Track Hub User Guide.

    For more detailed instructions on setting up a hub, please see the Setting Up Your Own Track Hub section of the Track Hub User Guide.

Resources:

Understanding hub.txt

hub MyHubsNameWithoutSpaces
shortLabel My Hub's Name
longLabel Name up to 80 characters versus shortLabel limited to 17 characters
genomesFile genomes.txt
email myEmail@address
descriptionUrl aboutMyHub.html
A hub starts with a few short lines in hubs.txt. The hub.txt file informs the UCSC Browser where to find the underlying assemblies via the genomesFile genomes.txt line, which in turn will direct the Browser to each assembly's related binary indexed track data outlined in the trackDb.txt. The optional descriptionUrl field allows you to add a HTML page describing your hub. See a basic example hub.txt.


Understanding genomes.txt

genome assembly_database_1
trackDb assembly_1_path/trackDb.txt

genome assembly_database_2
trackDb assembly_2_path/trackDb.txt

The genomes.txt text file can be as short as a two-line stanza when using only one UCSC assembly (e.g., genome panTro4 and trackDb panTro4/trackDb.txt). The genome line explains to the Browser to use the panTro4 chimp genome, while the trackDb line points the Browser to the associated trackDb.txt which will outline all of the assembly's tracks. See a basic example genomes.txt.


Understanding trackDb.txt

track uniqueNameNoSpacesOrDots
type track_type
bigDataUrl track_data_url
shortLabel label 17 chars
longLabel long label up to 80 chars

The trackDb.txt file uses stanzas for each track to inform the Browser of the name, type, location, and description of each binary file to display. The trackDb settings allow further display control such as by adding the line color 255,0,0 to define a track's color. Each track type (bigBed, bigWig, bam, and vcfTabix) has further customizable trackDb settings. The bigDataUrl can be a relative path to a local file or a publicly-accessibly URL that accepts byte-ranges. The trackDb.txt also allows for advanced track grouping known as composites, superTracks and multiWigs. See a basic example trackDb.txt.