Difference between revisions of "Glyphs and Glyph Options"

From GMOD
Jump to: navigation, search
(The generic Glyph)
(The generic Glyph)
Line 143: Line 143:
 
The full list of options recognized by generic and all descendent glyphs is given in the following table:
 
The full list of options recognized by generic and all descendent glyphs is given in the following table:
  
{| class="wikitable"
+
{| class="wikitable sortable"
 
|+ All the options recognized by "generic" and descendents
 
|+ All the options recognized by "generic" and descendents
 
|-
 
|-
Line 151: Line 151:
 
|-
 
|-
 
! key
 
! key
| Description of the track in the tracks table
+
| Description of the track in the tracks table.
 
| ''same as the stanza label''
 
| ''same as the stanza label''
 
|-
 
|-
| row 2, cell 1
+
! category
| row 2, cell 2
+
| The category of the track in the tracks table. You may use the format "category1:category2:category3" to specify subcategories.
| row 2, cell 3
+
| Uncategorized tracks will be placed in a hold-all named "General"
 
|}
 
|}

Revision as of 19:19, 31 January 2009

GBrowse offers many different options for displaying tracks. Tracks are generated by the Perl Graphics module, which is the definitive reference for the various display options in GBrowse. This page provides an introduction to the most commonly used glyphs.

Selecting and Configuring Glyphs

Every GBrowse [Track] stanza should have a glyph option. This option selects the shape and behavior of each feature rendered in the track. Other options fine tune the glyph's appearance by selecting its height, color, and other display properties. Several standard display options are shared among all glyphs; others are glyph-specific.

The simplest [Track] stanza will look like this:
Figure 1: The "generic" glyph with all its defaults.
[Demo]
feature = gene
glyph   = generic

The "generic" glyph is the basis of all other glyphs and simply draws a solid box using the cyan color. A track rendered with this configuration will look like Figure 1.

You can change the default appearance of the generic glyph using the standard height, bgcolor, and fgcolor options. You can also assign a longer key to the track using the key option. For example:
Figure 2: The "generic" glyph with changed options.
[Demo]
feature = gene
glyph   = generic
bgcolor = orange
fgcolor = black
height  = 9
key     = Demo track with custom display options

Figure 2 shows how this will appear.

Values Used in Glyph Options

Before we dive into the various glyphs and their options, we will discuss colors, true/false flags, and other values that are used in the options.

Colors

Many options accept color values. You can specify colors by name, by HTML value, or using CSS (cascading stylesheet) notation.

By Name

GBrowse color-related options accept human readable color names like "yellow" and "chartreuse". The full list is contained in the color chart in Figure 3.
Figure3: Named colors

By HTML Value

GBrowse accepts HTML style color values in the form "#RRGGBB", where RR, GG and BB are the red, green and blue intensity values respectively. The intensity values are expressed in hexadecimal, and range from 00 (completely off) to FF (completely on). Black is #000000 (all colors off), and white is #FFFFFF (all colors at full intensity). See [HTML Colors] for several nice tables of common #RRGGBB combinations. For example, to give a glyph a bright blue background, you could specify a bgcolor option like this:

bgcolor = #0000FF

Using CSS Notation

GBrowse also accepts [Cascading Stylesheeet Level 3] color specifications, which are in the form "rgb(r,g,b)", where r, g, b are red, green and blue color intensities expressed as percentages or decimal values from 0 to 255. In the percentage form, a bright red background color would be expressed as:

bgcolor = rgb(100%,0%,0%)

in the second form, the color yellow (which is an equal combination of red and green in rgb space) could be written as:

bgcolor = rgb(255,255,0)

Alpha (Transparency) Values

You can also create colors with various degrees of translucency by specifying an alpha value. Alpha values can be specified as a hexadecimal value, as a floating point number between 0.0 and 1.0, or as a percentage from 0% to 100%. When using a named color, you can specify the degree of opacity in either of these ways:

bgcolor = blue:0.8
bgcolor = blue:80%

Either of these forms specifies a blue value that is 80% opaque. Values of 0.0 or 0% will create an entirely transparent color (which will appear as a "hole" in the drawing canvas), while values of 1.0 or 100% will create an entirely opaque color.

To specify alpha values with CSS syntax, use the "rgba(r,g,b,a)" notation, where "a" is the value of the alpha channel expressed either as a floating point number between 0.0 and 1.0, or as a percentage. In this form, 80% blue can be expressed in any of these forms:

bgcolor = rgba(0%,0%,100%,80%)
bgcolor = rgba(0,0,255,80%)
bgcolor = rgba(0,0,255,0.8)

Finally, you can use an extension of the HTML color format to specify the color and alpha values as #RRGGBBAA, where AA is the hexadecimal representation of alpha. This format is a bit unintuitive because the alpha channel is expressed as a hexadecimal number between 0 and 7F (decimal 127), where 0 is completely opaque and 7F is completely transparent. This reversal of the direction of opacity reflects how alpha is represented in the underlying graphics data structure. In this format, 80% blue can be expressed as:

bgcolor = #0000FF19

True/False Values

Many options are flags that turn certain features on or off. GBrowse follows the Perl programming language convention of using 0 (zero) as false, and accepting any non-zero value as true. Most commonly, people use 0 for false and 1 for true. For example, the "gene" glyph takes a decorate_introns option, which if true draws little arrowheads on the introns of the gene's transcripts to indicate the direction of transcription. To activate this feature, set the option to a true value:

decorate_introns = 1

to deactivate, set it to false:

decorate_introns = 0

Fonts

Figure 4: Fonts available to GBrowse
Some options, such as the generic font option, expect a font name. GBrowse provides a small set of fixed-width fonts provided by the [GD library package], named "gdTinyFont","gdSmallFont", "gdMediumBoldFont","gdLargeFont" and "gdGiantFont". They are all shown together in Figure 4.

If not specified, most glyphs default to "gdSmallFont". Figure 5 shows the effect of changing the font to "gdLargeFont" and turning on feature labeling, as shown in the example below:

[Demo]
feature = gene
glyph   = generic
font    = gdGiantFont
bgcolor = orange
fgcolor = black
height  = 9
key     = Demo track using the "giant" font
Figure 5: Changing the font


Screen Measurements

All dimensions, such as height and margins, are given in pixel coordinates:

height = 12

No other measurement types, such as points, centimeters or ems are recognized.

Commonly-Used Glyphs and their Configuration Options

Ths section describes each of the common glyphs, shows a sample configuration stanza, and lists its options and possible values.

The generic Glyph

Figure 6: The generic glyph with all the trimmings
The generic glyph is the basis for all other glyphs and is the default if the glyph option is not explicitly stated. The following is a representative track stanza that uses several of generic's possible options:
[Demo]
feature     = gene
glyph       = generic
font        = gdSmallFont
bgcolor     = orange
fgcolor     = black
linewidth   = 2
height      = 9
stranded    = 1
label       = 1
connector   = solid
description = sub {my $feature    = shift;
                   my @gene_names = $feature->get_tag_values('gene');
		   return "Gene @gene_names";
		   }
link        = http://www.google.com/search?q=$name
key         = Demo track using the "generic" glyph

The result is shown in Figure 6. This example illustrates a pair of advanced features described in the GBrowse 2.0 HOWTO. The first advanced feature is the link option, which specifies where to link to when the user clicks on the feature. The example specifies "http://www.google.com/search?q=$name". When GBrowse renders the page, $name will be replaced with the name of the feature as specified in the underlying database.

A more complex example is the description option, which controls the optional text printed below the feature, is a Perl subroutine callback. It retrieves the feature from the subroutine parameter list (using the "shift" operator) and stores it into a variable named "$feature". It then calls the feature's get_tag_values() method to retrieve descriptive tags of type "gene", here used to store the common gene name. The gene names are stored into an array named "@gene_names." Lastly, the subroutine returns a string consisting of the word "Gene" followed by the list of gene names.

The full list of options recognized by generic and all descendent glyphs is given in the following table:

All the options recognized by "generic" and descendents
Name Description Default Value
key Description of the track in the tracks table. same as the stanza label
category The category of the track in the tracks table. You may use the format "category1:category2:category3" to specify subcategories. Uncategorized tracks will be placed in a hold-all named "General"