ac0316bc98d0b617a6fe83801277b8e1832902c4 max Mon Jan 11 06:51:15 2021 -0800 a few improvements for section #3 of bigBed.html, probably could use a lot more work to make the English clearer. no redmine yet, but coming today diff --git src/hg/htdocs/goldenPath/help/bigBed.html src/hg/htdocs/goldenPath/help/bigBed.html index 59e5796..310686a 100755 --- src/hg/htdocs/goldenPath/help/bigBed.html +++ src/hg/htdocs/goldenPath/help/bigBed.html @@ -115,31 +115,31 @@ 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> +<h3>Example #1: Load an existing bigBed file</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?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 "go" link. To view the data in the bigBed @@ -155,33 +155,33 @@ <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> 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> +<h3>Example #2: Create a bigBed file from a BED file</h3> <p> -In this example, you will create your own bigBed file from an existing bed file.</p> +In this example, you will convert a sample BED file to bigBed format.</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 sorted, first on the <code>chrom</code> field, and secondarily on the <code>chromStart</code> field. You can use the utility <code>bedSort</code> @@ -205,50 +205,60 @@ (<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> <a name=Ex3></a> -<h3>Example #3</h3> +<h3>Example #3: Create a bigBed file with extra (custom) fields</h3> <p> +BigBed files can +store extra fields in addition to the <a href="../../FAQ/FAQformat.html#format1">predefined BED +fields</a>. In this example, you will create your own bigBed file from a fully featured existing BED file that contains the standard BED fields up to and including the <em>color</em> field (field 9), plus two -additional non-standard fields (two alternate names for each item in the file). Since the resulting -bigBed file will have nine standard BED columns, which would include what is referenced as the -itemRgb field to inform the browser to display a R,G,B color value (e.g. 255,0,0), and two -additional non-standard user-defined columns, the bedToBigBed program is given <code>-type=bed9+2 -</code> and a file called <code>-as=bedExample2.as</code> to help correctly interpret all the -columns in the data. BigBed files can -store extra fields in addition to the <a href="../../FAQ/FAQformat.html#format1">predefined BED -fields</a>. If you add extra fields to your bigBed file, you must include an AutoSql format -(<em>.as</em>) file describing the fields. For more information on AutoSql, see +additional non-standard fields (two alternate names for each item in the file). +The resulting +bigBed file will have nine standard BED columns and two additional non-standard user-defined columns. +The standard column 9 is called the itemRgb field, it contains an R,G,B color value (e.g. 255,0,0). +</p> +If you add extra fields to your bigBed file, you must include an AutoSql format +(<em>.as</em>) file describing the fields. +In this file, all fields (standard and non-standard) are described with a short +internal name and also a human-readable description. +For more information on AutoSql, see <a href="http://www.linuxjournal.com/article/5949" target="_blank">Kent and Brumbaugh, 2002</a>, as well as examples of <em>.as</em> files in <a href="http://genome-source.soe.ucsc.edu/gitlist/kent.git/tree/master/src/hg/lib" target="_blank">this directory</a>. -This example also demonstrates how to create extra indices on the name field, and the first of the + +<p> +The bedToBigBed program is run with the arguments <code>-type=bed9+2</code> and also +<code>-as=bedExample2.as</code> to help correctly interpret all the columns in the data. +</p> + +This example also demonstrates how to create an extra search index on the name field, and the first of the extra fields to be used for track item search. The searchIndex setting requires the input BED data to be -case-senstive sorted (<code>sort -k1,1 -k2,2n</code>), where newer versions of the tool bedToBigBed +case-sensitive sorted (<code>sort -k1,1 -k2,2n</code>), where newer versions of the tool bedToBigBed (available <a href="http://hgdownload.soe.ucsc.edu/admin/exe/">here</a>) are enhanced to catch improper input.</p> <ol> <li> Save the BED file <a href="examples/bedExample2.bed"><em>bedExample2.bed</em></a> to your computer (<em>Steps 1</em> and <em>2</em> in <em>Creating a bigBed track</em>, above).</li> <li> Save the file <a href="hg18.chrom.sizes"><em>hg18.chrom.sizes</em></a> to your computer. This file contains the chrom.sizes for the human (hg18) assembly (<em>Step 4</em>, above).</li> <li> Save the AutoSql file <a href="examples/bedExample2.as"><em>bedExample2.as</em></a> to your computer. This file contains descriptions of the BED fields, and is required when the BED file contains a <em>color</em> field.</li> <li> Download the <code>bedToBigBed</code> utility (<em>Step 3</em>, above).</li> @@ -291,31 +301,32 @@ transform text fields into links with the "<a href="trackDb/trackDbHub.html#urls">urls</a>" trackDb setting.</li> <li> Extra fields that start with the character "_" are reserved for internal use (special display code); their contents are not shown on the details page.</li> </ol> <h2>Sharing Your Data with Others</h2> <p> If you would like to share your bigBed data track with a colleague, the best solution is to save your current view as a stable <a href="hgSessionHelp.html">Genome Browser Session Link</a>. This will save the position and all settings that you made, all track visibilities, filters, highlights, etc. </p> <p> -If you want to create URLs programmatically from software, look at Example #6 on <a href="customTrack.html#EXAMPLE6">this page</a>. +If you want to create URLs to your bigBed file programmatically from software, +look at Example #6 on <a href="customTrack.html#EXAMPLE6">this page</a>. </p> <h2>Extracting Data from the bigBed Format</h2> <p> Because the bigBed 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 bigBed formats, available from the <a href="http://hgdownload.soe.ucsc.edu/admin/exe/">binary utilities directory</a>:</p> <ul> <li> <code>bigBedToBed</code> — converts a bigBed file to ASCII BED format.</li> <li> <code>bigBedSummary</code> — extracts summary information from a bigBed file.</li> <li> <code>bigBedInfo</code> — prints out information about a bigBed file.</li> </ul>