944fa6bbf93daeaac9d5223930696cccccfa5197 lrnassar Fri Mar 27 17:25:06 2026 -0700 Updating the page to improve the flow, structure, be clear that the file names need to be identical, and include a new example hub, refs #36957 diff --git src/hg/htdocs/contribTracks.html src/hg/htdocs/contribTracks.html index b39ce964bca..f26d403ed76 100755 --- src/hg/htdocs/contribTracks.html +++ src/hg/htdocs/contribTracks.html @@ -1,139 +1,200 @@ <!DOCTYPE html> <!--#set var="TITLE" value="Genome Browser Contributed Tracks" --> <!--#set var="ROOT" value="." --> <!-- Relative paths to support mirror sites with non-standard GB docs install --> <!--#include virtual="$ROOT/inc/gbPageStart.html" --> -<h1>Contributed Tracks</h1> +<h1>Contributing Tracks to the UCSC Genome Browser</h1> <p> -Researchers are creating annotations for hundreds of assemblies -in one process, or creating a number of annotations for one assembly. -It would be useful to the wider research community to have these -annotations included in the default browser view on those assemblies. +Contributed tracks are annotations produced by research groups and integrated +into the default Genome Browser view on +<a href="https://hgdownload.gi.ucsc.edu/hubs/" +target="_blank">GenArk</a> assemblies. This page describes how to +prepare and submit them. </p> -<p> -This discussion outlines procedures for submitting a set of tracks to the -browser for inclusion in the default view of a genome assembly. - This procedure is for developers of tracks that have a number of tracks -to submit to one assembly, or a set of tracks to deliver to a multiple -set of genome assemblies. -</p> +<h2>Submission workflow</h2> + +<ol> +<li>Develop and test your annotations as a + <a href="docs/hubs/hubBasics.html" + target="_blank">track hub</a> hosted on a web server you control.</li> +<li>Organize the hub following the directory structure below.</li> +<li>Send the URL of your <b>hub.txt</b> file to the + <a href="contacts.html">Genome Browser team</a> + for review and inclusion.</li> +</ol> + +<h2>Directory structure</h2> <p> -Development process: -<ul> -<li>Develop your annotations in a track hub under your control.</li> -<li>Provide a reference to your development track hub to the genome browser - for inclusion consideration.</li> -<li>By following the suggested outline, the browser will be able to - efficiently add your annotations to the genome browser system.</li> -</ul> +Each assembly gets its own subdirectory named by its NCBI accession +identifier (<b>GCA_</b> or <b>GCF_</b>). Data files and the +<b>trackDb.txt</b> must use <b>the same file names</b> in every assembly +directory. This allows a single <b>trackDb.txt</b> to work across all +assemblies. </p> -<h2>Your track hub file/directory structure</h2> <pre> +-- hub.txt +-- genomes.txt -+-- documentation.html +-- GCA_000260495.2/ | +-- trackDb.txt -| +-- veupathGenes.bb -| +-- veupathGenes.gtf.gz +| +-- myTrack.bb +| +-- myTrackDocs.html +-- GCF_014441545.1/ | +-- trackDb.txt -| +-- veupathGenes.gtf.gz -| +-- veupathGenes.bb +| +-- myTrack.bb +| +-- myTrackDocs.html +-- GCF_014108235.1/ | +-- trackDb.txt -| +-- veupathGenes.gtf.gz -| +-- veupathGenes.bb +| +-- myTrack.bb +| +-- myTrackDocs.html </pre> <h2>Requirements</h2> -<p> -Assembly names need to be the NCBI GenBank accession names to -identify the corresponding assembly. <b>GCF_...</b> or <b>GCA_...</b> -</p> -<p>All annotations must have appropriate documentation.</p> -<p>The track hub directory structure must be as described here.</p> -<h2>Example <b>hub.txt</b> file</h2> +<ul> +<li><b>Assembly naming:</b> Directory names and assembly identifiers in + <b>genomes.txt</b> must be NCBI GenBank or RefSeq accession identifiers + (e.g., <b>GCA_000260495.2</b> or <b>GCF_014441545.1</b>). A full list + of GenArk assemblies is available at the + <a href="https://hgdownload.gi.ucsc.edu/hubs/UCSC_GI.assemblyHubList.txt" + target="_blank">assembly hub list</a>.</li> +<li><b>Data formats:</b> Annotation data must be in + <a href="goldenPath/help/bigBed.html" target="_blank">bigBed</a>, + <a href="goldenPath/help/bigWig.html" target="_blank">bigWig</a>, + or another + <a href="goldenPath/help/hgTrackHubHelp.html#Supported" + target="_blank">supported track type</a>.</li> +<li><b>Uniform file names:</b> Use the same file names for data files and + <b>trackDb.txt</b> across all assembly directories (e.g., + <b>myTrack.bb</b> everywhere, not <b>myTrack.GCA_000260495.2.bb</b>).</li> +<li><b>Documentation:</b> Every track must include an HTML documentation + page (see <a href="#documentation">Track documentation</a> below).</li> +</ul> + +<h2>Example hub.txt</h2> <pre> -hub PAG_2026_GenArk_Contrib_Example -shortLabel PAG 2026 GenArk tracks -longLabel PAG 2026 example of contributed tracks to UCSC GenArk assemblies -email genome@soe.ucsc.edu +hub myProjectHub +shortLabel My Contributed Tracks +longLabel Contributed annotation tracks for GenArk assemblies +email user@example.edu genomesFile genomes.txt descriptionUrl documentation.html - -# comments: -# load this hub with a reference to this hub.txt file: -# https://genome-test.gi.ucsc.edu/~hiram/BRC/contrib/hub.txt - -# for example, to show this track hub in the genome browser:: - -# https://genome.ucsc.edu/cgi-bin/hgTracks?genome=GCA_000260495.2& -# hubUrl=https://genome-test.gi.ucsc.edu/~hiram/BRC/contrib/hub.txt </pre> + <p> -The <b>genomes.txt</b> file specifies the target assemblies. -The <b>descriptionUrl</b> link refers to <b>documentation.html</b> for -this track hub. Since the data is uniform for all the tracks, -a single <b>documentation.html</b> can be sufficient for all documentation. +The <b>descriptionUrl</b> page provides an overall description of the hub +or research project. For details on hub.txt settings, see the +<a href="goldenPath/help/hgTrackHubHelp.html#Setup" +target="_blank">Track Hub User Guide</a>. </p> -<h2>Example <b>genomes.txt</b> file</h2> +<h2>Example genomes.txt</h2> + <pre> genome GCA_000260495.2 trackDb GCA_000260495.2/trackDb.txt genome GCF_014441545.1 trackDb GCF_014441545.1/trackDb.txt genome GCF_014108235.1 trackDb GCF_014108235.1/trackDb.txt </pre> + <p> -List each assembly for which you have calculated annotations. -The <b>trackDb.txt</b> file defines the tracks. To emphasize again, -the assembly names must be the GenBank accession identifier or -the UCSC database name, e.g.: <b>'GCF_016077325.2', or 'hg38', 'mm39'</b>. -You can find a full list of all GenArk repository assemblies at: -<a href='https://hgdownload.gi.ucsc.edu/hubs/UCSC_GI.assemblyHubList.txt' -target=_blank>assembly hub list</a> +One block per assembly, separated by a blank line. The <b>genome</b> value +is the NCBI accession identifier, and <b>trackDb</b> points to the +<a href="goldenPath/help/trackDb/trackDbHub.html" +target="_blank">trackDb.txt</a> file in that assembly's subdirectory. </p> -<h2>Example <b>trackDb.txt</b> file</h2> +<h2>Example trackDb.txt</h2> + <pre> -track VEuPathDBGeneModels -shortLabel PAG 2026 contrib -longLabel PAG 2026 - demonstrating contributed tracks to UCSC GenArk assemblies -group genes -type bigBed 12 . -visibility pack -labelFields name +track myTrack +shortLabel My Track +longLabel My contributed annotation track for GenArk assemblies +type bigBed 9 + +visibility dense +bigDataUrl myTrack.bb searchIndex name -bigDataUrl veupathGenes.bb -colorByStrand 0,0,122 157,60,32 -dataVersion VEuPathDB release 68 -html ../documentation - -# can be multiple track definitions here for other annotations +html myTrackDocs </pre> + <p> -Since all the annotations are the same type, a single <b>trackDb.txt</b> -file is sufficient for all assemblies. The <b>html</b> link refers -to <b>../documenation.html</b> as used in the <b>hub.txt</b> file. -For documentation structure, you can follow the typical UCSC track -format with sections for: <b>Description</b>, <b>Methods</b>, <b>Credits</b>, -<b>References</b>. For example: -<a href='/cgi-bin/hgTrackUi?db=hg38&c=chrX&g=recombRate2' -target=_blank>typical UCSC track</a> documentation. +Because data files have the same name in every assembly directory, +this identical <b>trackDb.txt</b> works for all assemblies. The +<b>bigDataUrl</b> is a relative path to the data file in the same directory. +The <b>html</b> setting points to the track documentation page (without the +<b>.html</b> extension). For the full list of trackDb settings, see the +<a href="goldenPath/help/trackDb/trackDbHub.html" +target="_blank">trackDb documentation</a>. </p> +<h2><a name="documentation"></a>Track documentation</h2> + +<p> +Every track must have an HTML documentation page. Place it in each assembly +directory with the filename referenced by the <b>html</b> setting in +trackDb.txt (e.g., <b>myTrackDocs.html</b>). If you omit the <b>html</b> +setting, the browser looks for <b>[trackName].html</b> in the same +directory as the trackDb.txt file. +</p> + +<p>Structure your documentation page with these sections:</p> + +<ul> +<li><b>Description</b> — What the annotation represents.</li> +<li><b>Methods</b> — How the annotation was generated.</li> +<li><b>Credits</b> — Who produced the data.</li> +<li><b>References</b> — Relevant publications or resources.</li> +</ul> + +<p> +A <a href="https://genome.ucsc.edu/goldenPath/help/examples/hubExamples/templatePage.html" +target="_blank">template documentation page</a> is available as a starting +point. For an example of a completed track description, see the +<a href="/cgi-bin/hgTrackUi?db=hg38&c=chrX&g=recombRate2" +target="_blank">recombination rate track</a> page. +</p> + +<h2>Live example</h2> + +<p> +An example contributed track hub with EVA SNP Release 8 data on five +GenArk assemblies is available for reference: +</p> +<ul> +<li><b>Hub URL:</b> + <a href="goldenPath/trackHubs/contributedTracksExample/hub.txt" + target="_blank">hub.txt</a></li> +<li><b>View in browser:</b> + <a href="cgi-bin/hgTracks?genome=GCF_000971095.1&position=default&hubUrl=https://genome.ucsc.edu/goldenPath/trackHubs/contributedTracksExample/hub.txt" + target="_blank">GCF_000971095.1 (swan goose) with EVA SNP track</a></li> +</ul> + +<h2>Next steps</h2> + +<p> +Once your hub is ready, contact the +<a href="contacts.html">UCSC Genome Browser team</a> with your +<b>hub.txt</b> URL. You can test it first by loading it via +<b>My Data > Track Hubs</b> in the browser. The team will review +your submission and work with you to integrate the tracks. +</p> + +<p> +For general information about track hubs, see the +<a href="goldenPath/help/hgTrackHubHelp.html" +target="_blank">Track Hub User Guide</a>. For best practices, see the +<a href="https://genome.ucsc.edu/goldenPath/help/publicHubGuidelines.html" +target="_blank">Public Hub Guidelines</a>. +</p> <!--#include virtual="$ROOT/inc/gbPageEnd.html" -->