e2628a7934646bf31d8fedb840e03177790d8bf1 mspeir Tue Oct 14 08:35:25 2025 -0700 changes based on input from Max + Lou, refs #29810 diff --git src/hg/htdocs/goldenPath/help/hubBasics.html src/hg/htdocs/goldenPath/help/hubBasics.html index 8380bda450e..143f6668adf 100755 --- src/hg/htdocs/goldenPath/help/hubBasics.html +++ src/hg/htdocs/goldenPath/help/hubBasics.html @@ -16,64 +16,68 @@ </p> <p> This page covers the basics of setting up your own hub: <ol> <li><a href="#create">Creating your hub.txt</a> <li><a href="#types">Common track types and their configuration</a> <li><a href="#grouping">Grouping tracks</a> <li><a href="#description">Creating description pages</a> <li><a href="#sharing">Sharing and linking to your hub</a> </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 +href="/cgi-bin/hgHubConnect#hubDeveloper">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.minimal.txt" + target="_blank">Minimal hub.txt</a> <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> + target="_blank"><b>Detailed hub.txt with setting explanations</b></a> or + <a href="examples/hubExamples/hubBasicSettings/hub.noExplanations.txt" + target="_blank"><b>without explanations</b></a></li> <li><a href="/cgi-bin/hgTracks?db=hg38&position=chr7:155799529-155812871&hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubExamples/hubBasicSettings/hub.txt" target="_blank">Visualize this example hub.txt</a></li> </ul> <a name="create"></a> <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 <a href="examples/hubExamples/hubBasicSettings/hub.txt">example hub.txt</a> 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 +<pre><code>hub myExampleHub # a short, unique internal identifier for your hub, no spaces +# shortLabel and longLabel are how your hub is labeled in the Genome Browser interface +# shortLabels should be under 20 characters and longLabels under 70 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> <a name="types"></a> <h2>Common Track Types</h2> <p> The most common <a href="/FAQ/FAQformat.html">track types</a> are bigBed and bigWig, compressed, binary versions of @@ -95,34 +99,37 @@ <ol> <li>Download the <code>bedToBigBed</code> utility for your system type from our <a href="https://hgdownload.soe.ucsc.edu/downloads.html#utilities_downloads">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. + You can download the <a href="examples/bed12.as">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>Put your bigBed file alongside your hub.txt in a web-accessible location, + either through <a href="/cgi-bin/hgHubConnect#hubUpload">the 10GB of space we + make available to users</a> or through one of <a href="hgTrackHubHelp#Hosting">several + other services</a> <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 @@ -189,31 +196,34 @@ <ol> <li>Download the <code>wigToBigWig</code> utility for your system type from our <a href="https://hgdownload.soe.ucsc.edu/downloads.html#utilities_downloads">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>Put your bigWig file alongside your hub.txt in a web-accessible location, + either through <a href="/cgi-bin/hgHubConnect#hubUpload">the 10GB of space we + make available to users</a> or through one of <a href="hgTrackHubHelp#Hosting">several + other services</a> <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 @@ -368,21 +378,24 @@ 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> ---> +If you feel that your hub would be of general use to the research community, +you can contact us about making it a public hub. Note that public hubs have to meet +more stringent requirements than the basics described here. +Check that your hub meets the <a href="publicHubGuidelines.html">public hub requirements</a> +and then follow the directions on that page for submitting it to us for review. <!--#include virtual="$ROOT/inc/gbPageEnd.html" -->