Bio::Phylo::Treedrawer(3)

NAME
Bio::Phylo::Treedrawer - Visualizer of tree shapes

SYNOPSIS
 use Bio::Phylo::IO 'parse';
 use Bio::Phylo::Treedrawer;

 my $string = '((A:1,B:2)n1:3,C:4)n2:0;';
 my $tree = parse( -format => 'newick', -string => $string )->first;

 my $treedrawer = Bio::Phylo::Treedrawer->new(
    -width  => 800,
    -height => 600,
    -shape  => 'CURVY', # curvogram
    -mode   => 'PHYLO', # phylogram
    -format => 'SVG'
 );

 $treedrawer->set_scale_options(
    -width => '100%',
    -major => '10%', # major cross hatch interval
    -minor => '2%',  # minor cross hatch interval
    -label => 'MYA',
 );

 $treedrawer->set_tree($tree);
 print $treedrawer->draw;

DESCRIPTION
This module prepares a tree object for drawing (calculating coordinates for nodes) and calls the appropriate format-specific drawer.

METHODS

  CONSTRUCTOR

new()
    Treedrawer constructor.

     Type    : Constructor
     Title   : new
     Usage   : my $treedrawer = Bio::Phylo::Treedrawer->new(
                   %args
               );
     Function: Initializes a Bio::Phylo::Treedrawer object.
     Alias   :
     Returns : A Bio::Phylo::Treedrawer object.
     Args    : none.

  MUTATORS

set_format()
    Sets image format.

     Type    : Mutator
     Title   : set_format
     Usage   : $treedrawer->set_format('Svg');
     Function: Sets the drawer submodule.
     Returns :
     Args    : Name of an image format

set_width()
    Sets image width.

     Type    : Mutator
     Title   : set_width
     Usage   : $treedrawer->set_width(1000);
     Function: sets the width of the drawer canvas.
     Returns :
     Args    : Integer width in pixels.

set_height()
    Sets image height.

     Type    : Mutator
     Title   : set_height
     Usage   : $treedrawer->set_height(1000);
     Function: sets the height of the canvas.
     Returns :
     Args    : Integer height in pixels.

set_mode()
    Sets tree drawing mode.

     Type    : Mutator
     Title   : set_mode
     Usage   : $treedrawer->set_mode('clado');
     Function: Sets the tree mode, i.e. cladogram
               or phylogram.
     Returns : Invocant.
     Args    : String, [clado|phylo]

set_shape()
    Sets tree drawing shape.

     Type    : Mutator
     Title   : set_shape
     Usage   : $treedrawer->set_shape('rect');
     Function: Sets the tree shape, i.e.
               rectangular, diagonal, curvy or radial.
     Returns : Invocant.
     Args    : String, [rect|diag|curvy|radial]

set_padding()
    Sets image padding.

     Type    : Mutator
     Title   : set_padding
     Usage   : $treedrawer->set_padding(100);
     Function: Sets the canvas padding.
     Returns :
     Args    : Integer value in pixels.

set_text_horiz_offset()
    Sets text horizontal offset.

     Type    : Mutator
     Title   : set_text_horiz_offset
     Usage   : $treedrawer->set_text_horiz_offset(5);
     Function: Sets the distance between
               tips and text, in pixels.
     Returns :
     Args    : Integer value in pixels.

set_text_vert_offset()
    Sets text vertical offset.

     Type    : Mutator
     Title   : set_text_vert_offset
     Usage   : $treedrawer->set_text_vert_offset(3);
     Function: Sets the text baseline
               relative to the tips, in pixels.
     Returns :
     Args    : Integer value in pixels.

set_text_width()
    Sets text width.

     Type    : Mutator
     Title   : set_text_width
     Usage   : $treedrawer->set_text_width(150);
     Function: Sets the canvas width for
               terminal taxon names.
     Returns :
     Args    : Integer value in pixels.

set_tree()
    Sets tree to draw.

     Type    : Mutator
     Title   : set_tree
     Usage   : $treedrawer->set_tree($tree);
     Function: Sets the Bio::Phylo::Forest::Tree
               object to unparse.
     Returns :
     Args    : A Bio::Phylo::Forest::Tree object.

set_scale_options()
    Sets time scale options.

     Type    : Mutator
     Title   : set_scale_options
     Usage   : $treedrawer->set_scale_options(
                    -width   => 400,
                    -major   => '10%', # major cross hatch interval
                    -minor   => '2%',  # minor cross hatch interval
                    -blocks  => '10%', # alternating blocks in light-gray
                    -label   => 'MYA',
                    -reverse => 1, # tips are 0
                    -tmpl    => '%d', # sprintf template for major cross hatch numbers
                    -font    => {
                       -face => 'Verdana',
                       -size => 11,
                    }
                );
     Function: Sets the options for time (distance) scale
     Returns :
     Args    :
            -width   => 400,
            -major   => '10%', # major cross hatch interval
            -minor   => '2%',  # minor cross hatch interval
            -blocks  => '10%', # alternating blocks in light-gray
            -label   => 'MYA',
            -reverse => 1, # tips are 0
            -tmpl    => '%d', # sprintf template for major cross hatch numbers
            -font    => {
               -face => 'Verdana',
               -size => 11,
            }

set_pie_colors
    Sets a hash reference whose keys are (unique) names for the different segments in a likelihood pie chart, and whose values are color codes.

     Type    : Mutator
     Title   : set_pie_colors
     Usage   : $treedrawer->set_pie_colors({ 'p1' => 'red', 'p2' => 'blue' });
     Function: sets likelihood pie colors
     Returns :
     Args    : HASH

  CASCADING MUTATORS

set_branch_width()
    Sets branch width.

     Type    : Mutator
     Title   : set_branch_width
     Usage   : $treedrawer->set_branch_width(1);
     Function: sets the width of branch lines
     Returns :
     Args    : Integer width in pixels.

set_node_radius()
    Sets node radius.

     Type    : Mutator
     Title   : set_node_radius
     Usage   : $treedrawer->set_node_radius(20);
     Function: Sets the node radius in pixels.
     Returns :
     Args    : Integer value in pixels.

set_collapsed_clade_width()
    Sets collapsed clade width.

     Type    : Mutator
     Title   : set_collapsed_clade_width
     Usage   : $treedrawer->set_collapsed_clade_width(6);
     Function: sets the width of collapsed clade triangles relative to uncollapsed tips
     Returns :
     Args    : Positive number

set_clade_label_width
    Sets clade label width, i.e. the spacing between nested clade annotations

     Type    : Mutator
     Title   : set_clade_label_width
     Usage   : $treedrawer->set_clade_label_width(6);
     Function: sets the spacing between nested clade annotations
     Returns :
     Args    : Positive number

set_tip_radius()
    Sets tip radius.

     Type    : Mutator
     Title   : set_tip_radius
     Usage   : $treedrawer->set_tip_radius(20);
     Function: Sets the tip radius in pixels.
     Returns :
     Args    : Integer value in pixels.

  ACCESSORS

get_format()
    Gets image format.

     Type    : Accessor
     Title   : get_format
     Usage   : my $format = $treedrawer->get_format;
     Function: Gets the image format.
     Returns :
     Args    : None.

get_format_mime()
    Gets image format as MIME type.

     Type    : Accessor
     Title   : get_format_mime
     Usage   : print "Content-type: ", $treedrawer->get_format_mime, "\n\n";
     Function: Gets the image format as MIME type.
     Returns :
     Args    : None.

get_width()
    Gets image width.

     Type    : Accessor
     Title   : get_width
     Usage   : my $width = $treedrawer->get_width;
     Function: Gets the width of the drawer canvas.
     Returns :
     Args    : None.

get_height()
    Gets image height.

     Type    : Accessor
     Title   : get_height
     Usage   : my $height = $treedrawer->get_height;
     Function: Gets the height of the canvas.
     Returns :
     Args    : None.

get_mode()
    Gets tree drawing mode.

     Type    : Accessor
     Title   : get_mode
     Usage   : my $mode = $treedrawer->get_mode('clado');
     Function: Gets the tree mode, i.e. cladogram or phylogram.
     Returns :
     Args    : None.

get_shape()
    Gets tree drawing shape.

     Type    : Accessor
     Title   : get_shape
     Usage   : my $shape = $treedrawer->get_shape;
     Function: Gets the tree shape, i.e. rectangular,
               diagonal, curvy or radial.
     Returns :
     Args    : None.

get_padding()
    Gets image padding.

     Type    : Accessor
     Title   : get_padding
     Usage   : my $padding = $treedrawer->get_padding;
     Function: Gets the canvas padding.
     Returns :
     Args    : None.

get_text_horiz_offset()
    Gets text horizontal offset.

     Type    : Accessor
     Title   : get_text_horiz_offset
     Usage   : my $text_horiz_offset =
               $treedrawer->get_text_horiz_offset;
     Function: Gets the distance between
               tips and text, in pixels.
     Returns : SCALAR
     Args    : None.

get_text_vert_offset()
    Gets text vertical offset.

     Type    : Accessor
     Title   : get_text_vert_offset
     Usage   : my $text_vert_offset =
               $treedrawer->get_text_vert_offset;
     Function: Gets the text baseline relative
               to the tips, in pixels.
     Returns :
     Args    : None.

get_text_width()
    Gets text width.

     Type    : Accessor
     Title   : get_text_width
     Usage   : my $textwidth =
               $treedrawer->get_text_width;
     Function: Returns the canvas width
               for terminal taxon names.
     Returns :
     Args    : None.

get_tree()
    Gets tree to draw.

     Type    : Accessor
     Title   : get_tree
     Usage   : my $tree = $treedrawer->get_tree;
     Function: Returns the Bio::Phylo::Forest::Tree
               object to unparse.
     Returns : A Bio::Phylo::Forest::Tree object.
     Args    : None.

get_scale_options()
    Gets time scale option.

     Type    : Accessor
     Title   : get_scale_options
     Usage   : my %options = %{
                   $treedrawer->get_scale_options
               };
     Function: Returns the time/distance
               scale options.
     Returns : A hash ref.
     Args    : None.

get_pie_colors
    Gets a hash reference whose keys are (unique) names for the different segments in a likelihood pie chart, and whose values are color codes.

     Type    : Accessor
     Title   : get_pie_colors
     Usage   : my %h = %{ $treedrawer->get_pie_colors() };
     Function: gets likelihood pie colors
     Returns :
     Args    : None

get_clade_label_width
    Gets clade label width, i.e. the spacing between nested clade annotations

     Type    : Mutator
     Title   : get_clade_label_width
     Usage   : my $width = $treedrawer->get_clade_label_width();
     Function: gets the spacing between nested clade annotations
     Returns :
     Args    : None

  CASCADING ACCESSORS

get_branch_width()
    Gets branch width.

     Type    : Accessor
     Title   : get_branch_width
     Usage   : my $w = $treedrawer->get_branch_width();
     Function: gets the width of branch lines
     Returns :
     Args    : Integer width in pixels.

get_collapsed_clade_width()
    Gets collapsed clade width.

     Type    : Mutator
     Title   : get_collapsed_clade_width
     Usage   : $w = $treedrawer->get_collapsed_clade_width();
     Function: gets the width of collapsed clade triangles relative to uncollapsed tips
     Returns : Positive number
     Args    : None

get_node_radius()
    Gets node radius.

     Type    : Accessor
     Title   : get_node_radius
     Usage   : my $node_radius = $treedrawer->get_node_radius;
     Function: Gets the node radius in pixels.
     Returns : SCALAR
     Args    : None.

get_tip_radius()
    Gets tip radius.

     Type    : Accessor
     Title   : get_tip_radius
     Usage   : my $tip_radius = $treedrawer->get_tip_radius;
     Function: Gets the tip radius in pixels.
     Returns : SCALAR
     Args    : None.

  TREE DRAWING

draw()
    Creates tree drawing.

     Type    : Unparsers
     Title   : draw
     Usage   : my $drawing = $treedrawer->draw;
     Function: Unparses a Bio::Phylo::Forest::Tree
               object into a drawing.
     Returns : SCALAR
     Args    :

render()
    Renders tree based on pre-computed node coordinates. You would typically use this method if you have passed a Bio::Phylo::Forest::DrawTree on which you have already calculated the node coordinates separately.

     Type    : Unparsers
     Title   : render
     Usage   : my $drawing = $treedrawer->render;
     Function: Unparses a Bio::Phylo::Forest::DrawTree
               object into a drawing.
     Returns : SCALAR
     Args    :

SEE ALSO
There is a mailing list at <https://groups.google.com/forum/#!forum/bio-phylo> for any user or developer questions and discussions.

Bio::Phylo
    The Bio::Phylo::Treedrawer object inherits from the Bio::Phylo object. Look there for more methods applicable to the treedrawer object.

Bio::Phylo::Manual
    Also see the manual: Bio::Phylo::Manual and <http://rutgervos.blogspot.com>.

CITATION
If you use Bio::Phylo in published research, please cite it:

Rutger A Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase Miller, 2011. Bio::Phylo - phyloinformatic analysis using Perl. BMC Bioinformatics 12:63. <http://dx.doi.org/10.1186/1471-2105-12-63>