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. A full list of supported decorator
settings is available in the
trackDb documentation, while the next section discusses how
to build a decorator bigBed file.
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)"
@@ -129,85 +129,168 @@
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). + + +
-Here is an example of how to use this format. Consider a BED item like the following in our main track: +Here is an example of how to use this format. Consider the items in BED format as features: +
+chr22 1000 5000 featureA 960 + 1000 5000 255,0,0 2 567,488, 0,3512 +chr22 2000 6000 featureB 900 - 2000 6000 0,255,0 2 433,399, 0,3601 ++
+We can take this BED file and construct a +mainEx1.bb from it as described in the bigBed +documentation. To add a decoration to featureA that highlights the region from base 1000 +to base 1282, we could create a corresponding item in a decorator bed file like the following: +
++chr22 1000 1282 highlight1 1000 + 1000 1282 255,0,0,255 1 282 0 chr22:1000-5000:featureA block 0,0,0,255 Ignored ++
highlight1 specified in the fourth field of the
+ decorator bed file.255,0,0,255 (9th field of the decorator bed file) specifies that the
+ decoration outline will be in solid red (255 red, 0 green, 0 blue, 255 alpha).chr22:1000-5000:featureA (13th field of the decorator bed file) entry describes
+ which item in the main bed file is to be annotated. In this case, it's an item with the name
+ "featureA" that spans chr22 from base 1000 to base 5000.0,0,0,255 (15th field of the decorator bed file) specifies that the interior
+ of the decoration will be shaded black (0 red, 0 green, 0 blue, 255 alpha). The decorated item
+ could be partially visible by using the alpha value.Ignored value is used in the last field of the bed file because we are
+ creating a block decoration (a decoration that annotates a range of bases).To add a glyph decoration that marks an exon from base 2000 to base 2433, with a red triangle, we would then +include the following line in the decorator bed file:
++chr22 2000 2433 Triangle 900 - 2000 2433 255,0,0,255 1 433 0 chr22:2000-6000:featureB glyph 255,0,0,255 Triangle ++
Triangle specified in the fourth field of the
+ decorator bed file255,0,0,255 (9th field of the decorator bed file) specifies that the
+ decoration outline will be in solid red (255 red, 0 green, 0 blue, 255 alpha).chr22:2000-6000:featureB (13th field of the decorator bed file) entry describes
+ which item in the main bed file is to be annotated. In this case, it's an item with the name
+ "featureB" that spans chr22 from base 2000 to base 6000.0,0,0,255 (15th field of the decorator bed file) specifies that
+ the interior of the decoration will be shaded black (0 red, 0 green, 0 blue, 255 alpha). The
+ decorated item could be partially visible by using the alpha value.Triangle glyph style is specified in the last field of the decorator bed fileAdditional "block" and "glyph" decorators can be added to the decorator bed file:
++chr22 4512 4674 highlight2 1000 + 4512 4674 48,197,255,255 1 162 0 chr22:1000-5000:featureA block 0,0,0,255 Ignored +chr22 4838 5000 highlight3 1000 + 4838 5000 93,226,60,255 1 162 0 chr22:1000-5000:featureA block 0,0,0,255 Ignored +chr22 5601 5734 Diamond 1000 - 5601 5734 0,0,0,255 1 133 0 chr22:2000-6000:featureB glyph 48,197,255,255 Diamond +chr22 5867 6000 invTriangle 1000 - 5867 6000 0,0,0,255 1 133 0 chr22:2000-6000:featureB glyph 93,226,60,255 invTriangle ++
+These bed decorations can be stored in a file named decoratorsEx1.bed +and then built as a decoratorsEx1.bb from it with the following command:
+bedToBigBed -type=bed12+ -as=decoration.as decoratorsEx1.bed hg38.chrom.sizes decoratorsEx1.bb ++ +
+A custom track can then be created using the main bigBed file 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/mainEx1.bb decorator.default.bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/decoratorsEx1.bb+
+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/mainEx1.bb%20decorator.default.bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/decoratorsEx1.bb&position=chr1:1000-2000 ++ + +
+Consider a BED item like the following in our main track:
chr1 1000 2000 MyItem 0 + 1000 2000 0 2 400,400 0,600
-We can take this BED file and construct a -bigBed from it as described in the bigBed +We can take this BED file and construct a +mainEx2.bb from it as described in the bigBed documentation. After that, if we wanted to add a decoration to this item that highlighted the region from base 1200 to base 1800, we could create a corresponding item in a decorator bigBed file like this:
chr1 1200 1800 MyDecoration 0 + 1200 1800 255,0,0,255 1 600 0 chr1:1000-2000:MyItem block 255,0,0,128 Ignored
+
The first color, 255,0,0,255 specifies that the decoration outline will be in solid red (255 red,
0 green, 0 blue, 255 alpha). The second color 255,0,0,128, specifies that the interior of the
decoration will be shaded toward pure red, but that the decorated item will still be partially visible behind it
(due to the alpha value of 128). The chr1:1000-2000:MyItem entry describes which item in the main
track is to be annotated. In this case, it's an item with the name "MyItem" that spans chr1 from base 1000 to
base 2000. The final Ignored value is not used here because we are creating a block decoration
(a decoration that annotates a range of bases).
To add a glyph decoration to our file that marked the final base of the transcript with a green circle, we could also include the following line in our BED file of decorations:
chr1 1999 2000 MySecondDecoration 0 + 1999 2000 0,255,0,255 1 1 0 chr1:1000-2000:MyItem glyph 0,255,0,255 Circle
-If we store both of those decorations in a file named input.bed, we can -then build a bigBed file from it with the following command:
-bedToBigBed -type=bed12+ -as=decoration.as input.bed hg38.chrom.sizes decorations.bb +If we store both of those decorations in a file named decoratorsEx2.bed, we can +then built as a decoratorsEx2.bb from it with the following command: +bedToBigBed -type=bed12+ -as=decoration.as input.bed hg38.chrom.sizes decoratorsEx2.bb- -Example #2: Create a Custom Track
--Create a decorator bigBed custom track using the decorator bigBed file from Example #1.
- +A custom track can then be created using the main bigBed file and the decorator bigBed file:
- - Construct a track line that references the bigBed - and decorator bigBed file: + Construct a track line that references the mainEx2.bb + and decoratorsEx2.bb
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/main.bb decorator.default.bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/decorations.bb+track type=bigBed name="Decorators Example Two" description="bigBed with decorators" visibility=pack bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/mainEx2.bb decorator.default.bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/decoratorsEx2.bb
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/main.bb%20decorator.default.bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/decorations.bb&position=chr1:1000-2000 +https://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hgct_customText=track%20type=bigBed%20bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/mainEx2.bb%20decorator.default.bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/decorator/decoratorsEx2.bb&position=chr1:1000-2000Example #3: Create a decorator bigBed with extra (custom) fields
Additional fields can also be added onto the end of the .as file if you desire, though they will not be used at all by default. Adding fields allows you to set up custom filtering of which decorations are displayed. For example, to include a "keywords" field you could add the following to the end of the decoration.as file:
int numKeywords; "Number of keywords" string[numKeywords] keywords; "Keywords for this decorator"You would then modify your input.bed file to include an additional fields at the end of each line, detailing which keywords