Region Decorator

Region Decorators are visualization filters that can dynamically set the color of regions based on their properties and also draw additional markers on top of the regions. Such decorators are useful for rapidly identifying regions with certain properties in a visual way.

For example, in the figure below a track with TF binding sites has been predicted in a "wild-type" DNA sequence (DNA_ref). Based on a SNP annotation track, a new "mutant" DNA sequence was derived (DNA_obs) and an analysis was performed to determine how the TFBSs were affected by the SNPs. The estimated change in binding score for each TFBS was stored in a user-defined region property named "score change". The Region Decorator tool can now be used to elegantly visualize how each region was affected. TFBSs that were positively affected (increased score) are marked with green upward pointing triangles and those that were negatively affected are marked with red downward pointing triangles. The change in score value is also shown in text boxes. Regions unaffected by the SNPs are grayed out.



It is possible to have multiple independent region decorators active at the same time. Go to the "Tools" menu and point the mouse at the "Region Decorator" tool to bring up a submenu containing all the currently active decorators. You can select an existing decorator to modify it or select the "Add New Decorator..." option to add a new decorator. Either choice will bring up the Region Decorator Dialog as shown below.

Region Decorator Dialog



The components of the dialog are as follows (starting from the top left and going anti-clockwise):

Rules

The behaviour of a Region Decorator is defined by a set of rules. Each rule is comprised of two parts: a condition and a decoration.

Condition Decoration
Property Comparator Value
⇒
Show Color Decorator

The condition is made up by the name of a region property, a comparison function (comparator) and a target value. For every region in the track, the condition is evaluated to see if the rule matches by comparing the value of the region's property to the specified target value. If it does match, the corresponding decoration will be applied to that region. The decoration itself consists of a decorator type, a color to draw the decoration in and a flag specifying whether the decorator should be shown at all.

Note that the order of the rules can be important. For rules that apply to the region itself or its border, only the first matching rule from the list will decide the region's color and visibility (subsequent rules will simply be ignored). For rules that apply to overlays, all the rules will be evaluated and the overlays will be drawn from left to right for matching rules. You can change the order of the rules by selecting a rule in the table and dragging it up and down. If you have multiple Region Decorators active at the same time, the last one added will be processed first before older Region Decorators are considered. The final color and visibility for the region is decided by the first matching rule that applies to "region".

Property

This is the name of the region property that the rule should apply to. It can refer to any standard or user-defined region property, including e.g. type, score and strand. Properties can be either numeric or textual, and any property that is not numeric is treated as a text string (such as boolean or list-properties). If the region track is a motif track, the prefix "motif:" can be added before the property name to refer to a property of the motif associated with the region rather than a property of the region itself. For example, if you specify the property "motif:IC-content", the property will refer to the information content of the region's motif (numeric property). For module tracks the "module:" prefix can be used in a similar way. If the property name is left blank, the rule will always be treated as a "match" and be applied to all regions.

Comparator

= Equals: the rule matches if the value of the region property is the same as the specified value or within the specified numeric range
<> Not equals: the rule matches if the value of the region property is not the same as the specified value or is outside of the specified numeric range
> , >= , < , <= Inequality: the rule matches if the numeric value of the region property is respectively greater than, greater than or equal to, less than or less than or equal to the specified value.
If the target value is a numeric range, the rule matches if the numeric value of the region property is outside the range (similar to <>).
For textual properties, the rule matches if its value is not the same as the specified value (similar to <>).
matches For textual properties, the rule matches if the property value matches the specified regular expression value. For numeric ranges, the rule matches if the property value is within the range. For other numeric values the rule never matches.
not matches For textual properties, the rule matches if the property value does not match the specified regular expression value. For numeric ranges, the rule matches if the property value is outside the range. For other numeric values the rule never matches.

Value

The target value for a rule can either be a specific textual or numeric value, a numeric range or a regular expression.
Specific value A single textual or numeric value used for comparison, such as e.g. "SINE" or "13.42"
Numeric range Numeric ranges are specified as two numbers separated by a comma and enclosed in brackets. The first number denotes the smallest value in the range and the second denotes the largest. A square opening or closing bracket means that the value next to it should be included in the range whereas a round bracket (parenthesis) means the value is excluded.
For example:

   [ 0, 10 ] : matches values equal to or greater than zero and equal to or less than ten (i.e. the range includes both zero and ten): 0 <= x <= 10
   [ 0, 10 ) : matches values equal to or greater than zero and less than ten (i.e. the range includes zero but not ten): 0 <= x < 10
   ( 0, 10 ] : matches values greater than zero and equal to or less than ten (i.e. the range includes ten but not zero): 0 < x <= 10
   ( 0, 10 ) : matches values greater than zero and less than ten (i.e. the range does not include zero or ten): 0 < x < 10
Regular expression Target values can be regular expressions when comparing textual properties using the "(not) matches" comparator function. Note that the text property must match the full regular expression, so if you want to check if e.g. a region property contains the word "xxx" as a substring, you must define the regular expression accordingly: ".*xxx.*"

Some commonly used regular expression rules include:
  • A vertical bar can be used to separate alternative matching expressions
  • Parentheses can be used to group character togethers
  • A dot "." matches any single character
  • A "+" plus sign after a character or group means that this character/group should match one or more times
  • A "*" star sign after a character or group means that this character/group should match zero or more times
  • A "?" sign after a character or group means that this character/group should match zero or one times (i.e. it is optional)
  • Two numbers in braces "{n,m}" directly behind a character or group means that the character/group should match between n and m times
  • A character class can be defined by listing characters in brackets and will match any single character in the class. E.g. the class "[abc]" will match either a, b or c
  • You can negate a character class by placing a "^" directly after the first bracket. E.g. the character class "[^abc]" will match any single character besides a, b and c
  • The special character class denoted by "\d" will match a single digit character and the complementary class "\D" will match a single non-digit character
  • The special character class denoted by "\w" will match a single "word" character (digit, letter or underscore) and the complementary class "\W" will match a single non-word character
  • The special character class denoted by "\s" will match a single whitespace character and the complementary class "\S" will match a single non-whitespace character
  • The following characters have special meaning within regular expressions and must be escaped with a backslash in front if you want to refer to them in a literal sense: \.+*[]{}()?^$|
For more information about the syntax of regular expressions in JAVA, consult this tutorial (or this one).

Examples:
The expression "cat|dogs?" will match either cat, dog or dogs.
The expression "b[aie]ts" will match either bats, bits or bets.
The expression "Go{2,5}gle" will match either Google, Gooogle, Goooogle or Gooooogle.
The expression "M.\d+" will match any word beginning with "M" followed by any character and then a succession of digits.
The expression "Hip(hop)+opotamus" will match words beginning with "Hip", followed by "hop" repeated any number of times and then ending with "opotamus".

Show


Color

Specific color The region, border or overlay will be draw in the specific color selected
Transparent The region itself (and its border) is drawn in a fully transparent color which renders it, in effect, invisible. The difference between using a transparent color rather than just unchecking the "Show" box is that overlays will still be drawn on top of the region.
Gray Out The region and its border is drawn in a light gray color with white label color and grayed out motif logo. The difference between selecting "gray out" and a regular light gray color is that with the latter option, the region label and motif logos will still be drawn in regular colors.
Original The region or overlay will be drawn in the original color of the region, as determined by its type. If applied to a border, it will either be drawn in a black color, a darker shade of the current region color or not drawn at all depending on the visualization settings for the track.
Gradients Gradients are special color schemes that can only be used with numeric properties. They assume that the property values have been normalized to the range [0,1] and will select the particular color to use depending on the property value.
  • RAINBOW: Starts at BLUE for the lowest value and goes through GREEN and YELLOW before ending in RED for the highest value
  • COLD: Same as the bottom half of RAINBOW; starting at BLUE for the lowest value and ending in GREEN for the highest value
  • WARM: Same as the top half of RAINBOW; starting at GREEN for the lowest value and ending in RED for the highest value
  • GRAYSCALE: Starts at BLACK for the lowest value and ends up in WHITE for the highest value
If the "property" of the rule does not refer to a numeric property, the color will default to the original color of the region.


Decorator

Region The color and visibility settings of the rule will be applied to the region itself
Border The color and visibility settings of the rule will be applied to the region's border
"Text" Draws a text box on top of the region containing the exact text within the quotes. The text is drawn in the selected color.
{property} Draws a text box on top of the region containing the value of the specified property. The text is drawn in the selected color.
If the property is unknown, the text "<*>" will be drawn instead.
[property] Draws a "gauge" on top of the region reflecting the value of a numeric property.
The gauge is in the form of a box which is filled with color from the bottom up for greater values.
The values of the property must have been normalized to the range [0,1].
If the property is unknown or not a numeric value, it will be drawn similar to a value of zero (empty gauge).
Square
Circle
Diamond
Star
Check
Cross
Plus
Minus
Smile
Frown
Triangle
Arrow		 Draws a small icon on top of the region

   

Arrows and triangles can be drawn in four directions: Up, Down, Left and Right.
Squares and circles come in both normal and small sizes.

Overlays

The last four options in the "decorator" table above (in green color) are referred to as overlays because they are drawn as text boxes or images on top of the region rather than affecting the appearance of the region itself. It is possible to have multiple overlay rules for the same Region Decorator, and if more than one rule matches the overlays will be positioned from left to right. For example, in the image on top of this page, the regions affected by SNPs all have two overlays – a triangle overlay followed by a property value text box.

If you have several different Region Decorators active at the same time, their overlays could end up being drawn on top of each other since each Region Decorator starts laying out its overlays from the left edge of the region. Sometimes this behaviour can be beneficial, however. In the example below we have two decorators. The second decorator illustrates the score property of each region using a large circle overlay in RAINBOW gradient colors and the first decorator shows the strand orientation of the region with a smaller red or green circle inside the larger circle. Note that since more recently added Region Decorators are processed before older decorators, the decorator drawing the smaller circle must be added before the decorator drawing the larger circle, or else the larger circle will be drawn on top of the smaller circle and thus hide it completely.

Decorator#1
Property Comparator Value Show Color Decorator
strand > 0 ✔ RED Small Circle
strand < 0 ✔ GREEN Small Circle

Decorator#2
Property Comparator Value Show Color Decorator
score >= 0 ✔ Rainbow Circle



Aligning overlays with SNPs
Overlays are a nice way to illustrate the location of SNPs or similar small regions that can potentially be hard to spot, especially at larger scales where the regions themselves are drawn very narrow. The Region Decorator below employs the "transparent" color to hide the region itself and rather uses a triangle overlay (which is always drawn at the same size) to mark its location. There is one drawback with this approach, however, which is that the top of the triangle does not point directly to the location of the SNPs (marked in pink color above the DNA track) but rather slightly off to the right since the left edge of the overlay is positioned after the edge of the region, as illustrated in the top figure below.

The way to correct this is to add an asterisk (*) behind the name of the overlay decorator. This will position the overlay so that the middle of the overlay aligns with the middle of the leftmost base of the region. As shown in the bottom image, the top of the triangle will now point directly to the location of the SNP as desired. Any subsequent overlays will be placed relative to this first overlay as normal, from left to right (unless they also have a * behind their name).

Property Comparator Value Show Color Decorator
  = 0 ✔ Transparent Region
  = 0 ✔ Original Triangle Up

  Triangle Up  
  Triangle Up *  


Anchoring overlays
If you add an exclamation mark (!) behind the name of a decorator, a vertical line (here called an "anchor") will be drawn from the middle of the overlay and directly down to the bottom of the track. The anchor can be combined with the alignment option described above by adding either "*!" or "!*" behind the decorator name. Anchors are another way to have an overlay point to a specific position in the track, and it can also be used with overlays that do not naturally point in any specific direction (such as circles and squares).



The Library

Complex region decorators can have many rules and take quite some time to set up properly. The library allows you to store away such decorators so that you can easily retrieve and reuse them at a later time without having to define the whole decorator again from scratch. It also allows you to export and import decorators to and from files that can be shared with others.