b4354dab1ce9929f4cd6b81628b545a3b0bd9840 dschmelt Wed Feb 26 14:43:22 2020 -0800 Adding note about bigDataIndex keyword #25018 diff --git src/hg/htdocs/goldenPath/help/bam.html src/hg/htdocs/goldenPath/help/bam.html index 1d86685..c65f6bc 100755 --- src/hg/htdocs/goldenPath/help/bam.html +++ src/hg/htdocs/goldenPath/help/bam.html @@ -39,45 +39,53 @@ Convert SAM to BAM using the samtools program: <pre><code> samtools view -S -b -o my.bam my.sam</code></pre> If converting a SAM file that does not have a proper header, the <code>-t</code> or <code>-T</code> option is necessary. For more information about the command, run <code>samtools view</code> with no other arguments.</li> <li> Sort and create an index for the BAM: <pre><code> samtools sort my.bam my.sorted samtools index my.sorted.bam</code></pre> The sort command appends <code>.bam</code> to <code>my.sorted</code>, creating a BAM file of alignments ordered by leftmost position on the reference assembly. The index command generates a new file, <code>my.sorted.bam.bai</code>, with which genomic coordinates can quickly be translated into file offsets in <code>my.sorted.bam</code>.</li> <li> Move both the BAM file and index file (<code>my.sorted.bam</code> and - <code>my.sorted.bam.bai</code>) to an http, https, or ftp location.</li> + <code>my.sorted.bam.bai</code>) to an http, https, or ftp location. Note that the Genome Browser + looks for an index file with the same URL as the BAM file with the .bai suffix added. If your + hosting site does not use the filename as the URL link, you will have to specifically + call the location of this .bam.bai index file with the <code>bigDataIndex</code> keyword. + This keyword is relevant in Custom Tracks + and Track Hubs. You can read more about <em>bigDataIndex</em> in + <a href="trackDb/trackDbHub.html#bigDataIndex">the TrackDb Database Definition page</a>.</li> <li> - If the file URL ends with .bam, you can paste the URL directly into the - <a href="../../cgi-bin/hgCustom">custom track</a> management page, click submit and view in the - Genome Browser. The track name will then be the name of the file. If you want to configure the - track name and descriptions, you will need to create a <a href="hgTracksHelp.html#TRACK">track - line</a>, as shown below in step 7.</li> + If the file URL ends with .bam and the BAM index file URL ends with .bam.bai, you can paste the + URL directly into the <a href="../../cgi-bin/hgCustom">custom track</a> management page, + click submit and view in the Genome Browser. The track name will then be the name of the file. + If you want to configure the track name and descriptions or the URLs are not as described, you + will need to create a <a href="hgTracksHelp.html#TRACK">track line</a>, as shown below in + step 7.</li> <li> Construct a <a href="hgTracksHelp.html#CustomTracks">custom track</a> using a single <a href="hgTracksHelp.html#TRACK">track line</a>. The most basic version of the "track" line will look something like this: <pre><code> track type=bam name="My BAM" bigDataUrl=<em>http://myorg.edu/mylab/my.sorted.bam</em></code></pre> Again, in addition to <em>http://myorg.edu/mylab/my.sorted.bam</em>, the associated index file <em>http://myorg.edu/mylab/my.sorted.bam.bai</em> must also be available at the same - location.</li> + location. If not, you can specify the URL with the + <code>bigDataUrl=<em>http://myorg.edu/mylab/my.sorted.bam.bai</em></li> <li> Paste the custom track line into the text box in the <a href="../../cgi-bin/hgCustom" target="_blank">custom track management page</a>, click submit and view in the Genome Browser.</li> </ol> <h3>Parameters for BAM custom track definition lines</h3> <p> All options are placed in a single line separated by spaces. In the example below, the lines are broken only for readability. If you copy/paste this example, you must remove the line breaks. Click <a href="examples/bamExample.txt">here</a> for a text version that you can paste without editing.</p> <pre><code> <strong>track type=bam bigDataUrl=</strong><em>http://...</em> <strong>pairEndsByName=</strong><em>.</em> <strong>pairSearchRange=</strong><em>N</em> @@ -101,30 +109,31 @@ <pre><code> <strong>pairEndsByName </strong><em>any value </em> # presence indicates paired-end alignments <strong>pairSearchRange </strong><em>N </em> # max distance between paired alignments, default 20,000 bases <strong>bamColorMode </strong><em>strand|gray|tag|off </em> # coloring method, default is strand <strong>bamGrayMode </strong><em>aliQual|baseQual|unpaired </em> # grayscale metric, default is aliQual <strong>bamColorTag </strong><em>XX </em> # optional tag for RGB color, default is "YC" <strong>minAliQual </strong><em>N </em> # display only items with alignment quality at least N, default 0 <strong>showNames </strong><em>on|off </em> # if off, don't display query names, default is on </code></pre> Other optional settings are not specific to BAM, but relevant: <pre><code> <strong>name </strong><em>track label </em> # default is "User Track" <strong>description </strong><em>center label </em> # default is "User Supplied Track" <strong>visibility </strong><em>squish|pack|full|dense|hide</em> # default is hide (will also take numeric values 4|3|2|1|0) + <strong>bigDataUrl </strong><em>https://your.bam.bai.com </em> # default is the bigDataUrl with .bai added to the end <strong>priority </strong><em>N </em> # default is 100 <strong>db </strong><em>genome database </em> # e.g. hg18 for Human Mar. 2006 <strong>maxWindowToDraw </strong><em>N </em> # don't display track when viewing more than N bases <strong>chromosomes </strong><em>chr1,chr2,... </em> # track contains data only on listed reference assembly sequences <strong>doWiggle </strong><em>on|off </em> # if on, show data as density graph, default is off </code></pre> <p> The <a href="hgBamTrackHelp.html" target="_blank">BAM track configuration</a> help page describes the BAM track configuration page options corresponding to <code>pairEndsByName</code>, <code>minAliQual</code>, <code>bamColorMode</code>, <code>bamGrayMode</code> and <code>bamColorTag</code> in more detail.</p> <p> <code>pairSearchRange</code> applies only when <code>pairEndsByName</code> is given. It allows for a tradeoff of display speed vs. completeness of pairing the paired-end alignments. When paired ends