651b51fcb3020fe99b030a09dc0c4b941faedae9 lrnassar Tue Mar 31 09:47:53 2026 -0700 Add missing documentation.html to directory structure example on contributed tracks page. refs #36957 diff --git src/hg/htdocs/contribTracks.html src/hg/htdocs/contribTracks.html index f26d403ed76..247d257b08a 100755 --- src/hg/htdocs/contribTracks.html +++ src/hg/htdocs/contribTracks.html @@ -1,200 +1,201 @@ <!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>Contributing Tracks to the UCSC Genome Browser</h1> <p> 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> <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> 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> <pre> +-- hub.txt +-- genomes.txt ++-- documentation.html +-- GCA_000260495.2/ | +-- trackDb.txt | +-- myTrack.bb | +-- myTrackDocs.html +-- GCF_014441545.1/ | +-- trackDb.txt | +-- myTrack.bb | +-- myTrackDocs.html +-- GCF_014108235.1/ | +-- trackDb.txt | +-- myTrack.bb | +-- myTrackDocs.html </pre> <h2>Requirements</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 myProjectHub shortLabel My Contributed Tracks longLabel Contributed annotation tracks for GenArk assemblies email user@example.edu genomesFile genomes.txt descriptionUrl documentation.html </pre> <p> 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 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> 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 trackDb.txt</h2> <pre> track myTrack shortLabel My Track longLabel My contributed annotation track for GenArk assemblies type bigBed 9 + visibility dense bigDataUrl myTrack.bb searchIndex name html myTrackDocs </pre> <p> 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" -->