Tree::Cladogram - Render a cladogram using Imager or Image::Magick
Tree::Cladogram
This is scripts/imager.pl:
#!/usr/bin/env perl use strict; use warnings; use Getopt::Long; use Pod::Usage; use Tree::Cladogram::Imager; # Or Tree::Cladogram::ImageMagick. # ---------------------------------------------- my($option_parser) = Getopt::Long::Parser -> new; my(%option); if ($option_parser -> getoptions ( \%option, 'draw_frame=i', 'frame_color=s', 'help', 'input_file=s', 'leaf_font_file=s', 'leaf_font_size=i', 'output_file=s', 'print_tree=i', 'title=s', 'title_font_file=s', 'title_font_size=s', ) ) { pod2usage(1) if ($option{'help'}); exit Tree::Cladogram::Imager -> new(%option) -> run; } else { pod2usage(2); }
See also scripts/image.magick.pl.
As you can see, you create an object and then call "run()".
And this is the heart of scripts/imager.sh:
perl -Ilib scripts/plot.pl \ -debug 0 \ -draw_frame $FRAME \ -input_file data/$i.01.clad \ -leaf_font_file $LEAF_FONT_FILE \ -output_file data/$i.01.png \ -title "$TITLE" \ -title_font_file $TITLE_FONT_FILE
See also scripts/image.magick.sh.
Tree::Cladogram provides a mechanism to turn a tree into a cladogram image. The image is generated using Imager or Image::Magic.
The image type created is determined by the suffix of the output file. See "What image formats are supported?" for details.
The details of the cladogram are read from a text file. See the "FAQ" for details.
For information about cladograms, see https://en.wikipedia.org/wiki/Cladogram.
For another sample of a cladogram, see http://phenomena.nationalgeographic.com/2015/12/11/paleo-profile-the-smoke-hill-bird/.
Sample input is shipped as data/*.clad. The corresponding output is shipped as data/*.png, and is on-line:
wikipedia.01.clad output by Imager
wikipedia.01.clad output by Image::Magick
nationalgeographic.01.clad output by Imager
nationalgeographic.01.clad output by Image::Magick
This module is available as a Unix-style distro (*.tgz).
See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing distros.
Install Tree::Cladogram as you would for any Perl module:
Perl
Run:
cpanm Tree::Cladogram
or run:
sudo cpan Tree::Cladogram
or unpack the distro, and then:
perl Makefile.PL make (or dmake or nmake) make test make install
new() is called as my($cladotron) = Tree::Cladogram::Imager -> new(k1 => v1, k2 => v2, ...) or as my($cladotron) = Tree::Cladogram::ImageMagick -> new(k1 => v1, k2 => v2, ...).
new()
my($cladotron) = Tree::Cladogram::Imager -> new(k1 => v1, k2 => v2, ...)
my($cladotron) = Tree::Cladogram::ImageMagick -> new(k1 => v1, k2 => v2, ...)
It returns a new object of type Tree::Cladogram::Imager or Tree::Cladogram::ImageMagick.
Tree::Cladogram::Imager
Tree::Cladogram::ImageMagick
Key-value pairs accepted in the parameter list (see corresponding methods for details [e.g. "branch_color([$string])"]):
Specify the color of the branches in the tree.
See (in the FAQ) "What colors are supported?" for details about colors.
Default: '#7e7e7e' (gray).
Specify the thickness of the branches.
Default: 3 (px).
Specify non-production effects.
Currently, the only extra effect is to draw fuchsia boxes around the leaf names.
Frankly, this helped me debug the Image::Magick side of things.
Default: 0 (no extra effects).
Specify that you want a frame around the image.
Default: 0 (no frame).
Specify an extra bit for the length of the final branch leading to the names of the leaves.
Default: 30 (px).
Specify the color of the frame, if any.
See also draw_frame.
draw_frame
Default: '#0000ff' (blue).
Specify the name of the *.clad file to read. Of course, the suffix does not have to be 'clad'.
The format of this file is specified in the "FAQ".
Default: ''.
Specify the font color of the name of each leaf.
Specify the name of the font file to use for the names of the leaves.
You can use path names, as per the default, or - using Image::Magick -, you can just use the name of the font, such as 'DejaVu-Sans-ExtraLight'.
Default: '/usr/share/fonts/truetype/freefont/FreeMono.ttf'.
Specify the size of the text used for the name of each leaf.
Default: 16 (points).
Specify the distance from the left of the image to the left-most point at which something is drawn.
This also sets the right-hand margin.
Default: 15 (px).
Specify the name of the image file to write.
Image formats supported are anything supported by Imager or Image::Magick. See the "What image formats are supported?" for details.
Default: '' (no output).
Specify that you want to print the tree constructed by the code.
This option is really a debugging aid.
Default: 0 (no tree).
Specify the title to draw at the bottom of the image.
Default: '' (no title).
Specify the font color of the title.
Default: '#000000' (black).
Specify the name of the font file to use for the title.
Default: '/usr/share/fonts/truetype/freefont/FreeSansBold.ttf'.
Specify the size of the text used for the name of the title.
Specify the distance from the top of the image to the top-most point at which something is drawn.
This also sets the bottom margin.
The horizontal length of branches.
See also "final_x_step([$integer])" and "y_step([$integer])".
Default: 50 (px).
The vertical length of the branches.
Note: Some vertical branches will be shortened if the code detects overlapping when leaf names are drawn.
See also "x_step([$integer])".
Default: 40 (px).
Get or set the color used to draw branches.
branch_color is a parameter to "new()".
branch_color
Get or set the width of branches.
branch_width is a parameter to "new()".
branch_width
Get or set the option to activate debug mode.
debug is a parameter to "new()".
debug
Get or set the option to draw a frame on the image.
draw_frame is a parameter to "new()".
Get or set a bit extra for the horizontal length of the branch leading to leaf names.
final_x_step is a parameter to "new()".
final_x_step
Get or set the color of the frame.
frame_color is a parameter to "new()".
frame_color
Get or set the name of the input file.
input_file is a parameter to "new()".
input_file
Get or set the font color of the text used to draw leaf names.
leaf_font_color is a parameter to "new()".
leaf_font_color
Get or set the name of the font file used for leaf names.
leaf_font_file is a parameter to "new()".
leaf_font_file
Get or set the size of the font used to draw leaf names.
leaf_font_size is a parameter to "new()".
leaf_font_size
Get or set the distance from the left edge at which drawing starts.
This also sets the right margin.
left_margin is a parameter to "new()".
left_margin
Get the right-most point at which something was drawn.
This value is determined by examining the bounding boxes of all leaf names.
In the case that the title is wider that the right-most leaf's name, maximum_x reflects this fact.
maximum_x
Get the bottom-most point at which something was drawn.
This value includes the title, if any.
See "Constructor and Initialization" for details on the parameters accepted by "new()".
Get or set the name of the output file.
The file suffix determines what type of file is written.
For more on supported image types, see the "What image formats are supported?".
output_file is a parameter to "new()".
output_file
Get or set the option to print the tree constructed by the code. This is basically a debugging option.
print_tree is a parameter to "new()".
print_tree
Get the root of the tree built by calling run(). This tree is an object of type Tree::DAG_Node.
For printing the tree, see "print_tree([$Boolean])".
Normally, end-users would never call this method.
After calling "new()", this is the only other method you would normally call.
Get or set the title to be drawn at the bottom of the image.
Note: It's vital you set the title before calling "run()", since the width of the title might be greater that the width of the tree, and the width of the title would then be used to determine the width of the image to create.
title is a parameter to "new()".
title
Get or set the font color of the text used to draw the title.
title_font_color is a parameter to "new()".
title_font_color
Get or set the name of the font file used for the title.
title_font_file is a parameter to "new()".
title_font_file
Get or set the size of the font used to draw the title.
title_font_size is a parameter to "new()".
title_font_size
Get or set the distance from the top edge at which drawing starts.
top_margin is a parameter to "new()".
top_margin
Get or set the length of horizontal branches.
See also final_x_step.
x_step is a parameter to "new()".
x_step
Get or set the length of vertical branches.
y_step is a parameter to "new()".
y_step
See scripts/*.pl and scripts/*.sh.
Outputs to my web server's doc root, which is in Debian's RAM disk, a file called "$ENV{DR}/misc/Debian.font.list.png".
The output file is not part of the distro (being 3.3 Mb), but is on line at http://savage.net.au/misc/Debian.font.list.png.
The program you would normally use to drive Tree::Cladogram::ImageMagick.
See also image.magick.sh.
A convenient way to run image.magick.pl.
The program you would normally use to drive Tree::Cladogram::Imager.
See also imager.sh.
A convenient way to run imager.pl.
A simple way for me to convert the docs into HTML.
Outputs data/test.image.magick.png. I used this program to experiment with Image::Magick while converting Tree::Cladogram::Imager into Tree::Cladogram::ImageMagick.
A convenient way to run test.image.magick.pl.
See data/*.
This sample input file is discussed just below, at the start of the "FAQ".
This is the output of rendering nationalgeographic.01.clad with Imager.
This is the output of rendering nationalgeographic.01.clad with Image::Magick.
The is is output of scripts/test.image.magick.pl.
This is the output of rendering wikipedia.01.clad with Imager.
This is the output of rendering wikipedia.01.clad with Image::Magick.
Sample 1 - https://en.wikipedia.org/wiki/Cladogram:
+---- Beetles | | Root ---+ +---- Wasps, bees, ants | | | | 1---+ +---- Butterflies, moths | | | | 2---+ | | +---- Flies
This is the data file (shipped as data/cladogram.01.clad). The format is defined formally below:
Parent Place Node root above Beetles root below 1 1 above Wasps, bees, ants 1 below 2 2 above Butterflies, moths 2 below Flies
Output: Using Imager and using Image::Magick.
Sample 2 - http://phenomena.nationalgeographic.com/2015/12/11/paleo-profile-the-smoke-hill-bird/:
+--- Archaeopterix lithographica | | | Root ---+ +--- Apsaravis ukhaana | | | | | | 1---+ +--- Gansus yumemensis | | | | | | 2---+ +--- Ichthyornis dispar | | | | +--- Gallus gallus | | | 3---+ 5---+ | | | | | +--- Anas clypeata | | 4---+ | +--- Pasquiaornis | | | | 6---+ +--- Enaliornis | | | | | | 7---+ +--- Baptornis advenus | | | | +--- Brodavis varnei | | | 8---+ 10--+ | | | | | +--- Brodavis baileyi | | 9---+ | +--- Fumicollis hoffmani | | | | 11--+ +--- Parahesperornis alexi | | | | 12--+ | | +--- Hesperornis regalis
This is the data file (shipped as data/nationalgeographic.01.clad). The format is defined formally below:
Parent Place Node root above Archaeopterix lithographica root below 1 1 above Apsaravis ukhaana 1 below 2 2 above Gansus yumemensis 2 below 3 3 above Ichthyornis dispar 3 below 4 4 above 5 4 below 6 5 above Gallus gallus 5 below Anas clypeata 6 above Pasquiaornis 6 below 7 7 above Enaliornis 7 below 8 8 above Baptornis advenus 8 below 9 9 above 10 9 below 11 10 above Brodavis varnei 10 below Brodavis baileyi 11 above Fumicollis hoffmani 11 below 12 12 above Parahesperornis alexi 12 below Hesperornis regalis
File format:
Oh, all right. You can use any number of spaces too, but why bother?
For non-programmers, the /.../ is a regular expression, just saying the program tests for that exact string. The '\t's represent tabs and the suffix 'i' means use a case-insensitive test.
One for the daughter 'above' the current node, and one for the daughter 'below'.
The code hides the name of nodes which match /^(\d+|root)$/.
Imager V 1.004.
Image::Magick V 6.9.3-0 Q16.
For help installing Image::Magick under Debian, see http://savage.net.au/ImageMagick/html/Installation.html.
My default install of Imager lists:
bmp ft2 ifs png pnm raw
Image::Magick supports a huge range of formats (221 actually). To list them, run scripts/test.image.magick.pl. Note: This program writes to data/test.image.magick.png.
See Imager::Color for Imager's docs on color. But you're probably better off using Image::Magick's table mentioned next, since my module only accepts colors. It does not allow you to provide an Imager::Color object as a parameter.
See Image::Magick colors for a huge table of both names and hex values.
Check these directories:
If you're using Debian, run fc-list for a list of installed fonts.
fc-list
More information on Debian's support for fonts can be found on Debian's wiki.
See http://savage.net.au/misc/Debian.font.list.png for the fonts on my laptop. Note: This file is 3.3 Mb, so you may have to zoom it to 500% to make it readable.
See scripts/imager.sh and scripts/image.magick.sh for lists of fonts I have played with while developing this module.
Further, note this text copied from the docs for Imager::Font:
This module handles creating Font objects used by Imager. The module also handles querying fonts for sizes and such. If both T1lib and FreeType were available at the time of compilation then Imager should be able to work with both TrueType fonts and t1 Postscript fonts. To check if Imager is t1 or TrueType capable you can use something like this: use Imager; print "Has truetype\n" if $Imager::formats{tt}; print "Has t1 postscript\n" if $Imager::formats{t1}; print "Has Win32 fonts\n" if $Imager::formats{w32}; print "Has Freetype2\n" if $Imager::formats{ft2};
My default install of Imager reports:
Has Freetype2
This might depend on the font, but here are some tests I ran with the one leaf font:
I started with Tree::Simple precisely because it's simple, but found it awkward to use.
I did use Tree::Simple in HTML::Parser::Simple. That module was deliberately kept simple, but before that, and since, I've always gone back to Tree::DAG_Node.
The process starts by calling the undocumented method _check_for_overlap().
_check_for_overlap()
Bio::Tree::Draw::Cladogram
Imager
Image::Magick
Help installing Image::Magick
Tree::DAG_Node
The file Changes was converted into Changelog.ini by Module::Metadata::Changes.
Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.
https://github.com/ronsavage/Tree-Cladogram
Email the author, or log a bug on RT:
https://rt.cpan.org/Public/Dist/Display.html?Name=Tree::Cladogram.
Tree::Cladogram was written by Ron Savage <ron@savage.net.au> in 2015.
My homepage: http://savage.net.au/
Australian copyright (c) 2015, Ron Savage.
All Programs of mine are 'OSI Certified Open Source Software'; you can redistribute them and/or modify them under the terms of The Perl License, a copy of which is available at: http://dev.perl.org/licenses/
To install Tree::Cladogram, copy and paste the appropriate command in to your terminal.
cpanm
CPAN shell
perl -MCPAN -e shell install Tree::Cladogram
For more information on module installation, please visit the detailed CPAN module installation guide.