Bio::Graphics::Glyph::ideogram - The "ideogram" glyph

Author

       Gudmundur A. Thorisson <mummi@cshl.edu>

       Copyright (c) 2001-2006 Cold Spring Harbor Laboratory

Bugs

       Please report them.

Contributors

       Sheldon McKay <mckays@cshl.edu<gt>

       This library is free software; you can redistribute it and/or modify it under the same terms as Perl
       itself.  See DISCLAIMER.txt for disclaimers of warranty.

perl v5.30.0                                       2019-11-25                Bio::Graphics::Glyph::ideogram(3pm)

Description

This glyph draws a section of a chromosome ideogram. It relies on certain data from the feature to
determine which color should be used (stain) and whether the segment is a telomere or centromere or a
regular cytoband. The centromeres and 'var'-marked bands are rendered with diagonal black-on-white
patterns if the "-patterns" option is true, otherwise they are rendered in dark gray. This is to prevent
a libgd2 crash on certain 64-bit platforms when rendering patterned images.

The cytobandband features would typically be formatted like this in GFF3:

...
ChrX UCSC cytoband 136700001 139000000 . . . Parent=ChrX;Name=Xq27.1;Alias=ChrXq27.1;stain=gpos75;
ChrX UCSC cytoband 139000001 140700000 . . . Parent=ChrX;Name=Xq27.2;Alias=ChrXq27.2;stain=gneg;
ChrX UCSC cytoband 140700001 145800000 . . . Parent=ChrX;Name=Xq27.3;Alias=ChrXq27.3;stain=gpos100;
ChrX UCSC cytoband 145800001 153692391 . . . Parent=ChrX;Name=Xq28;Alias=ChrXq28;stain=gneg;
ChrY UCSC cytoband 1 1300000 . . . Parent=ChrY;Name=Yp11.32;Alias=ChrYp11.32;stain=gneg;

which in this case is a GFF-ized cytoband coordinate file from UCSC:

http://hgdownload.cse.ucsc.edu/goldenPath/hg16/database/cytoBand.txt.gz

and the corresponding GBrowse config options would be like this to
create an ideogram overview track for the whole chromosome:

The 'chromosome' feature below would aggregated from bands and centromere using the default
chromosome aggregator

[CYT:overview]
feature = chromosome
glyph = ideogram
fgcolor = black
bgcolor = gneg:white gpos25:silver gpos50:gray
gpos:gray gpos75:darkgray gpos100:black acen:cen gvar:var
arcradius = 6
height = 25
bump = 0
label = 0

A script to reformat UCSC annotations to GFF3 format can be found at
the end of this documentation.

OPTIONS
The following options are standard among all Glyphs. See Bio::Graphics::Glyph for a full explanation.

Option Description Default
------ ----------- -------

-fgcolor Foreground color black

-outlinecolor Synonym for -fgcolor

-linewidth Line width 1

-height Height of glyph 10

-font Glyph font gdSmallFont

-connector Connector type 0 (false)

-connector_color
Connector color black

-label Whether to draw a label 0 (false)

-description Whether to draw a description 0 (false)

The following options are specific to the ideogram glyph.

Option Description Default
------ ----------- -------

-bgcolor Band coloring string none

-bgfallback Coloring to use when no bands yellow
are present

-bgcolor is used to map each chromosome band's "stain" attribute into a color or pattern. It is a string
that looks like this:

gneg:white gpos25:silver gpos50:gray \
gpos:gray gpos75:darkgray gpos100:black acen:cen gvar:var

This is saying to use "white" for features whose stain attribute is "gneg", "silver" for those whose
stain attribute is "gpos25", and so on. Several special values are recognized: "stalk" draws a narrower
gray region and is usually used to indicate an acrocentric stalk. "var" creates a diagonal black-on-white
pattern. "cen" draws a centromere.

If -bgcolor is just a color name, like "yellow", the glyph will ignore all bands and just draw a filled
in chromosome.

If -bgfallback is set to a color name or value, then the glyph will fall back to the indicated background
color if the chromosome contains no bands.

Name

       Bio::Graphics::Glyph::ideogram - The "ideogram" glyph

Synopsis

         See L<Bio::Graphics::Panel> and L<Bio::Graphics::Glyph>.

Ucsc To Gff Conversion Script

       The following short script can be used to convert a UCSC cytoband annotation file into GFF format.  If
       you have the lynx web-browser installed you can call it like this in order to download and convert the
       data in a single operation:

         fetchideogram.pl http://hgdownload.cse.ucsc.edu/goldenPath/hg18/database/cytoBand.txt.gz

       Otherwise you will need to download the file first. Note the difference between this script and input
       data from previous versions of ideogram.pm: UCSC annotations are used in place of NCBI annotations.

       #!/usr/bin/perl

       use strict; my %stains; my %centros; my %chrom_ends;

       foreach (@ARGV) {
           if (/^(ftp|http|https):/) {      $_ = "lynx --dump $_ |gunzip -c|";
           } elsif (/\.gz$/) {      $_ = "gunzip -c $_ |";
           }
           print STDERR "Processing $_\n"; }

       print "##gff-version 3\n"; while(<>) {
           chomp;
           my($chr,$start,$stop,$band,$stain) = split /\t/;
           $start++;
           $chr = ucfirst($chr);
           if(!(exists($chrom_ends{$chr})) || $chrom_ends{$chr} < $stop)
           {      $chrom_ends{$chr} = $stop;
           }
           my ($arm) = $band =~ /(p|q)\d+/;
           $stains{$stain} = 1;
           if ($stain eq 'acen')
           {      $centros{$chr}->{$arm}->{start} = $stop;      $centros{$chr}->{$arm}->{stop} = $start;
            next;
           }
           $chr =~ s/chr//i;
           print
       qq/$chr\tUCSC\tcytoband\t$start\t$stop\t.\t.\t.\tParent=$chr;Name=$chr;Alias=$chr$band;stain=$stain;\n/;
       }

       foreach my $chr(sort keys %chrom_ends) {
           my $chr_orig = $chr;
           $chr =~ s/chr//i;
           print
       qq/$chr\tUCSC\tcentromere\t$centros{$chr_orig}->{p}->{stop}\t$centros{$chr_orig}->{q}->{start}\t.\t+\t.\tParent=$chr;Name=$chr\_cent\n/;
       }