eb4adbf30d849f0a7301359e0153c0932b2660e6 brianlee Tue May 17 12:10:20 2022 -0700 Fixing dynaseq-> dynseq typo in example custom track text diff --git src/hg/htdocs/goldenPath/help/bigWig.html src/hg/htdocs/goldenPath/help/bigWig.html index 896658e..8e69ca3 100755 --- src/hg/htdocs/goldenPath/help/bigWig.html +++ src/hg/htdocs/goldenPath/help/bigWig.html @@ -1,283 +1,283 @@ <!DOCTYPE html> <!--#set var="TITLE" value="Genome Browser bigWig Format" --> <!--#set var="ROOT" value="../.." --> <!-- Relative paths to support mirror sites with non-standard GB docs install --> <!--#include virtual="$ROOT/inc/gbPageStart.html" --> <h1>bigWig Track Format</h1> <p> The bigWig format is useful for dense, continuous data that will be displayed in the Genome Browser as a graph. BigWig files are created from <a href="wiggle.html">wiggle</a> (wig) type files using the program <code>wigToBigWig</code>. Alternatively, bigWig files can be created from <a href="/goldenPath/help/bedgraph.html">bedGraph</a> files, using the program <code>bedGraphToBigWig</code>. </p> <p> The bigWig files are in an indexed binary format. The main advantage of this format is that only those portions of the file needed to display a particular region are transferred to the Genome Browser server. Because of this, bigWig files have considerably faster display performance than regular wiggle files when working with large data sets. The bigWig file remains on your local web-accessible server (http, https or ftp), not on the UCSC server, and only the portion needed for the currently displayed chromosomal position is locally cached as a "sparse file". If you do not have access to a web-accessible server and need hosting space for your bigWig files, please see the <a href="hgTrackHubHelp.html#Hosting">Hosting</a> section of the Track Hub Help documentation.</p> <p> Wiggle data must be continuous and consist of equally sized elements. If your data is sparse or contains elements of varying sizes, use the <a href="bedgraph.html">bedGraph</a> format instead of the wiggle format. If you have a very large bedGraph data set, you can convert it to the bigWig format using the <code>bedGraphToBigWig</code> program. For details, see <a href="#Ex3">Example #3</a> below. Refer to <a href="http://genomewiki.ucsc.edu/index.php/Selecting_a_graphing_track_data_format" target="_blank">this wiki page</a> for help in selecting the graphing track data format most appropriate for the type of data you have.</p> <p> Note that the <code>wigToBigWig</code> utility uses a substantial amount of memory: approximately 50% more memory than that of the uncompressed wiggle input file. While running the <code>wigToBigWig</code> utility, we recommend that you monitor the system's memory usage with the <code>top</code> command. The <code>bedGraphToBigWig</code> utility uses about 25% more RAM than the uncompressed bedGraph input file.</p> <h2>Creating a bigWig track</h2> <p> To create a bigWig track from a wiggle file, follow these steps:<p> <strong>Step 1.</strong> Create a wig format file following the directions <a href="wiggle.html">here</a>. When converting a wig file to a bigWig file, you are limited to one track of data in your input file; therefore, you must create a separate wig file for each data track. <p> <strong>Step 2.</strong> Remove any existing "track" or "browser" lines from your wig file so that it contains only data.</p> <p> <strong>Step 3.</strong> Download the <code>wigToBigWig</code> program from the <a href="http://hgdownload.soe.ucsc.edu/admin/exe/">binary utilities directory</a>.</p> <p> <strong>Step 4.</strong> Use the <code>fetchChromSizes</code> script from the <a href="http://hgdownload.soe.ucsc.edu/admin/exe/">same directory</a> to create the <em>chrom.sizes</em> file for the UCSC database with which you are working (e.g., hg19). If the assembly <code>genNom</code> is hosted by UCSC, chrom.sizes can be a URL like: <code>http://hgdownload.soe.ucsc.edu/goldenPath/genNom/bigZips/genNom.chrom.sizes</code></p> <p> <strong>Step 5.</strong> Use the <code>wigToBigWig</code> utility to create the bigWig file from your wig file:</p> <pre><code><strong>wigToBigWig</strong> input.wig chrom.sizes myBigWig.bw</code></pre> <p> Note that the wigToBigWig program also accepts gzipped wig input files.</p> <p> <strong>Step 6.</strong> Move the newly created bigWig file (<em>myBigWig.bw</em>) to a web-accessible http, https, or ftp location.</p> <p> <strong>Step 7.</strong> If the file name ends with a <em>.bigWig</em> or <em>.bw</em> suffix, you can paste the URL directly into the <a href="../../cgi-bin/hgCustom">custom track management page</a>, click "submit" and view the file as a track in the Genome Browser. By default, the file name will be used to name the track. To configure the track label or other visualization options, you must create a <a href="hgTracksHelp.html#TRACK">track line</a>, as shown in <em>Step 8</em>.</p> <p> <strong>Step 8.</strong> Construct a <a href="hgTracksHelp.html#CustomTracks">custom track</a> using a single track line. The most basic version of the track line will look something like this:</p> <pre><code>track type=bigWig name="My Big Wig" description="A Graph of Data from My Lab" bigDataUrl=http://myorg.edu/mylab/myBigWig.bw</code></pre> <p> Paste the custom track line into the text box on the <a href="../../cgi-bin/hgCustom">custom track management page</a>.</p> <p> <a name="optional"></a> bigWig custom track lines can have several optional parameters, including: <pre> <strong>autoScale </strong><em><on|off> </em> # default is on <strong>alwaysZero </strong><em><on|off> </em> # default is off <strong>gridDefault </strong><em><on|off> </em> # default is off <strong>maxHeightPixels </strong><em><max:default:min> </em> # default is 128:128:11 <strong>graphType </strong><em><bar|points> </em> # default is bar <strong>viewLimits </strong><em><lower:upper> </em> # default is range found in data <strong>viewLimitsMax </strong><em><lower:upper> </em> # suggested bounds of viewLimits, but not enforced <strong>yLineMark </strong><em><real-value> </em> # default is 0.0 <strong>yLineOnOff </strong><em><on|off> </em> # default is off <strong>windowingFunction </strong><em><mean+whiskers|maximum|mean|minimum></em> # default is maximum, mean+whiskers is recommended <strong>smoothingWindow </strong><em><off|[2-16]> </em> # default is off <strong>transformFunc </strong><em><NONE|LOG> </em> # default is NONE</pre> <p> For further information on custom bigWig track settings, see the <a href="trackDb/trackDbDoc.html#wig_-_Signal_Graphing_Track_Settings">Track Database Definition Document</a>. For more information on how bigWig settings are used in native Genome Browser tracks, see the <a href="hgWiggleTrackHelp.html">Configuring graph-based tracks</a> page.</p> <h2>Examples</h2> <h3>Example #1</h3> <p> In this example, you create a bigWig custom track using an existing bigWig file on the UCSC http server. The file contains data that spans chromosome 21 on the hg19 assembly. <p> To create a custom track using this bigWig file: <ol> <li> Paste the URL <code>http://genome.ucsc.edu/goldenPath/help/examples/bigWigExample.bw</code> onto the <a href="../../cgi-bin/hgCustom">custom track management page</a> for the human assembly hg19 (Feb. 2009).</li> <li> Click the "submit" button. </li> <li> On the next page that displays, click the "chr21" link in the custom track listing to view the bigWig track at position chr21:33,031,597-33,041,570 in the Genome Browser. </li> </ol> <p> Alternatively, you can customize the track display by including track and browser lines that define certain parameters: </p> <ol> <li> Construct a track line that references the <em>bigWigExample.bw</em> file: <pre><code>track type=bigWig name="Example One" description="A bigWig file" bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/bigWigExample.bw</code></pre></li> <li> Include the following browser line to ensure that the custom track opens at the correct position: <pre><code>browser position chr21:33,031,597-33,041,570</code></pre></li> <li> Paste the browser and track lines onto the <a href="../../cgi-bin/hgCustom">custom track management page</a> for the human assembly hg19 (Feb. 2009), click the "submit" button, then click the "chr21" link in the custom track listing to view the bigWig track in the Genome Browser.</li> </ol> <h3>Example #2</h3> <p> In this example, you will create your own bigWig file from an existing wiggle file.</p> <ol> <li> Save <a href="examples/wigVarStepExample.gz">this wiggle file</a> to your computer (<em>Steps 1</em> and <em>2</em> in <em>Creating a bigWig format track</em>, above).</li> <li> Save the file <a href="hg19.chrom.sizes"><em>hg19.chrom.sizes</em></a> to your computer. This file contains the chrom.sizes for the human (hg19) assembly (<em>Step 4</em>, above).</li> <li> Download the <code>wigToBigWig</code> utility (<em>step 3</em>, above).</li> <li> Run the utility to create the bigWig output file (<em>step 5</em>, above): <pre><code><strong>wigToBigWig</strong> wigVarStepExample.gz hg19.chrom.sizes myBigWig.bw</code></li> <li> Place the newly created bigWig file (<em>myBigWig.bw</em>) on a web-accessible server (<em>step 6</em>, above).</li> <li> Paste the URL of the bigWig file into the custom track entry form, or construct a track line that points to your bigWig file (<em>step 7</em>, above).</li> <li> Create the custom track on the human assembly hg19 (Feb. 2009), and view it in the Genome Browser (<em>step 8</em>, above). Note that the original wiggle file spans only chromosome 21.</li> </ol> <a name=Ex3></a> <h3>Example #3</h3> <p> To create a bigWig track from a bedGraph file, follow these steps:</p> <ol> <li> Create a bedGraph format file following the directions <a href="bedgraph.html">here</a>. When converting a bedGraph file to a bigWig file, you are limited to one track of data in your input file; therefore, you must create a separate bedGraph file for each data track.</li> <li> Remove any existing track or browser lines from your bedGraph file so that it contains only data.</li> <li> Download the <code>bedGraphToBigWig</code> program from the <a href="http://hgdownload.soe.ucsc.edu/admin/exe/">binary utilities directory</a>.</li> <li> Use the <code>fetchChromSizes</code> script from the <a href="http://hgdownload.soe.ucsc.edu/admin/exe/">same directory</a> to create the <em>chrom.sizes</em> file for the UCSC database with which you are working (e.g., hg19). If the assembly <code>genNom</code> is hosted by UCSC, chrom.sizes can be a URL like <code>http://hgdownload.soe.ucsc.edu/goldenPath/genNom/bigZips/genNom.chrom.sizes</code></li> <li> Use the <code>bedGraphToBigWig</code> utility to create a bigWig file from your bedGraph file: <pre><code><strong>bedGraphToBigWig</strong> in.bedGraph chrom.sizes myBigWig.bw</code></pre> (Note that the bedGraphToBigWig program <strong>DOES NOT</strong> accept gzipped bedGraph input files.)</li> <li> Move the newly created bigWig file (<code>myBigWig.bw</code>) to a web-accessible http, https, or ftp location.</li> <li> Paste the URL into the custom track entry form or construct a <a href="hgTracksHelp.html#CustomTracks">custom track</a> using a single <a href="hgTracksHelp.html#TRACK">track line</a>.</li> <li> Paste the custom track line into the text box on the <a href="../../cgi-bin/hgCustom">custom track management page</a>.</li> </ol> <a name=dynseq></a> <h3 id=Ex4>Example #4</h3> <p> In this example, we will display a bigWig with a dynamic sequence logo using <code>logo=on</code>.</p> <p> <ol> <li> Construct a track line that references the <em>bigWigExample.bw</em> file: - <pre><code>track type=bigWig logo=on name="Example dynaseq" description="A bigWig file with logo=on dynaseq" visibility=full autoScale=off bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/bigWigExample.bw</code></pre></li> + <pre><code>track type=bigWig logo=on name="Example dynseq" description="A bigWig file with logo=on dynseq" visibility=full autoScale=off bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/bigWigExample.bw</code></pre></li> <li> Include the following browser line to ensure that the custom track opens at the correct position: <pre><code>browser position chr21:33,037,000-33,037,050</code></pre></li> <li> Paste the browser and track lines onto the <a href="../../cgi-bin/hgCustom?db=hg19">custom track management page</a> for the human assembly hg19 (Feb. 2009), click the "submit" button, then click the "chr21" link in the custom track listing to view the bigWig track in the Genome Browser.</li> </ol> <p> You can also load the above by clicking this <a target="_blank" -href="../../cgi-bin/hgTracks?db=hg19&position=chr21:33,037,000-33,037,050&hgct_customText=track%20type%3DbigWig%20logo%3Don%20name%3D%22Example%20dynaseq%22%20description%3D%22A%20bigWig%20file%20with%20logo%3Don%20dynaseq%22%20visibility%3Dfull%20autoScale%3Doff%20bigDataUrl%3Dhttp%3A%2F%2Fgenome.ucsc.edu%2FgoldenPath%2Fhelp%2Fexamples%2FbigWigExample.bw">link</a>.</p> +href="../../cgi-bin/hgTracks?db=hg19&position=chr21:33,037,000-33,037,050&hgct_customText=track%20type%3DbigWig%20logo%3Don%20name%3D%22Example%20dynseq%22%20description%3D%22A%20bigWig%20file%20with%20logo%3Don%20dynseq%22%20visibility%3Dfull%20autoScale%3Doff%20bigDataUrl%3Dhttp%3A%2F%2Fgenome.ucsc.edu%2FgoldenPath%2Fhelp%2Fexamples%2FbigWigExample.bw">link</a>.</p> <div class="text-center"> <img src="../../images/dynseq.png" alt="Example4 of dynseq logo=on setting" width="700"> </div> <p> This <a href="https://kundajelab.github.io/dynseq-pages/" target="_blank">dynseq</a> display scales nucleotide characters by user-specified, base-resolution scores and was developed by the <a href="https://kundajelab.github.io/about/" target="_blank">Kundaje Lab</a>.</p> <h2>Sharing your data with others</h2> <p> If you would like to share your bigWig data track with a colleague, learn how to create a URL by looking at Example #6 on <a href="customTrack.html#EXAMPLE6">this page</a>.</p> <a name="Extract"></a> <h2>Extracting data from the bigWig format</h2> <p> Because bigWig files are indexed binary files, it can be difficult to extract data from them. UCSC has developed the following programs to assist in working with these files, available from the <a href="http://hgdownload.soe.ucsc.edu/admin/exe/">binary utilities directory</a>. <ul> <li> <code>bigWigToBedGraph</code> — converts a bigWig file to ASCII <a href="http://genome.ucsc.edu/FAQ/FAQformat.html#format1.8">bedGraph</a> format.</li> <li> <code>bigWigToWig</code> — converts a bigWig file to <a href="http://genome.ucsc.edu/FAQ/FAQformat.html#format6">wig</a> format. Note: if a bigWig file was created from a bedGraph, bigWigToWig will revert the file back to bedGraph.</li> <li> <code>bigWigSummary</code> — extracts summary information from a bigWig file.</li> <li> <code>bigWigAverageOverBed</code> — computes the average score of a bigWig over each bed, which may have introns.</li> <li> <code>bigWigInfo</code> — prints out information about a bigWig file.</li> </ul> <p> These utilities accept either file path names or URLs to files as input. As with all UCSC Genome Browser programs, simply type the program name (with no parameters) on the command line to view the usage statement.</p> <p> In some cases, <code>bigWigSummary</code> and <code>bigWigAverageOverBed</code> will produce very similar results, but in other cases, the results may differ. This is due to data-handling differences between the two programs. Summary levels are used with <code>bigWigSummary</code>; therefore, some rounding errors and border conditions are encountered when extracting data over relatively small regions. In contrast, the <code>bigWigAverageOverBed</code> utility uses the actual data, which ensures the highest level of accuracy.</p> <!--#include virtual="$ROOT/inc/gbPageEnd.html" -->