bigNarrowPeak Track Format

The bigNarrowPeak format stores annotation items that are a single block with a single base peak within that block, much as BED files indexed as bigBeds do. A bigNarrowPeak file is a standard six field bed with four additional fields that contain three doubles with scoring information and the location of the single base peak. It is the binary version of the ENCODE narrowPeak or point-source peak format.

The bigNarrowPeak files are created using the program bedToBigBed, run with the -as option to pull in a special autoSql (.as) file that defines the extra fields of the bigNarrowPeak.

The bigNarrowPeak 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, indexed binary files have considerably faster display performance than regular BED format files when working with large data sets. The bigNarrowPeak 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 bigNarrowPeak files, please see the Hosting section of the Track Hub Help documentation.

bigNarrowPeak file definition

The following autoSql definition is used to specify bigNarrowPeak files. This definition, contained in the file bigNarrowPeak.as, is pulled in when the bedToBigBed utility is run with the -as=bigNarrowPeak.as option.


table bigNarrowPeak
"BED6+4 Peaks of signal enrichment based on pooled, normalized (interpreted) data."
(
    string chrom;        "Reference sequence chromosome or scaffold"
    uint   chromStart;   "Start position in chromosome"
    uint   chromEnd;     "End position in chromosome"
    string name;	 "Name given to a region (preferably unique). Use . if no name is assigned"
    uint   score;        "Indicates how dark the peak will be displayed in the browser (0-1000) "
    char[1]  strand;     "+ or - or . for unknown"
    float  signalValue;  "Measurement of average enrichment for the region"
    float  pValue;       "Statistical significance of signal value (-log10). Set to -1 if not used."
    float  qValue;       "Statistical significance with multiple-test correction applied (FDR -log10). Set to -1 if not used."
    int   peak;         "Point-source called for this peak; 0-based offset from chromStart. Set to -1 if no point-source called."
)

Click here to view an example of a bigNarrowPeak (bed6+4) input file.

Note that the bedToBigBed utility uses a substantial amount of memory: approximately 25% more RAM than the uncompressed BED input file.

Creating a bigNarrowPeak track

To create a bigNarrowPeak track, follow these steps:

Step 1. Create a bigNarrowPeak file. The first six fields of the bigNarrowPeak bed6+4 format are described by the basic BED file format shown here. You can also read about narrowPeak (or point-source peak), the precursor to bigNarrowPeak, here. Your bigNarrowPeak file must also contain the four extra fields described in the autoSql file definition shown above: signalValue, pValue, qValue, peak. Your bigNarrowPeak file must be sorted first on the chrom field, and secondarily on the chromStart field. You can use the UNIX sort command to do this:

sort -k1,1 -k2,2n unsorted.bed > input.bed

Step 2. Download the bedToBigBed program from the binary utilities directory.

Step 3. Use the fetchChromSizes script from the same directory to create a chrom.sizes file for the UCSC database with which you are working (e.g., hg38). Alternatively, you can download the chrom.sizes file for any assembly hosted at UCSC from our downloads page (click on "Full data set" for any assembly). For example, the hg38.chrom.sizes file for the hg38 database is located at http://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.chrom.sizes.

Step 4. Create the bigNarrowPeak file from your sorted input file using the bedToBigBed utility:

bedToBigBed -as=bigNarrowPeak.as -type=bed6+4 bigNarrowPeak.txt chrom.sizes myBigNarrowPeak.bb

Step 5. Move the newly created bigNarrowPeak file (myBigNarrowPeak.bb) to a web-accessible http, https, or ftp location.

Step 6. Construct a custom track using a single track line. Note that any of the track attributes listed here are applicable to tracks of type bigNarrowPeak. The basic version of the track line will look something like this:

track type=bigNarrowPeak name="My Big NarrowPeak" description="A Set of Peaks from DNase Experiments" bigDataUrl=http://myorg.edu/mylab/myBigNarrowPeak.bb

Step 7. Paste this custom track line into the text box on the custom track management page.

The bedToBigBed program can be run with several additional options. For a full list of the available options, type bedToBigBed (with no arguments) on the command line to display the usage message. If you do not have access to a web-accessible server and need hosting space for your bigNarrowPeak files, please see the Hosting section of the Track Hub Help documentation.

Examples

Example #1

In this example, you will create a bigNarrowPeak custom track using a bigNarrowPeak file, bigNarrowPeak.bb, located on the UCSC Genome Browser http server. This file contains data for the hg38 assembly.

To create a custom track using this bigNarrowPeak file:

Construct a track line that references the file:

track type=bigNarrowPeak name="bigNarrowPeak Example One" description="A bigNarrowPeak file" bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/bigNarrowPeak.bb

Paste the track line into the custom track management page for the human assembly hg38 (Dec. 2013).
Click the "submit" button.

Custom tracks can also be loaded via one URL line. The link below loads the same bigNarrowPeak track and sets additional parameters in the URL:

http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hgct_customText=track%20type=bigNarrowPeak %20name=Example%20bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/bigNarrowPeak.bb

After this example bigNarrowPeak track is loaded in the Genome Browser, click on a peak in the browser's track display to view the details page for that peak.

Example #2

In this example, you will create your own bigNarrowPeak file from an existing bigNarrowPeak input file.

Save the example bed6+4 input file, bigNarrowPeak.txt, to your computer (Step 1 in Creating a bigNarrowPeak track, above).
Download the bedToBigBed utility (Step 2, above).
Save the hg38.chrom.sizes text file to your computer. This file contains the chrom.sizes for the human hg38 assembly (Step 3, above).
Save the autoSql file bigNarrowPeak.as to your computer.

Run the bedToBigBed utility to create the bigNarrowPeak output file (step 4, above):

bedToBigBed -type=bed6+4 -tab -as=bigNarrowPeak.as bigNarrowPeak.txt hg38.chrom.sizes bigNarrowPeak.bb

Place the newly created bigNarrowPeak file (bigNarrowPeak.bb) on a web-accessible server (Step 5, above).
Construct a track line that points to the bigNarrowPeak file (Step 6, above).
Create the custom track on the human assembly hg38 (Dec. 2013), and view it in the Genome Browser (step 7, above).

Example #3

In this example, you will see the additional filtering options available for the signalValue, pValue, qValue fields in the bigNarrowPeak format.

Look to the above constructed track line in example one that references the bigNarrowPeak.bb file.
Now look at the below version that adds the following filters signalFilter, pValueFilter, qValueFilter to the track line as well as setting limitations on those filters with additional signalFilterLimits, pValueFilterLimits, qValueFilterLimits settings.
```
track type=bigNarrowPeak name="bigNarrowPeak Example Filter" description="A bigNarrowPeak file with additional Filter Settings" signalFilter=0 signalFilterLimits=0:18241 pValueFilter=2 pValueFilterLimits=0:300 qValueFilter=2 qValueFilterLimits=0:300 bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/bigNarrowPeak.bb
```
These values are simply added to the earlier track line in pairs, such as pValueFilterLimits=0:300, and can be given a set value for where the filter should start such as pValueFilter=2.
Paste the track line from above into the custom track management page for the human assembly hg38 (Dec. 2013).
Click the "submit" button.
When viewing the track, right-click the track and then select the "Configure bigNarrowPeak Example One" option and you will see you can enter different filtering options.

These same options could also be used in a track hub using the bigNarrowPeak format. Here is an example track hub stanza:

  track exBigNarrowPeakTrack
  type bigNarrowPeak
  visibility full
  signalFilter 0
  signalFilterLimits 0:10000
  pValueFilter 0
  pValueFilterLimits 0:300
  qValueFilter 0
  qValueFilterLimits 0:300
  shortLabel Ex bigNPk
  longLabel bigNarrowPeak Example
  bigDataUrl http://genome.ucsc.edu/goldenPath/help/examples/bigNarrowPeak.bb

Sharing your data with others

If you would like to share your bigNarrowPeak data track with a colleague, learn how to create a URL by looking at Example #11 on this page and the additional URL optional parameters section.

Extracting data from bigBed format

Because the bigNarrowPeak files are an extension of bigBed files, which 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 binary utilities directory.

bigBedToBed — converts a bigBed file to ASCII BED format.
bigBedSummary — extracts summary information from a bigBed file.
bigBedInfo — prints out information about a bigBed file.

Such tools can be used to obtain only features within a given range, for example:

bigBedToBed http://hgdownload.soe.ucsc.edu/gbdb/danRer10/transMap/V4/danRer10.refseq.transMapV4.bigPsl -chrom=chr6 -start=0 -end=1000000 stdout

As with all UCSC Genome Browser programs, type the program name (with no parameters) at the command line to view the usage statement.

Troubleshooting

If you encounter an error when you run the bedToBigBed program, check your input file for data coordinates that extend past the end of the chromosome. If these are present, run the bedClip program (available here) to remove the problematic row(s) before running the bedToBigBed program.