Track Decorators

Overview

Track decorators allow highlighting parts of features with colors and/or symbols (glyphs/shapes) within a single track. The decorations can either be overlaid onto the feature or shown directly underneath. Decorators can be added to BED 12+, bigBed, PSL, and bigGenePred tracks. To add decorations to a track, the decorations must first be stored in a separate bigBed file that includes extra fields to identify the decorated items. The track settings for the track must then be modified to include a pointer to that bigBed file; this can be done either in the track line for a custom track, or in the trackDb.txt file for a hub. At present, we only support a single decorator per track, but we anticipate supporting multiple decorators in the future.

Contents

Annotating the Genome
The Decorator Styles
Getting Started
Examples
Hub TrackDb Settings
Troubleshooting

Annotating the Genome

The genome browser‘s primary way to annotate the genome uses colored rectangles ("exons" for gene tracks) linked by thin lines ("introns"), often stored as a bigBed. These were originally used for genes but then evolved to cover other types of annotations, e.g. enhancers, chromatin modifications, or single nucleotide variants. We usually call these annotations "features". Each rectangle ("exon") of a feature has the same color and individual parts cannot be highlighted. If you wanted to highlight parts of the features, traditionally this required a second track.

A track decorator is more compact than creating a separate track for these sub-features, but loses some of the abilities of normal tracks, for example, there is no right-click on the sub-features and the user cannot click these sub-features. The primary use case driving this display was protein-domains drawn on top of gene models, but we have found many other applications since then, e.g. drawing summits on ATAC peaks or highlighting selenocysteines on transcripts.

The Decorator Styles

Track decorators can be shown in two styles, "block" and "glyph" style. The "block" style option can be used to color exons and introns and can display a label for them. For example, the "block" track decorator could be used to overlay protein domain boundaries on transcripts where usually one would use an entirely different track for the domains.

The "glyph" style option offers 8 different types of glyphs and the color of choice.

The "glyph" style option can be used to draw entirely new symbols, for example, to indicate insertion positions on the genome with small triangles. We appreciate user feedback. If you have glyph questions, glyph style requests, or have found new glyph applications, please contact our mailing list.

To use decorators in your track hub or custom tracks, you will need to create an additional bigBed file that defines the regions, colors, and glyphs.

Getting Started

The Decorator bigBed

A decorator bigBed file, which contains decorations for annotating another track, is very similar to our standard bigBed file format. The only difference is the addition of some extra required fields, which describe how each decoration should be drawn and what item within that other track it annotates.

The full .as format for decorator bigBed files is as follows: 

    string chrom;      "Chromosome (or contig, scaffold, etc.)"
    uint   chromStart; "Start position in chromosome"
    uint   chromEnd;   "End position in chromosome"
    string name;       "Name of item"
    uint   score;      "Score from 0-1000"
    char[1] strand;    "+ or -"
    uint thickStart;   "Start of where display should be thick (start codon)"
    uint thickEnd;     "End of where display should be thick (stop codon)"
    uint color;        "Primary RGB color for the decoration"
    int blockCount;    "Number of blocks"
    int[blockCount] blockSizes; "Comma separated list of block sizes"
    int[blockCount] chromStarts; "Start positions relative to chromStart"
    string decoratedItem; "Identity of the decorated item in chr:start-end:item_name format"
    string style;      "Draw style for the decoration (e.g. block, glyph)"
    string fillColor;  "Secondary color to use for filling decoration, blocks, supports RGBA"
    string glyph;  "The glyph to draw in glyph mode; ignored for other styles"

A copy of this file can be found here.

Valid values for the style field are "block" and "glyph". Valid glyph entries include "Circle", "Square", "Diamond", "Triangle", "InvTriangle", "Octagon", "Star", and "Pentagram". If the text isn't recognized, Circle will be used by default.

The "decoratedItem" field (chr:start-end:item_name format) captures the link between the decoration and what item in the track is being decorated. The contents of this field must be the chromosome, BED start coordinate, BED end coordinate, and item name for the decorated item (note - these are 0-based half-open BED coordinates, not 1-based fully closed coordinates. That means they are the same values as should appear in a BED file describing the decorated item).

Examples

Example #1: Building a decorator bigBed

Here is an example of how to use this format. Consider the item in BED format as a "feature": 

chr1 1000 2000 feature 0 + 1000 2000 0 2 400,400 0,600

We can take this BED file and construct a mainEx.bb from it as described in the bigBed documentation. To add a decoration to the "feature" item that highlights the region at position chr1:1,201-1,800, we could create a corresponding item in a decorator bed file like the following: 

chr1 1200 1800 highlight 0 + 1200 1800 255,0,0,255 1 600 0 chr1:1000-2000:feature block 255,0,0,128 Ignored

To add a glyph decoration that marks the final base of the transcript with a green circle, we would then include the following line in the decorator bed file:

chr1 1999 2000 green_circle 0 + 1999 2000 0,255,0,255 1 1 0 chr1:1000-2000:feature glyph 0,255,0,255 Circle

Both of these bed decorations can be stored in a file named decoratorsEx.bed and then built as a decoratorsEx.bb using the hg38.chrom.sizes and the decoration.as files and running the following command:

bedToBigBed -type=bed12+ -as=decoration.as decoratorsEx.bed hg38.chrom.sizes decoratorsEx.bb
Debugging the decorator bigBed

The resulting decoratorsEx.bb file can be displayed as a stand-alone custom track for debugging purposes. This process allows verification that the decorations are correctly applied. To display the decorator bigBed, navigate to the UCSC Genome Browser Custom Tracks page and paste the URL into the designated text field:

browser position chr1:1000-2000
https://genome.ucsc.edu/goldenPath/help/examples/decorator/decoratorsEx.bb

Once the decorator bigBed is loaded, the decorations will be rendered on the UCSC Genome Browser, allowing for verification of the correct display.

Example #2: Create a custom track

Create a decorator bigBed custom track using the decorator bigBed file from Example #1.

  1. Construct a track line that references the bigBed and the decorator bigBed file:

    browser position chr1:1000-2000
track type=bigBed name="Decorators Example Two" description="bigBed with decorators" visibility=pack bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/mainEx.bb decorator.default.bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/decoratorsEx.bb
  2. Paste the track line into the custom track page for the human assembly, hg38.
  3. Click the button.

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

https://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hgct_customText=track%20type=bigBed%20bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/mainEx.bb%20decorator.default.bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/decoratorsEx.bb&position=chr1:1000-2000

Example #3: Create a decorator bigBed with extra (custom) fields

Additional fields can also be added onto the end of the .as file, though they will not be used by default. The additional fields can be used for custom feature filters and mouseOvers options. For example, to set up a filterValues filter, you would add the following two fields to the decoration.as file:

    int numKeywords;  "Number of keywords"
    string[numKeywords] keywords;  "Keywords for this decorator"

The numKeywords field specifies the number of keywords and the keywords field specifies the keywords. You would then modify your decoratorsEx.bed file to include an additional fields at the end of each line, detailing which keywords apply to each of the decorations:

chr1 1200 1800 highlight 0 + 1200 1800 255,0,0,255 1 600 0 chr1:1000-2000:feature block 255,0,0,128 Ignored 1 Type1
chr1 1999 2000 green_circle 0 + 1999 2000 0,255,0,255 1 1 0 chr1:1000-2000:feature glyph 0,255,0,255 Circle 2 Type2,Type3

The first bed entry filters for one class "Type1" and the second bed entry filters for two classes "Type2,Type3".

You can also add a mouseOverField which will allow you to mouse over text that is different from the "name" of the decorator bigBed. You would add the following field to the decoration.as file:

    string mouseOverField;  "Mouse over text"

Then modify your decoratorsEx.bed file to include the additional field. 

chr1 1200 1800 highlight 0 + 1200 1800 255,0,0,255 1 600 0 chr1:1000-2000:feature block 255,0,0,128 Ignored 1 Type1 alternate_highlight_name
chr1 1999 2000 green_circle 0 + 1999 2000 0,255,0,255 1 1 0 chr1:1000-2000:feature glyph 0,255,0,255 Circle 2 Type2,Type3 alternate_green_circle_name

You would then rebuild the decorations.bb file using the decorationEx_fields.as with extra fields: 

bedToBigBed -type=bed12+ -as=decorationEx_fields.as decoratorsEx.bed hg38.chrom.sizes decoratorsEx.bb

Hub TrackDb Settings

The statement below provides trackDb settings to add decorators to a track hub:

track testTrack
type bigBed 12
bigDataUrl https://genome.ucsc.edu/goldenPath/help/examples/decorator/mainEx.bb
itemRgb on
decorator.default.bigDataUrl https://genome.ucsc.edu/goldenPath/help/examples/decorator/decorationsEx.bb

Other settings are available to further configure decorators. Each may be applied to the decorator instead of the primary track by prepending "decorator.default." to the setting. For example, to set up a filterValues filter on the "keywords" field of the decorator, allowing the user to filter to any combination of three classes "Type1", "Type2", and "Type3", the following trackDb entry could be used were the multipleListOr setting splits the three classes list values by commas: 

decorator.default.filterValues.keywords Type1,Type2,Type3
decorator.default.filterType.keywords multipleListOr

Please note that this would also require building an extra keywords field into the decorator bigBed to hold those values, see Example #3 for more details.

Decorators also support the mouseOver and mouseOverField settings that can be applied to bigBed tracks:

decorator.default.mouseOver decorator $name mouseOver
decorator.default.mouseOver $mouseOver

You can configure the block decoration placement visibility to "overlay", "adjacent", or "hide" using the blockMode setting:

decorator.default.blockMode adjacent

You can use the maxLabelBases setting to set a maximum window size (in bases) for which labels will be drawn. If not set, the value will default to 200kb. This can be useful to deactivate decoration labels when there are too many track items and too many decoration labels to process visually.

decorator.default.maxLabelBases 100000

A full list of supported decorator settings is available in the trackDb documentation.

Troubleshooting

If you get an error when you run the bedToBigBed program, please check your input BED 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) in your input BED file before using the bedToBigBed program.