b036e61e75f5a6626d9fd3b4febe41c69cf97b5d brianlee Mon Dec 14 17:03:46 2020 -0800 Adding some changes to Max's changes to bigBed.html refs #26677 diff --git src/hg/htdocs/goldenPath/help/bigBed.html src/hg/htdocs/goldenPath/help/bigBed.html index 451797f..59e5796 100755 --- src/hg/htdocs/goldenPath/help/bigBed.html +++ src/hg/htdocs/goldenPath/help/bigBed.html @@ -19,61 +19,66 @@ access to a web-accessible server and need hosting space for your bigBed files, please see the <a href="hgTrackHubHelp.html#Hosting">Hosting</a> section of the Track Hub Help documentation.</p> <p> Additional indices can be created for the items in a bigBed file to support item search in track hubs. See <a href="#Ex3">Example #3</a> below for an example of how to build an additional index.</p> <p> See <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 that is most appropriate for your type of data.</p> <p> Note that the <code>bedToBigBed</code> utility uses a substantial amount of memory: approximately 25% more RAM than the uncompressed BED input file.</p> <p> +<a name=quick></a> <h2>Quickstart example commands</h2> -It is not hard to create a bigBed file. The following UNIX commands create one on a Linux machine and are +It is not hard to create a bigBed file. The following UNIX commands create one on a Linux machine +(swap macOSX for linux for an Apple environment). The steps are explained in more detail in the following sections on this page: <pre><code>wget https://genome.ucsc.edu/goldenPath/help/examples/bedExample.txt wget https://genome.ucsc.edu/goldenPath/help/hg19.chrom.sizes wget http://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/bedToBigBed chmod a+x bedToBigBed -bedToBigBed bedExample.txt hg19.chrom.sizes myBigBed.bb +./bedToBigBed bedExample.txt hg19.chrom.sizes myBigBed.bb mv myBigBed.bb ~/public_html/ </code></pre> The last step assumes that your ~/public_html/ directory is accessible from the internet. This may not be the case on your server. You may have to copy the file to another server and web-accessible location at your University. Once you know the URL to the file myBigBed.bb, you can paste this URL into the <a href="../../cgi-bin/hgCustom">custom track</a> box on the UCSC Genome Browser to display the file. +<a name=overview></a> <h2>Overview of the steps to create a bigBed track</h2> <p> To create a bigBed track, follow these steps (for concrete Unix commands, see the examples below on this page):<p> <p> <strong>Step 1.</strong> Create a BED format file following the directions <a href="../../FAQ/FAQformat.html#format1">here</a>. When converting a BED file to a bigBed file, you are limited to one track of data in your input file; therefore, you must create a separate BED file for each data track. Your BED file must be sorted. <p> If your BED file was originally a custom track, remove any existing "track" or "browser" lines from your BED file so that it -contains only data.</p> +contains only data. Also the input BED must be sorted, performed with this command: +<code>sort -k1,1 -k2,2n unsorted.bed > input.bed</code> +</p> <p> <strong>Step 2.</strong> Download the <code>bedToBigBed</code> program from the <a href="http://hgdownload.soe.ucsc.edu/admin/exe/">binary utilities directory</a>. Example #2 below shows the exact Unix command. </p> <p> The <code>bedToBigBed</code> program can be run with several additional options. Some of these, such as the <code>-as</code> and <code>-type</code> options, are used in examples below. The <code>-type</code> option, describes the size of the bigBed file, <code>-type=bedN[+[P]]</code>, where <code>N</code> is an integer between 3 and 12 and the optional <code>+[P]</code> parameter specifies the number of extra fields, not required, but preferred. Describing the size of the bigBed file is needed for access to extra fields like name, itemRgb, etc. @@ -109,99 +114,104 @@ 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 name and descriptions, you must create a "<a href="hgTracksHelp.html#TRACK">track line</a>", as shown in <em>Step 8</em>.</p> <p> Alternatively, if you want to set the track labels and other options yourself, construct a <a href="hgTracksHelp.html#CustomTracks">custom track</a> using a single track line. Note that any of the track attributes listed <a href="customTrack.html#TRACK">here</a> are applicable to tracks of type bigBed. The most basic version of the track line will look something like this:</p> <pre><code><strong>track type=</strong>bigBed <strong>name=</strong>"My Big Bed" <strong>description=</strong>"A Graph of Data from My Lab" <strong>bigDataUrl=</strong>http://myorg.edu/mylab/myBigBed.bb</code></pre> <p> Paste this custom track line into the text box on the <a href="../../cgi-bin/hgCustom">custom track</a> management page.</p> <h2>Examples</h2> +<a name=Ex1></a> <h3>Example #1</h3> <p> In this example, you will load an existing bigBed file, <em>bigBedExample.bb</em>, on the UCSC http server. This file contains chromosome 21 data on the human hg19 assembly.</p> <p> To create a custom track using this bigBed file:</p> <ol> <li> Paste the URL <code>http://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb</code> into - the <a href="../../cgi-bin/hgCustom">custom track</a> management page for the human assembly + the <a href="../../cgi-bin/hgCustom?db=hg19">custom track</a> management page 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 bigBed track in the Genome Browser. </li> + On the next page that displays, click the "go" link. To view the data in the bigBed + track in the Genome Browser navigate to <code>chr21:33,031,597-33,041,570</code>.</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>bigBedExample.bb</em> file: <pre><code>track type=bigBed name="bigBed Example One" description="A bigBed file" bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb</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> + Paste the track line into the <a href="../../cgi-bin/hgCustom?db=hg19">custom track</a> + management page, click the "submit" button. On the next page that displays, click + the "go" link. To view the data in the bigBed track in the Genome Browser + navigate to <code>chr21:33,031,597-33,041,570</code>.</li> <li> - Paste the browser and track lines into the <a href="../../cgi-bin/hgCustom">custom track</a> - management page, click the "submit" button, then click the "chr21" link in the - custom track listing to view the bigBed track in the Genome Browser.</li> + With the addition of the following browser line with the track line you can ensure that the + custom track opens at the correct position when you paste in the information: + <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> + Paste the browser and track lines into the <a href="../../cgi-bin/hgCustom?db=hg19">custom track</a> + page, click the "submit" button and the "go" link to see the data.</li> </ol> <a name=Ex2></a> <h3>Example #2</h3> <p> In this example, you will create your own bigBed file from an existing bed file.</p> <ol> <li> Save the BED file <a href="examples/bedExample.txt"><em>bedExample.txt</em></a> to a server, ideally one that is accessible from the internet. (<em>Steps 1</em> and <em>2</em> in <em>Creating a bigBed track</em>, above).<br> <pre><code>wget https://genome.ucsc.edu/goldenPath/help/examples/bedExample.txt</code></pre> </li> <li> Save the file <a href="hg19.chrom.sizes"><em>hg19.chrom.sizes</em></a> to your computer. It contains the chrom.sizes data for the human (hg19) assembly (<em>Step 4</em>, above).<br> <pre><code>wget https://genome.ucsc.edu/goldenPath/help/hg19.chrom.sizes</code></pre> </li> -<li>If you use your own file, it has to be sortedi, first on the +<li>If you use your own file, it has to be sorted, first on the <code>chrom</code> field, and secondarily on the <code>chromStart</code> field. You can use the utility <code>bedSort</code> available <a href="http://hgdownload.soe.ucsc.edu/admin/exe/" target="_blank">here</a> or the following UNIX <code>sort</code> command to do this: </p> <pre><code>sort -k1,1 -k2,2n unsorted.bed > input.bed</code></pre> </li> <li> Download the <code>bedToBigBed</code> utility (<em>Step 3</em>, above). Replace "linux" below with "macOSX" if your server is a Mac. <pre><code>wget http://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/bedToBigBed chmod a+x bedToBigBed</code></pre> </li> <li> Run the utility to create the bigBed output file (<em>Step 5</em>, above): -<pre><code><strong>bedToBigBed</strong> bedExample.txt hg19.chrom.sizes myBigBed.bb</code></pre></li> +<pre><code><strong>./bedToBigBed</strong> bedExample.txt hg19.chrom.sizes myBigBed.bb</code></pre></li> <li> Place the bigBed file you just created (<em>myBigBed.bb</em>) on a web-accessible server (<em>Step 6</em>, above).<br> <pre><code>mv myBigBed.bb ~/public_html/</code></pre> At some Universities, this involves using the commands ftp, scp or rsync to copy the file to a different server, one that is accessible from the internet. We have <a href="hgTrackHubHelp.html#Hosting">documentation</a> how to find such a server. </li> <li> Paste the URL itself into the Custom Tracks entry form or construct a track line that points to your bigBed 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 BED file contains data on chromosome 21 only.</li> </ol>