gbrowse_karyotype help

# gbrowse_karyotype

# TABLE OF CONTENTS

- gbrowse_karyotype
- TABLE OF CONTENTS
- Using the URL query string interface
- URL structure
- Summary of CGI arguments
- Detailed CGI Arguments
  - Adding third-party annotations
  - The featuretext option
    - Configuration sections
      - Colors
      - Glyphs
    - The Reference Line
    - The Data Lines
    - The featuretext option can also contain GFF
    - Comments
- Browser customization and configuration
  - The base configuration file
  - The data source configuration file
  - gbrowse_karyotype as an interactive browser
- How to obtain and use cytoband data
  - Format and graphical rendering of chromosome bands
    - Stains and background colors
    - Tips, stalks, and centromeres
  - Sample GFF data
  - Sample Data Extraction script
  - Options for server-side storage of chromosome band data
    - In a relational database
    - As a flat file
- Other usage examples:
  - Using non-standard cytoband features: Human gene density plot
    - Sample GFF data
    - Configuration file
    - URL
  - Loading chromosome band data remotely
    - CGI arguments
    - GET vs. POST method
- SEE ALSO:
- BUGS
- AUTHOR

# Using the URL query string interface

Using gbrowse_karyotype to draw a karyotype in a web page is as simple as creating an <img> or <iframe> element that uses the URL for the CGI script as the src attribute.

For example, an <img> element like this:

    <img src="/cgi-bin/gbrowse_karyotype?src=Homo_sapiens">

    Will generate this image:

gbrowse_karyotype can also be used to generate image-mapped HTML either on its own or as the contents of an <iframe> element.
For example (the URL parameters are described below):

    <iframe height=300 width=150 frameborder=0 scrolling=no

     src="/cgi-bin/gbrowse_karyoype?src=Homo_sapiens;e=1;c=1+2+3;h=250">

    </iframe>

yields the image below. The chromosome bands now have mousover labels:

The script can also be used to superimpose external features onto the display. If we add the following argument to the above iframe example:

      a=1+gene+gene1+50000000..5100000+bgcolor=red;a=1+gene+gene1+61000000..6300000+bgcolor=blue

# URL structure

http://mckay.cshl.edu/cgi-bin/Homo_sapiens?e=1;b=1;a=1+gene+gene1+2000..10000

- base URL -- the location of the gbrowse_karyotype script
- data source -- the name of the optional data source. This can specified as part of the URL path (as shown) or as a CGI argument, eg "src=Homo_sapiens".
- CGI arguments -- these are always '=' separated key value pairs. For aguments that require multiple parts (see below), the parts are separated by white-space*.

*Note: white-space and other non-word characters must be URL-escaped if passed as CGI arguments using the GET method. This is explained in more detail below.

# Summary of CGI arguments

The script recognizes the following CGI arguments. Argument pairs must be separated by semicolons or by ampersands.
Most options have shorter aliases that can be used to reduce URL lengths. Default values for each of the options in bold
face can also be specified in the configuration file for the data source, if one is used.

Argument | Alias | Description
--- | --- | ---
type | t | built-in tracks to include in image
rows | r | number of rows of chromosomes to draw
chromosome | c | which chromosome(s) to draw
style | s | style information for added features
add | a | added feature(s) to superimpose on the image
embed | e | generate full HTML for image and imagemap for use in an embedded frame
transparent | tr | make the image background color transparent
cwidth | w | chromsome width
cheight | h | maximum chromosome height
bandlabels | b | label chromosome bands
band | ba | the type of feature to be used as chromosome bands or centromeres
list | l | get certain types of configuration information
source | src | database name
useform | f | print a data entry form if there are no other CGI parameters.
featuretext | ft | enter third-party annotations as Bio::Graphics::FeatureFile-style text.

# Detailed CGI Arguments

type (Alias: t)

  This argument applies only to configured data sources on the web server (see configuration below). The 'type' option lists the feature types to display with the karyotype. The value of this argument is a list of track names separated by spaces ("+" characters when URL-escaped). For example:

       <img src="/cgi-bin/gbrowse_karyotype?src=rat;type=gene+allele">

  Multiple type= arguments will be combined to form a single space-delimited list. The alias "t" can be used to shorten the length of the URL.

  If the track name has a space in it, put quotes around the name:

       type="microbe tRNA"+NG+WABA+CG+ESTB

  Available track names can be listed by calling the gbrowse_karyotype script with the option "list=types",

       /cgi-bin/gbrowse_karyotype/sourcename?list=types or /cgi-bin/gbrowse_karyotype?src=sourcename;list=types

chromome (Alias: c)
  Number and order of chromosomes to draw. The default is to draw all chromosomes. Multiple chromosomes can be specified in a space-delimited list ("+" characters when URL-escaped). For example c=1+2+3+4 will draw chromosomes 1-4. If drawing a genome for which there is no data source or configuration file on the server, specify the length of each chromosome in addition to the name.

            c=1:250000000+2:200000000+3:180000000

rows (Alias: r)
  The number or rows to arrange the chromosomes in. The default behavior is to automatically adjust the number of rows to keep the image less than or equal to 1024 pixels in width.
cwidth (Alias: w) Width of the chromosomes, in pixels. The default value is 20px.
cheight (Alias: h)
  Height of the largest chromosome, in pixels. This option affects the overall image height. Chromosome lengths are scaled by their size in bp. The default is 500 px.
arcradius (Alias: ar)
  The radius of the round part of the telomere in pixels. The default value is calculated as 1/100 of the maximum chromosome length.
transparent (Alias: tr)
  The "transparent" option is used to determine whether the karyotype image uses either a white or transparent background. Defining the "transparent" parameter will cause the image to appear to have whatever background color is used by the parent web page.
style (Alias: a)
  The style argument can be used to control the default rendering of features added via the "add" option.
  It is a flattened version of the style configuration sections described in this document
  For example, if you have added a "Blast Hit" annotation, then you can tell the renderer to use a red bar for this glyph in this way:

       style="Blast Hit"+glyph=generic+bgcolor=red

  Note: The 'style' parameter controls how all features of a specified type are rendered. The general style directives can be overriden for individual features via the 'add' option described below.
  Note2: For large numbers of added features or complex configuration, see the featuretext option.

  ## Adding third-party annotations

add (Alias: a)
  This option is used to add one or more additional features to the karyotype, for example, genes, blast hits, etc. Features are specified as space ("+") delimited lists in the following format:

          add=chr2+Type+Name+start..end,start2..end2+bgcolor=green+glyph=dot+desc='my+favorite+gene'

  - "ref" is the name of the reference sequence
  - "type" link the feature to a style definition (see "style" below), if used
  - "name" is the unique feature name or identifier. It will be used a a mousover label if the 'embed' option is selected and there is no description. Names that contain white space must be quoted, for example "BLAST hit".
  - "coordinates" is a range in the format start..end. Multiple ranges can be used as a comma-separated list (eg: start..end,start2..end2,start3..end3). Negative strand features can be specified by inverting the start and end coordinates.
  - Other fields can optionally be appended after the coordinates to control how the feature is drawn.
  Free-form text will be interpreted as a description, for example:

       add=I+"curated+gene"+act-2+23897..28799+"C.+elegans+actin+gene"

  "key=value" pairs will be added to the feature's attributes. Certain reserved keywords will override any default style for that feature type.

  reserved keywords
  glyph | the type of glyph used to represent the feature (eg: 'dot', 'diamond', 'triangle')
  fgcolor | glyph foreground (outline) color
  bgcolor | glyph background (fill) color
  orient | cardinal direction that glyph points in; N, S, E, W
  url (alias 'link') | URL destination if the feature is clicked (see Note below)
  desc (alias 'description') | feature description. This will be used as a mousover label.

  Note: URLs that contain special characters such as '&', ';', '~', etc must be URL escaped in order to be parsed properly. Allowed special characters and their ASCII escape codes are listed below. URLs containing special characters that are not on this list are not allowed.

  character | escape code | character | escape code
  --- | --- | --- | ---
  # | %23 | ~ | %7E
  / | %2F | ? | %3F
  : | %3A | @ | %40
  = | %3D | & | %26
  ; | %3B |  |

list (Alias l)
  If this argument is present, it will cause the script to dump out various types of information in plain text form. Currently the two values for this argument are sources, to dump out the list of data sources, and types, to dump out the list of configured types. For list=sources, the script will return a simple text list of the data source names. For list=types, the script will return a three-column tab-delimited list giving the track names and feature types corresponding to the currently-selected data source. The format is as follows:

       Mnemonic <tab> Full description of feature <tab> [default]

  The third column contains the word "default" if the track will be shown by default when no type argument is provided.
source (Alias src)
  This argument specifies the database for the images. The list of sources can be found using list=sources.
embed (Alias: e)
  Generate image and a corresponding HTML imagemap in a form suitable for embedding into a frame.
  The default behavior for gbrowse_karyotype is to output binary image data. To embed an image in your web page with maousover effects, etc, use the embed=1 options and call the script via an <iframe> element. For example, the clickable image below is generated via an iframe element with this format:

      <iframe src="/cgi-bin/gbrowse_karyotype?c=1+2+3;h=350;src=mouse;e=1;a=2+gene+gene1+1000000..1010000+bgcolor=red+url=http://www.google.com" width="150" height="350"></iframe>

  Mouseover or click the triangle

useform (Alias f)
  If gbrowse_karyotype is being used as an interactive browser, define this option either as a CGI parameter or in the configuration file. If this option is set in the configuration file, the form will be printed when the script is called with no CGI parameters. If used as a CGI parameter, the form will be printed if there are no other CGI parameters.

## The featuretext option

featuretext (Alias ft)
To submit large numbers of features or more complex annotation data, it may be preferable to use this option and the POST method rather than the 'add' and 'style' methods. The format of the text, which would be placed within a <textarea> element, follows the Bio::Graphics::FeatureFile format, an example of which is shown below:

    ## Default display options for gene ##
    [gene]
    glyph   = triangle
    bgcolor = red
    fgcolor = red
    height  = 7
    bump    = 1

    [mutation]
    glyph   = lightning
    bgcolor = yellow
    fgcolor = black
    height  = 15

    # chromosome 1
    reference=1
    gene gene1 20000001..20006000 "Carbonic Anhydrase gene"
    gene gene2 20066001..20069000 "ADH gene"
    gene gene3 50000001..50006000 bgcolor=blue;fgcolor=blue;glyph=dot;description="Unknown gene"

    # chromosome 5
    reference=5
    gene gene4 20000001..20006000 bgcolor=white
    gene gene5 30006001..30009000
    gene gene6 80000001..80006000
    mutation allele2 30006001..30009000 "cosmic radiation damage"

The components of the annotation/config text (configuration sections, reference lines and data lines) are discussed in detail below:

### Configuration sections

The appearance of third-party annotations can be controlled by including one or more configuration stanzas in the annotation file.

Here is an example configuration section. It can appear at the top of the file, at the bottom, or interspersed among data sections:

>     [gene]

>     glyph   = triangle

>     orient  = E

>     bgcolor = red

>     fgcolor = red

>     height  = 7

>     bump    = 1

The configuration section is divided into a set of sections, each one labeled with a [section title]. The [general] section specifies global options for the entire image. Other sections apply to particular feature types.

Inside each section is a series of name=value pairs, where the name is the name of an option to set. You can put whitespace around the = sign to make it more readable, or even use a colon (:) instead if you prefer. The following option names are recognized:

Option | Value | Example
--- | --- | ---
bgcolor | Background color of each element | blue
bump | Prevent features from colliding (0=no, 1=yes; default 1) | 1
fgcolor | Foreground color of each element | yellow
glyph | Style of each graphical element (see list below) | triangle
width | Width of each graphical element (pixels) | 10
linewidth | Width of lines (pixels) | 1
orient | Direction in which triangle and lightning glyphs point (N, S, E, W; default E) | E
point | Place an unscaled glyph in the center of the range. (0=no, 1=yes; default 1) | 1

The bump option is the most important option for controlling the look of the image. If set to false (the number 0), then the features are allowed to overlap. If set to true (the number 1), then the features will movehorizontally to avoid colliding. If not specified, bump is turned on if the number of any given type of sequence feature is greater than 50.

Remote annotation files do not support callbacks (code references) as values in the attribute:value pairs.

#### Colors

Colors are English-language color names or Web-style #RRGGBB colors (see any book on HTML for an explanation). The following colors are recognized:

white | coral | darkslateblue | green | lightpink | mediumslateblue | paleturquoise | sienna
black | cornflowerblue | darkslategray | greenyellow | lightsalmon | mediumspringgreen | palevioletred | silver
aliceblue | cornsilk | darkturquoise | honeydew | lightseagreen | mediumturquoise | papayawhip | skyblue
antiquewhite | crimson | darkviolet | hotpink | lightskyblue | mediumvioletred | peachpuff | slateblue
aqua | cyan | deeppink | indianred | lightslategray | midnightblue | peru | slategray
aquamarine | darkblue | deepskyblue | indigo | lightsteelblue | mintcream | pink | snow
azure | darkcyan | dimgray | ivory | lightyellow | mistyrose | plum | springgreen
beige | darkgoldenrod | dodgerblue | khaki | lime | moccasin | powderblue | steelblue
bisque | darkgray | firebrick | lavender | limegreen | navajowhite | purple | tan
blanchedalmond | darkgreen | floralwhite | lavenderblush | linen | navy | red | teal
blue | darkkhaki | forestgreen | lawngreen | magenta | oldlace | rosybrown | thistle
blueviolet | darkmagenta | fuchsia | lemonchiffon | maroon | olive | royalblue | tomato
brown | darkolivegreen | gainsboro | lightblue | mediumaquamarine | olivedrab | saddlebrown | turquoise
burlywood | darkorange | ghostwhite | lightcoral | mediumblue | orange | salmon | violet
cadetblue | darkorchid | gold | lightcyan | mediumorchid | orangered | sandybrown | wheat
chartreuse | darkred | goldenrod | lightgoldenrodyellow | mediumpurple | orchid | seagreen | whitesmoke
chocolate | darksalmon | gray | lightgreen | mediumseagreen | palegoldenrod | seashell | yellow
coral | darkseagreen | green | lightgrey | mediumslateblue | palegreen | sienna | yellowgreen

#### Glyphs

The option controls how the features are rendered. There are dozens of glyphs available but not all are suitable for drawing features on a chromosome scale. A comprehensive list of available glyphs can be found on the bioperl website. The following glyphs are recommended for best results:

Name | Descripton
--- | ---
triangle | A triangle; use the 'orient' option (N,S,E or W) to control where it points.
dot | A small circle.
diamond | A diamond shape.
lightning | For those features who do not take themselves too seriously.

### The Reference Line

The annotation file must have at least one reference = landmark name line. This line tells the browser what coordinate system you are using. This would typically be a chromosome name. The word "reference" must be all lower-case. There may or may not be whitespace before and after the "=" sign.

>     reference = 1

You may have several reference lines in the file. Each reference landmark will apply to all data lines located beneath it until the next reference line occurs.

### The Data Lines

The format of the data lines is analogous to that of the 'add' option, except that the reference seuquence is specified only once per group and URL-escaping special characters is not required. Each annotation occupies one or more lines. It contains three to four columns, delimited by tabs or spaces.

Column 1, the feature type
The first column is the feature type. Any description is valid, but a short word, like "knockout" is better than a long one, like "Transposon-mediated knockout". Later on you can provide a long descriptive name in the formatting key if you desire. If the feature type contains white space, you must surround it by double or single quotes.

Column 2, the feature name
This is the name of the feature. The name will be used as a mousover label unless there is a comment (see below). If the name contains white space, you must surround it by white space. Use empty quotes ("") if there is no name to display.

Column 3, the feature position
The third column contains one or more ranges occupied by the feature. A range has a start and a stop, and is expressed either as "start..stop" or "start-stop". Use whichever form you prefer. You can express a feature that occupies a discontinuous set of ranges, such as an mRNA aligned to the genome, by providing a list of ranges separated by commas. Example:
1..10,49..80,110..200

There should be no spaces before or after the commas. If there are, enclose the entire range in quotes. All ranges uses the coordinate system of the most recently declared reference landmark.

Column 4, Description [optional]
This is the description column. If a description exists, it will be used as a mouseover label for the feature, taking precedence over the feature name from column 2. Descriptions that contain whitespace should be wrapped in quotes. The description column can also be used to specify attribute=value information to override track display options for an individual feature. For example, if the features in a track are normally displayed as triangles, adding glyph=diamond to column 4 will draw a diamond in place of a triangle for just this one feature. Multiple attribute=value pairs should be delimited with semicolons. attribute=value pairs and text descriptions can be mixed by prepending a "decription=" to the text. For example:

     gene gene1 10001..16000 bgcolor=white;glyph=dot;description="a very special gene"

### The featuretext option can also contain GFF

GFF data will also be parsed correctly from the featuretext data. The GFF can be included anywhere in the text, as long as it is preceded by a '##gff-version' directive.

### Comments

You can place a comment in the annotation file by preceding it with a pound sign (#). Everything following the pound sign is ignored:

>     # this is a comment

# Browser customization and configuration

## The base configuration file

This is an example of Gbrowse_karyotype.conf. It contains basic configuration information for drawing karyotypes when no server-side data source is used. This is formatting information only. All of the data needed to draw the chromosomes must be supplied via CGI parameters.
Note: The base configuration is only used if no data source is specified and no style information is otherwise supplied. These values will be overidden by style information supplied as CGI parameters and/or specific data source configuration files.
Note2: for options that can be used either as CGI parameters or in configuration files, use the long form, rather than the short alias, in the confuguration file.
# default configuration for gbrowse_karyotype

    [GENERAL]
    description = no source

    max segment = 999_999_999_999_999

    # Web site configuration info
    tmpimages   = /gbrowse/tmp
    stylesheet  = /gbrowse/gbrowse.css
    buttons     = /gbrowse/images/buttons

    [karyotype]
    cheight         = 500 # max chromosome height
    cwidth          = 25  # chromosome width
    cytoband_track  = ideogram
    bands           = chromosome_band cytoband centromere
    useform         = 1 # print a data entry form if there are no CGI parameters
    ##################################################################
    # For a customized input form, the following options would be
    # uncommented and filled with HTML code
    ##################################################################
    # This option would contain HTML code for a customized page header
    #header          =
    #
    # This option would contain HTML code for a customized page footer
    #footer          =
    #
    # This option would contain HTML code for a customized input form
    #input_form      =
    ###################################################################

    # Default glyph settings
    [TRACK DEFAULTS]
    glyph       = triangle
    height      = 8
    bgcolor     = black
    fgcolor     = black
    description = 0
    label       = 0
    orient      = E
    point       = 1

    [ideogram]
    glyph       = ideogram
    fgcolor     = black
    bgcolor  = gneg:white gpos25:silver gpos50:gray gpos:gray
                  gpos75:darkgray gpos100:black gvar:var stalk:#666666
    arcradius   = 7
    height      = 20
    bump        = 0

## The data source configuration file

    Example:
    # This is a basic configuration to draw chromosome ideograms for the
    # human genome.  It is a standalone file but could could also be part
    # of a normal gbrowse configuration file.
    [GENERAL]
    description   = human
    db_adaptor    = Bio::DB::GFF
    # this configuration just uses a simple flatfile
    db_args       = -adaptor memory
                    -gff    'usr/local/apache/htdocs/gbrowse/databases/ideograms/human_cytobands.gff'

    # Where temporary images are stored
    tmpimages   = /gbrowse/tmp

    # gbrowse_karyotype-specific configuration
    [karyotype]
    max_height       = 400
    cwidth           = 15
    chromosome       = 1 2 3 4 5 6 7 8 9 10 11 12 13
                       14 15 16 17 18 19 20 21 22 X Y
    rows             = auto
    cytoband_track   = CYT:karyotype
    band_labels      = 1

    # this controls how the chromosomes are drawn
    [CYT:karyotype]
    feature       = cytoband chromosome_band centromere
    glyph         = ideogram
    fgcolor       = black
    bgcolor       = gneg:white gpos25:silver gpos50:gray gpos:gray
                    gpos75:darkgray gpos100:black gvar:var stalk:#666666
    arcradius     = 7
    height        = 21

    # Other built-in feature configuration, if any,  would be added here

## gbrowse_karyotype as an interactive browser

The CGI script can be used as an interactive browser using the useform=1 option.

In the configuration file, a customized data entry form can be specified using the following options:

- The front page for the interactive browser can be almost entirely customized with the following keys in the [karyotype] stanza.

  -      header     = ...

    Page header biolerplate (Visible title, etc.)

  -      input_form = ...

    HTML to replace eveything between the header and footer

  -      footer     = ...

    Page footer

  If the useform option is specified in the configuration file but the above fields are not; reasonable, albeit plain, defaults will be supplied by the CGI script.

This if the default data entry form

-     chromosome = chr1 chr2 chr3

  This entry is required to specify which chromosomes to display and in which order. The space delimited list should contain reference sequences that exist in your database or GFF flat file.

-     cytoband = CYT:karyotype

  This specifies which built-in feature corresponds to the chromosome band data. If there are no band data, blank chromosomes will be drawn. However, a configuration stanza is still necessary to specify default chromosome attributes.

-     feature = cytoband chromosome_band centromere

  List individual feature types (typically chromosome_band and centromere). 'cytoband' is also recognized but it is not a valid SO term. List actual features, not aggregators.

-     glyph  = ideogram

  The ideogram glyph would be most commonly used in combination with cytoband data. An alternative for scored, non cytoband features (for example local gene densites, recombination rates, etc) is the heat_map_ideogram glyph, which can be used to draw chromosomes with color-coded bands representing scores, frequencies etc. The chromosome-like look can be enhanced by including the centromere amongst the scored "bands".

# How to obtain and use cytoband data

The starting point for drawing chromosome ideograms is the cytoband data. These data can be obtained from the UCSC genome browser, from NCBI and from EnsEMBL and other sources such as the primary literature. Once obtained, the cytobands are converted to GFF to be loaded into a Bio::DB::GFF database or saved as a flatfile.

Below is an example of GFF3-format cytoband data. Note that the Parent= tag is used to facilitate aggregation of bands into their parent chromosomes. Preprocessed GFF files for mouse, human and rat can be found in the html (or htdocs) directory at gbrowse/databases/ideogram.

## Format and graphical rendering of chromosome bands

The CGI/config options that specifically control how chromosomes are drawn for configured data sources are shown below:

    [karyotype]
    # This option tells the CGI script which features to interpret as
    # "cytoband" features to be drawn on the chromosome ideograms.
    # The three feature types below are assumed by default but
    # Other types can be used as well.
    bands          = chromosome_band centromere cytoband
    # This is where the names and order of the chromosomes are specified
    chomosome      = 1 2 3 4 5 6
    # This option specifies that band labels should be added
    band_labels    = 1
    # This option species the configuration section that applies to the chromosome ideograms
    cytoband_track = ideogram
    # Largest chromosome height
    cheight        = 500

    # This section provides default style options
    # for the chromosomes.  Note the specially formatted bgcolor (see below)
    [ideogram]
    glyph       = ideogram
    fgcolor     = black
    bgcolor     = gneg:white gpos25:silver gpos50:gray gpos:gray gpos75:darkgray
                  gpos100:black gvar:var stalk:#666666
    arcradius   = 7
    height      = 20
    bump        = 0

### Stains and background colors

The specially formatted bgcolor option is parsed to control band colors individually for each cytoband feature other than the centromere.
each 'stain:color' pair specifies the color to draw each band feature, each of which has a 'stain' attribute associated with it.
The stains can be anything, with the exceptions noted below:

### Tips, stalks, and centromeres

The keyword 'tip' refers to the very top of mouse chromosomes, which are extremely acrocentric. This stain will cause a small, black, rectangular chromosome tip.
The keyword 'stalk' will cause a narrower band that represents the stalk region of human acrocentric chromosomes.
Centromeres are usually specified by type, but the keyword 'acen' will also cause a band to be rendred as a centromere.
The keyword 'gvar' will create a band that has a patterned background color.

## Sample GFF data

      ##gff-version 3
      ##sequence-region 1 1 245522847
      1       ensembl chromosome_band        1       2300000 .       .       .       Parent=1;Name=p36.33;Alias=1p36.33;Stain=gneg
      1       ensembl chromosome_band        2300001 5300000 .       .       .       Parent=1;Name=p36.32;Alias=1p36.32;Stain=gpos25
      1       ensembl chromosome_band        15600001        20200000        .       .       .       Parent=1;Name=p36.13;Alias=1p36.13;Stain=gneg
      1       ensembl centromere      121000001       127900000       .       .       .       Parent=1;Name=1_cent;Alias=11_cent

Note: If a GFF flatfile is being used as the database for chromosome banding data, be sure to have a 'sequence-region' directive for each chromosome.

## Sample Data Extraction script

Ensembl has cytoband data for human, mouse and rat. Below is an example of a script that retrieves cytoband features from the public mysql database and converts them to GFF3.

    #!/usr/bin/perl -w
    use strict;
    use DBI;

    my $database = shift;
    my $host     = 'ensembldb.ensembl.org';
    my $query    =
    'SELECT name,seq_region_start,seq_region_end,band,stain
     FROM seq_region,karyotype
     WHERE seq_region.seq_region_id = karyotype.seq_region_id;';

    my $dbh = DBI->connect( "dbi:mysql:$database:$host", 'anonymous' )
        or die DBI->errstr;

    my $sth = $dbh->prepare($query) or die $dbh->errstr;
    $sth->execute or die $sth->errstr;

    my ($cent_start,$prev_chr,$chr_end,$segments,$gff);
    my $chr_start = 1;
    while (my @band = $sth->fetchrow_array ) {
      my ($chr,$start,$end,$band,$stain) = @band;
      my $class = 'Chromosome';
      my $method;

      $chr =~ s/chr//;
      if ($stain eq 'acen' && !$cent_start) {
        $cent_start = $start;
        next;
      }
      elsif ($cent_start) {
        $method = 'centromere';
        $band   = "$chr\_cent";
        $start  = $cent_start;
        $stain  = '';
        $cent_start = 0;
      }
      else {
        $method = 'chromosome_band'; # SO term
      }

      my $alias = $method =~ /centromere/i ? $band : $chr.$band;
      $gff .= join("\t", $chr, 'ensembl', lc $method, $start, $end,
             qw/. . ./,qq{Parent=$chr;Name=$band;Alias=$alias});
      $gff .= $stain ? ";Stain=$stain\n" : "\n";

      if ($prev_chr && $prev_chr !~ /$chr/) {
        $segments .= "\#\#sequence-region $prev_chr $chr_start $chr_end\n";
        $chr_start = 1;
      }

      $prev_chr = $chr;
      $chr_end  = $end;
    }

    $segments .= "\#\#sequence-region $prev_chr $chr_start $chr_end\n";
    print "##gff-version 3\n";
    print $segments,$gff;

    __END__
    # Currently ideograms for human, rat and mouse are available
    # To see the current database list, try the command:

    mysql -uanonymous -hensembldb.ensembl.org -e 'show databases' \
    | grep core | grep 'sapiens\|rattus\|mus' | grep -v 'expression'

## Options for server-side storage of chromosome band data

### In a relational database

Cytoband data can be stored in a Bio::DB::GFF database just like any other, properly formatted GFF. See the Gbrowse tutorial for more information on database loading and configuration.
Below is an example of hoe the database access would be specified in the data source config file:

    db_adaptor    = Bio::DB::GFF
    db_args       = -dsn dbi:mysql:database=my_database;host=localhost;user=user;password=passwd

### As a flat file

Cytoband data, such as the output of the above example script, can be stored as a GFF file on the webserver's filesystem and parsed into memory at runtime.
A sample configuration is shown below:

    db_adaptor    = Bio::DB::GFF
    db_args       = -adaptor memory
                    -gff '/var/www/html/gbrowse/databases/ideograms/mouse_cytobands.gff'

Ensure that the GFF data in the flatfile is formatted as the
above sample.

# Other usage examples:

## Using non-standard cytoband features: Human gene density plot

The image below is drawn using a Bio::DB::GFF database that specifies gene_density features rather than chromosome_bands. Each gene_density feature (see sample GFF) has a score, which corresponds to the number of genes /megabase.

### Sample GFF data

    ##gff-version 3
    1       calculated      gene_density    1       1000000 35      .       .       Parent=Dense:1
    1       calculated      gene_density    1000001 2000000 45      .       .       Parent=Dense:1
    1       calculated      gene_density    2000001 3000000 18      .       .       Parent=Dense:1
    1       calculated      gene_density    3000001 4000000 21      .       .       Parent=Dense:1
    1       calculated      gene_density    4000001 5000000 1       .       .       Parent=Dense:1
    1       calculated      gene_density    5000001 6000000 1       .       .       Parent=Dense:1
    1       calculated      gene_density    6000001 7000000 21      .       .       Parent=Dense:1
    1       calculated      gene_density    7000001 8000000 12      .       .       Parent=Dense:1
    1       calculated      gene_density    8000001 9000000 18      .       .       Parent=Dense:1
    1       calculated      gene_density    9000001 10000000        20      .       .       Parent=Dense:1
    1       calculated      gene_density    10000001        11000000        18      .       .       Parent=Dense:1
    1       calculated      gene_density    11000001        12000000        28      .       .       Parent=Dense:1
    1       calculated      gene_density    12000001        13000000        25      .       .       Parent=Dense:1
    1       calculated      gene_density    13000001        14000000        10      .       .       Parent=Dense:1
    1       calculated      gene_density    14000001        15000000        3       .       .       Parent=Dense:1
    1       calculated      gene_density    15000001        16000000        27      .       .       Parent=Dense:1
    1       calculated      gene_density    16000001        17000000        45      .       .       Parent=Dense:1
    1       calculated      gene_density    17000001        18000000        15      .       .       Parent=Dense:1
    1       calculated      gene_density    18000001        19000000        6       .       .       Parent=Dense:1
    1       calculated      gene_density    19000001        20000000        23      .       .       Parent=Dense:1
    1       calculated      gene_density    20000001        21000000        20      .       .       Parent=Dense:1
    1       calculated      gene_density    21000001        22000000        14      .       .       Parent=Dense:1
    1       calculated      gene_density    22000001        23000000        17      .       .       Parent=Dense:1
    1       calculated      gene_density    23000001        24000000        27      .       .       Parent=Dense:1

### Configuration file

The file Human_gene_density.conf contains the following text. This configuration uses the heat_map_ideogram glyph, which is like the ideogram glyph but allows bands to have their color calculated based on the score (see GFF above).

    description   = Human gene density
    db_adaptor    = Bio::DB::GFF
    db_args       = -dsn dbi:mysql:database=human;host=localhost;user=nobody

    # Web site configuration info
    tmpimages   = /gbrowse/tmp
    stylesheet  = /gbrowse/gbrowse.css
    buttons     = /gbrowse/images/buttons

    # how long to save cached images
    image cachetime = 2_592_000

    [karyotype]
    cheight         = 500
    cwidth          = 20
    chromosome      = 1 2 3 4 5 6 7 8 9 10 11 12 13
                      14 15 16 17 18 19 20 21 22 X Y
    cytoband_track  = CYT

    [CYT]
    feature       = gene_density centromere
    glyph         = heat_map_ideogram # note the different glyph
    start_color   = white
    end_color     = red
    min_score     = 0
    max_score     = 40
    fgcolor       = black

### URL

Since the configuration and data are on the web server, a very simple url is required:
"http://mckay.cshl.edu/cgi-bin/gbrowse_karyotype/Human_gene_density"

## Loading chromosome band data remotely

It is also possible to draw a whole genome "from scratch" with no server-side data. Chromosome and band data and configuration passed as CGI arguments at runtime.
The following arguments apply (chromosome is the only required option):

### CGI arguments

bands=feature_type1+feature_type2*
chromosome=1:10000000+2:500000 etc (see above for more details)
add=1+chromosome_band+1p23+1..10000000+Stain=gpos50 etc.
*This is only required if features other than the default 'chromosome_band', 'cytoband' and 'centromere' are used.
+Cytoband data are not required. Blank chromosomes will be drawn in their absence.
The chromosome band data can be passed the same way as any other type of feature, via the add or featuretext options.

### GET vs. POST method

If there large numbers of chromosome bands and/or other annotations to be drawn, a very long URL submitted via the GET method may become unwieldy. Consider submitting a form using the featuretext option and the POST method. If you already have the chromosome band data in GFF format, it can simply be appended to the other featuretext data. If each of the chromosomes is specified as a sequence-region directive in the GFF data, then the otherwise requisite 'chromosome' option is not required.

    ##sequence-region chromosome_name start end

The HTML code shown below embeds a complete human chromosome 21 with superimposed features within a web page:

       <form method=POST name="f1" action="/cgi-bin/gbrowse_karyotype_devel" target="iframe1">
        <input type="hidden" name="embed" value=1>
        <input type="hidden" name="band_labels" value=1>
        <input type=submit name="submit" value="Click to display chromosome 21">
        <!-- The textarea is not visible -->
        <div style="width:0px;height:0px;visibility:hidden">
        <textarea name="featuretext" type=hidden>
         ## Configuration
         [gene]
         glyph   = triangle
         bgcolor = red
         fgcolor = red
         height  = 7
         bump    = 1
         point   = 1

         [mutation]
         glyph   = lightning
         bgcolor = yellow
         fgcolor = black
         height  = 15

         # chromosome 1
         reference=21
         gene gene1 20000001..20006000 "Some sort of gene"
         gene gene2 30066001..30069000 bgcolor=white;desc="ADH gene"
         gene gene3 50000001..50006000 bgcolor=blue;fgcolor=blue;glyph=dot;description="Unknown gene"
         gene gene6 40000001..40006000 glyph=dot;bgcolor=white;fgcolor=black;height=15
         mutation allele2 30006001..30009000 link=http://www.nasa.gov;description="cosmic radiation damage"

         # chromosome 21 cytoband data
         ##gff-version 3
         ##sequence-region 21 1 46944323
         21      ensembl chromosome_band 1       2900000 .       .       .       Parent=21;Name=p13;Alias=21p13;Stain=gvar
         21      ensembl chromosome_band 2900001 6300000 .       .       .       Parent=21;Name=p12;Alias=21p12;Stain=stalk
         21      ensembl chromosome_band 6300001 10000000        .       .       .       Parent=21;Name=p11.2;Alias=21p11.2;Stain=gvar
         21      ensembl chromosome_band 13200001        15300000        .       .       .       Parent=21;Name=q11.2;Alias=21q11.2;Stain=gneg
         21      ensembl chromosome_band 15300001        22900000        .       .       .       Parent=21;Name=q21.1;Alias=21q21.1;Stain=gpos100
         21      ensembl chromosome_band 22900001        25800000        .       .       .       Parent=21;Name=q21.2;Alias=21q21.2;Stain=gneg
         21      ensembl chromosome_band 25800001        30500000        .       .       .       Parent=21;Name=q21.3;Alias=21q21.3;Stain=gpos75
         21      ensembl chromosome_band 30500001        34700000        .       .       .       Parent=21;Name=q22.11;Alias=21q22.11;Stain=gneg
         21      ensembl chromosome_band 34700001        36700000        .       .       .       Parent=21;Name=q22.12;Alias=21q22.12;Stain=gpos50
         21      ensembl chromosome_band 36700001        38600000        .       .       .       Parent=21;Name=q22.13;Alias=21q22.13;Stain=gneg
         21      ensembl chromosome_band 38600001        41400000        .       .       .       Parent=21;Name=q22.2;Alias=21q22.2;Stain=gpos50
         21      ensembl chromosome_band 41400001        46944323        .       .       .       Parent=21;Name=q22.3;Alias=21q22.3;Stain=gneg
         21      ensembl centromere      10000001        13200000        .       .       .       Parent=21;Name=21_cent;Alias=21_cent
        </textarea>
       </div>
      </form>

      <!-- The iframe where the image and map will be embedded -->
      <iframe name="iframe1" id="iframe1" height=600 frameborder=0></iframe>

## Configuration [gene] glyph = triangle bgcolor = red fgcolor = red height = 7 bump = 1 point = 1 [mutation] glyph = lightning bgcolor = yellow fgcolor = black height = 15 # chromosome 1 reference=21 gene gene1 20000001..20006000 "Some sort of gene" gene gene2 30066001..30069000 bgcolor=white;desc="ADH gene" gene gene3 50000001..50006000 bgcolor=blue;fgcolor=blue;glyph=dot;description="Unknown gene" gene gene6 40000001..40006000 glyph=dot;bgcolor=white;fgcolor=black;height=15 mutation allele2 30006001..30009000 link=http://www.nasa.gov;description="cosmic radiation damage" # chromosome 21 cytoband data ##gff-version 3 ##sequence-region 21 1 46944323 21 ensembl chromosome_band 1 2900000 . . . Parent=21;Name=p13;Alias=21p13;Stain=gvar 21 ensembl chromosome_band 2900001 6300000 . . . Parent=21;Name=p12;Alias=21p12;Stain=stalk 21 ensembl chromosome_band 6300001 10000000 . . . Parent=21;Name=p11.2;Alias=21p11.2;Stain=gvar 21 ensembl chromosome_band 13200001 15300000 . . . Parent=21;Name=q11.2;Alias=21q11.2;Stain=gneg 21 ensembl chromosome_band 15300001 22900000 . . . Parent=21;Name=q21.1;Alias=21q21.1;Stain=gpos100 21 ensembl chromosome_band 22900001 25800000 . . . Parent=21;Name=q21.2;Alias=21q21.2;Stain=gneg 21 ensembl chromosome_band 25800001 30500000 . . . Parent=21;Name=q21.3;Alias=21q21.3;Stain=gpos75 21 ensembl chromosome_band 30500001 34700000 . . . Parent=21;Name=q22.11;Alias=21q22.11;Stain=gneg 21 ensembl chromosome_band 34700001 36700000 . . . Parent=21;Name=q22.12;Alias=21q22.12;Stain=gpos50 21 ensembl chromosome_band 36700001 38600000 . . . Parent=21;Name=q22.13;Alias=21q22.13;Stain=gneg 21 ensembl chromosome_band 38600001 41400000 . . . Parent=21;Name=q22.2;Alias=21q22.2;Stain=gpos50 21 ensembl chromosome_band 41400001 46944323 . . . Parent=21;Name=q22.3;Alias=21q22.3;Stain=gneg 21 ensembl centromere 10000001 13200000 . . . Parent=21;Name=21_cent;Alias=21_cent

# SEE ALSO:

The gbrowse tutorial
perldoc Bio::Graphics::Glyph::ideogram

# BUGS

Please report them to the author.

# AUTHOR

Sheldon McKay mckays@cshl.edu

Copyright (c) 2006 Cold Spring Harbor Laboratory

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

For additional help, see The GMOD Project pages.