c6582ecb0ccf13141e44395c11adec3d32d2ac9a jnavarr5 Tue May 14 17:24:46 2024 -0700 Adding links to the hosting documentation on the custom track help page, refs #23633 diff --git src/hg/htdocs/goldenPath/help/customTrackText.html src/hg/htdocs/goldenPath/help/customTrackText.html index d0fcb25..a775ead 100755 --- src/hg/htdocs/goldenPath/help/customTrackText.html +++ src/hg/htdocs/goldenPath/help/customTrackText.html @@ -41,32 +41,34 @@ <li><a href="#BROWSER">Browser lines</a></li> <li><a href="#TRACK">Track lines</a></li> <li>Data lines</li> </ul> <a name="CREATE"></a> <h3>Building and sharing a custom track</h3> <p> To construct an annotation file and display it in the Genome Browser, follow these steps:</p> <a name="format"></a> <p> <strong>Step 1. Format the data set</strong><br> Format your data as a tab-separated file using one of the <a href="/FAQ/FAQformat.html" target="_blank">formats supported</a> by the Genome -Browser. Annotation data can be in a format designed specifically for the Human Genome Project or -UCSC Genome Browser, including: +Browser. Chromosome references must be of the form <em>chrN</em> (the parsing of chromosome names +<em><strong>is</strong></em> case-sensitive). You may include more than one data set in your +annotation file; these need not be in the same format. Annotation data can be in a format designed +specifically for the Human Genome Project or UCSC Genome Browser, including: <div class="container"> <div class="row"> <div class="col-xs-12 col-sm-6 col-md-2"> <ul> <li><a href="bedgraph.html">bedGraph</a> <li><a href="/FAQ/FAQformat.html#format4">GTF</a> and <a href="/FAQ/FAQformat.html#format3">GFF</a> <li><a href="/FAQ/FAQformat.html#format2">PSL</a> <li><a href="/FAQ/FAQformat.html#format1">BED</a> <li><a href="wiggle.html">WIG</a> </ul> </div> <div class="col-xs-12 col-sm-6 col-md-2"> <ul> <li><a href="bigBed.html">bigBed</a></li> @@ -98,33 +100,37 @@ <ul> <li><a href="../../FAQ/FAQformat.html#format1.7">BED detail</a> <li><a href="../../FAQ/FAQformat.html#format10">Personal Genome SNP</a> <li><a href="../../FAQ/FAQformat.html#format13">broadPeak</a> </ul> </div> <div class="col-xs-12 col-sm-6 col-md-2"> <ul> <li><a href="../../FAQ/FAQformat.html#format12">narrowPeak</a> <li><a href="../../FAQ/FAQformat.html#format6.5">microarray</a> (BED15) </ul> </div> </div> </div> <p> -Chromosome references must be of the form <em>chrN</em> (the parsing of chromosome names -<em><strong>is</strong></em> case-sensitive). You may include more than one data set in your -annotation file; these need not be in the same format.</p> +Some annotations need to be hosted remotely in a web-accessible location that support byte-range +requests to be visualized on the UCSC Genome Browser, such as: bigBed, bigWig, BAM, VCF, etc. +<em> +For examples of how to host your custom track data remotely, please refer to the track hub user +guide, "<a href="/goldenPath/help/hgTrackHubHelp.html#Hosting" target="_blank">Where to host +your data?</a>".</em> +</p> <p> <strong>Step 2. Define the Genome Browser display characteristics</strong><br> Add one or more optional <a href="#BROWSER">browser lines</a> to the beginning of the data file to configure the overall display of the Genome Browser when it initially shows the annotation data. Browser lines allow you to configure such things as the initial genome position, the width of the display, and hide/show other annotation tracks in the display.</p> <p> <em> NOTE: If the browser position is not explicitly set in the annotation file, the display will default to the user's most recent position, which may not be an appropriate position for viewing the annotation track.</em></p> <p> <strong>Step 3. Define the annotation track display characteristics</strong><br> Following the browser lines <em>--and immediately preceding the formatted data--</em> add a @@ -191,31 +197,36 @@ <a href="../../cgi-bin/hgTracks">Genome Browser</a>. (Note: if one or more tracks have already been uploaded during the current Browser session, additional tracks may be loaded on the Manage Custom Tracks page. In this case, the button on the Browser page will be labeled "manage custom tracks" and will automatically direct you to the track management page. See <a href="#MANAGE_CT">Displaying and Managing Custom Tracks</a> for more information.)</p> <p> <strong>Step 2. Load the custom track data</strong><br> The Add Custom Tracks page contains separate sections for uploading custom track data and optional custom track descriptive documentation. Load the annotation data into the upper section by one of the following methods:</p> <ul> <li> Enter one or more URLs for custom tracks (one per line) in the data text box. The Genome Browser supports both the HTTP and FTP (passive-only) protocols. Data provided by a URL may need to be proceeded by a separate line defining <a href="#TRACK">type=<<em>track_type</em>></a> required - for some tracks, for example such as "track type=broadPeak".</li> + for some tracks, for example such as "track type=broadPeak". + <br><br> + <em>For examples of how to host your custom track data remotely, please refer to the track hub + user guide, "<a href="/goldenPath/help/hgTrackHubHelp.html#Hosting" target="_blank">Where to host + your data?</a>".</em> + </li> <li> Click the "Choose File" button directly above the data text box, then choose a custom track file from your local computer. # or type the pathname of the file into the "upload" text box adjacent to the "Browse" button. The custom track data may be compressed by any of the following programs: gzip (<em>.gz</em>), compress (<em>.Z</em>), or bzip2 (<em>.bz2</em>). Files containing compressed data must include the appropriate suffix in their names.</li> <li> Paste or type the custom track data directly into the data box. Because the text in this box will not be saved to a file, this method is not recommended unless you have a copy of the data elsewhere.</li> </ul> <p> Multiple custom tracks may be uploaded at one time on the Add Custom Tracks page through one of the @@ -697,31 +708,35 @@ <strong>htmlUrl=<<em>external_url</em>></strong> <br> Defines a URL for an HTML description page to be displayed with this track. There is no default for this attribute. A template for a standard format HTML track description is <a class="change" target="_blank" href="http://genome.ucsc.edu/goldenPath/help/ct_description.txt">here</a>.</li> <li> <strong>bigDataUrl=<<em>external_url</em>></strong> <br> Defines a URL to the data file for <a href="../help/bam.html" target="_blank">BAM</a>, <a href="../help/cram.html" target="_blank">CRAM</a>, <a href="../help/bigBed.html" target="_blank">bigBed</a>, <a href="../help/bigWig.html" target="_blank">bigWig</a> or <a href="../help/vcf.html" target="_blank">VCF</a> tracks. This is a required attribute for those - track types. There is no default for this attribute.</li> + track types. There is no default for this attribute. + <em>For examples of how to host your custom track data remotely, please refer to the track hub + user guide, "<a href="/goldenPath/help/hgTrackHubHelp.html#Hosting" target="_blank">Where to host + your data?</a>".</em> + </li> <li> <strong>bigDataIndex=<<em>external_url</em>></strong> <br> The URL of the BAI/TBI index file for <a href="../help/bam.html" target="_blank">BAM</a> and <a href="../help/cram.html" target="_blank">CRAM</a> files. By default, these index files are assumed to be at the same URL as the data file, but with the extension .bai. For example, if the data file is https://genome.gov/genome.bam, the index file by default must be at https://genome.gov/genome.bam.bai. If that is not the case, the bigDataIndex option must be used to point to the index file. </li> <li> <strong>doWiggle=<<em>on</em>></strong> <br> The doWiggle setting enables BAM custom tracks to be displayed as bar graphs where the height is proportional to the number of reads mapped @@ -1346,80 +1361,89 @@ reflects the score value of that line. <pre><code>browser position chr22:1000-10000 browser hide all track name="BED track" description="BED format custom track example" visibility=2 color=0,128,0 useScore=1 #chrom chromStart chromEnd name score strand thickStart thickEnd itemRgb blockCount blockSizes blockStarts chr22 1000 5000 itemA 960 + 1100 4700 0 2 1567,1488, 0,2512 chr22 2000 7000 itemB 200 - 2200 6950 0 4 433,100,550,1500 0,500,2000,3500 </code></pre> <p> Click <a class="insideLink" href="../../cgi-bin/hgTracks?org=human&position=chr22&hgt.customText=http://genome.ucsc.edu/goldenPath/help/examples/ct_example3.txt" target="_blank">here</a> to view this track in the Genome Browser.</p> <a name="EXAMPLE3b"></a> <h3>Simple annotation in bigBed format</h3> <p> -This example shows a simple annotation file containing one data set in the bigBed format. This track -displays random sized blocks across chr21 in the human genome. The big data formats, such as the -bigBed format, can be uploaded using a bigDataUrl that is specified in the track line. For more -information on these track line parameters, refer to the <a href="#TRACK">Track Lines</a> -section. When using bigDataUrls, data is cached and updated every 300 seconds. If you are updating -your big data tracks with different displays and are not seeing your track changes in the browser, -you may want to add the <a href="hgTrackHubHelp.html#Debug">udcTimeout</a> parameter to prevent -caching of your track data and force a reload.</p> +This example shows a simple annotation file containing a single data set in the bigBed format. +The track displays arbitrarily sized blocks across chr21 in the human genome. The big* data +formats, such as the bigBed format, can be uploaded using a bigDataUrl that is specified in the +track line. <em>For more information on these track line parameters, refer to the +<a href="#TRACK">Track Lines</a> section above.</em> +Some annotations need to be hosted remotely in a web-accessible location that support byte-range +requests to be visualized on the UCSC Genome Browser, such as: bigBed, bigWig, BAM, VCF, etc. +<em> +For examples of how to host your custom track data remotely, please refer to the track hub user +guide, "<a href="/goldenPath/help/hgTrackHubHelp.html#Hosting" target="_blank">Where to host +your data?</a>".</em> +</p> <p> You may paste these two lines directly into the "Add Custom Tracks" page to view this example in the browser:</p> <pre><code>browser position chr21:33,031,597-33,041,570 track type=bigBed name="bigBed Example One" description="A bigBed file" bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb</code></pre> <p> Alternatively, you may also upload just the URL of the bigBed file:</p> <pre><code>http://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb </code></pre> <p> -This will infer the track type as "bigBed" based on the file extension and set the track -name to "bigBedExample".</p> +The Genome Browser will attempt to infer the track type as "bigBed" based on the file +extension and set the track name to "bigBedExample".</p> +<p> +When using bigDataUrls, data is cached and updated every 300 seconds. If you are updating +your big data tracks with different displays and are not seeing your track changes in the browser, +you may want to add the <a href="hgTrackHubHelp.html#Debug">udcTimeout</a> parameter to prevent +caching of your track data and force a reload.</p> + <a name="EXAMPLE4"></a> <h3>Create external links using the 'name' field from the BED file</h3> <p> Here is an example of a file in which the <em>url</em> attribute has been set to point to the file <a href="cloneshtml.txt" target="_blank">http://genome.ucsc.edu/goldenPath/help/clones.html</a>. The URL parameter, '#$$', appended to the end of the file name in the example points to the HTML NAME tag within the file that matches the name of the feature (cloneA, cloneB, etc.).</p> <pre><code>browser position chr22:10000000-10020000 browser hide all track name=clones description="Clones" visibility=2 color=0,128,0 useScore=1 url="http://genome.ucsc.edu/goldenPath/help/clones.html#$$" #chrom chromStart chromEnd name score chr22 10000000 10004000 cloneA 960 chr22 10002000 10006000 cloneB 200 chr22 10005000 10009000 cloneC 700 chr22 10006000 10010000 cloneD 600 chr22 10011000 10015000 cloneE 300 chr22 10012000 10017000 cloneF 100 </code></pre> <p> Click <a class="insideLink" href="../../cgi-bin/hgTracks?org=human&position=chr22&hgt.customText=http://genome.ucsc.edu/goldenPath/help/examples/ct_example4.txt" target="_blank">here</a> to display this track in the Genome Browser.</p> <a name="EXAMPLE5"></a> <h3>Loading a custom track via the URL</h3> <p> The following URL will open up the Genome Browser window to display chr22 of the latest human genome assembly and will show the annotation track pointed to by the URL -http://genome.ucsc.edu/goldenPath/help/test.bed: -<pre><code -<a class="insideLink" href="../../cgi-bin/hgTracks?org=human&position=chr22&hgt.customText=http://genome.ucsc.edu/goldenPath/help/test.bed" +(http://genome.ucsc.edu/goldenPath/help/test.bed): +<pre><code><a href="../../cgi-bin/hgTracks?org=human&position=chr22&hgt.customText=http://genome.ucsc.edu/goldenPath/help/test.bed" target="_blank">http://genome.ucsc.edu/cgi-bin/hgTracks?org=human&position=chr22&hgt.customText=http://genome.ucsc.edu/goldenPath/help/test.bed</a></code></pre> <p> If a login and password is required to access data loaded through a URL (e.g., via https: protocol), this information can be included in the URL using the format protocol://user:password@server.com/somepath. Only Basic Authentication is supported for HTTP. Note that passwords included in URLs are not protected. If a password contains a non-alphanumeric character, such as $, the character must be replaced by the hexadecimal representation for that character. For example, in the password mypwd$wk, the $ character should be replaced by %24, resulting in the modified password mypwd%24wk.</p> <a name="EXAMPLE6"></a> <h3>Construct a sharable URL using the bigDataUrl setting</h3> <p> If you would like to share a URL that your colleague can click on directly, rather than loading it in the Custom Track tool (as in Example #5), then the URL will need a few extra parameters. Let's