f49623d03093fdc8e7f06b65abb0b77efad6a3b9 Merge parents bbabbd5d256 7ec5fd8d353 mspeir Sun Oct 26 12:19:55 2025 -0700 fixed merge conflict. diff --cc src/hg/htdocs/goldenPath/help/hubBasics.html index 9ddd7a5821a,19df6a02d91..e09ea0f79b0 --- src/hg/htdocs/goldenPath/help/hubBasics.html +++ src/hg/htdocs/goldenPath/help/hubBasics.html @@@ -1,401 -1,406 +1,412 @@@ <!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><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#hubDeveloper">Track Data Hub</a> page to - check your hub for errors or to disable file caching to + check 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 begin, here is 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. + them. There is also a version provided without the explanations. <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>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 use this as a starting point, changing our default values to those for your hub. + These settings control how your hub is labeled in the interface and contact information: <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 - corresponding plain-text formats. Together they should cover much + The most common <a href="/FAQ/FAQformat.html">track types</a> are bigBed and bigWig. Compressed, binary versions of + the corresponding plain-text formats. Together they should cover most of what you might want to display in the Genome Browser, from transcription peaks to - RNA-seq results. + RNA-seq signals. <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 + Your file must start with a minimum of 3, and up to 12, standard fields, 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#utilities_downloads">download + our <a href="https://hgdownload.gi.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 ++<<<<<<< HEAD + be a URL (replace "genNom" with the assembly name (e.g. hg38)): + http://hgdownload.gi.ucsc.edu/goldenPath/genNom/bigZips/genNom.chrom.sizes. + If you're working with a GenArk assembly hub, then the chrom.sizes ++======= + be a URL (e.g. hg38): + <a href="https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.chrom.sizes"> + https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.chrom.sizes</a>. + If you're working with a <a href="https://hgdownload.soe.ucsc.edu/hubs/"> + GenArk assembly hub</a> (e.g. GCF/GCA), then the chrom.sizes ++>>>>>>> 7ec5fd8d353ae3486915167a5d57c84cb0cb918f 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="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, 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 + 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 </code></pre> <p>The type line consists of three parts: <ul> - <li>"bigBed" is the basic track type + <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 - ".". + "." (e.g. type bigBed 12 .). </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 + display, from decorators to highlights. Additionally, it offer extensive + <a href="/goldenPath/help/hubQuickStartFilter.html"> + filter controls</a>, <a href="/goldenPath/help/hubQuickStartSearch.html"> + searching options</a>, 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: + genome signal 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="https://hgdownload.soe.ucsc.edu/downloads.html#utilities_downloads">download + our <a href="https://hgdownload.gi.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.gi.ucsc.edu/goldenPath/genNom/bigZips/genNom.chrom.sizes. - If you're working with a GenArk assembly hub, then the chrom.sizes + be a URL (e.g. hg38): + <a href="https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.chrom.sizes"> + https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.chrom.sizes</a>. + If you're working with a <a href="https://hgdownload.soe.ucsc.edu/hubs/"> + GenArk assembly hub</a> (e.g. GCF/GCA), 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>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 + 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>). + all tracks require 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"> <a name="grouping"></a> <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. + together under a single container. <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"> <a name="description"></a> <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> <a name="sharing"></a> <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: + on the assembly of interest. There are three <a href="/FAQ/FAQlink.html">URL parameters</a> + 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> <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" -->