TreeGradients.pl user guide

TreeGradients.pl is a tree drawing program. The tree drawing options are fairly basic but the program has the ability to plot continuous traits at the nodes in colors, and uses color gradients to fill the branches between nodes. The output format is SVG (scalable vector graphics), which can be imported in most vectorial drawing software. The input trees have to be in a modified version of the phyloXML format, and I strongly recommend using TreeExtender.pl to generate them.

Dependencies

TreeGradients.pl is a Perl script. It requires that you have a recent version of Perl installed. In addition, TreeGradients.pl uses code from a number of external libraries. So, before running the script, make sure you have these modules installed. They can be obtained from CPAN.

  • BioPerl bundle
  • Sort::Array
  • Math::Trig
  • Graphics::ColorUtils
  • XML::DOM
  • SVG

Using the program

The program is a Perl script that must be run from the command-line. Its functionality must be controlled with command-line parameters.


global parameters

-t This option allows specifying the file containing the input tree in phyloXML format. It is a mandatory parameter. The input trees have to be in a modified version of the phyloXML format, and I strongly recommend using TreeExtender.pl to generate them.
-o This option allows specifying an output filename. Output is always written in SVG format. It is a mandatory parameter.

plotting gradients

-vn Specify the variable name you wish to along the tree. This variable name must correspond to a character name in the phyloXML file used as input. If you wish to plot branch support on the tree instead of the characters in the phyloXML file, you can use one of these:
bootstrap1 Uses the bootstrap values from the tree
bootstrap2 Ditto, but values < 50 are given the color for 50
posterior1 Uses the posterior probability values from the tree
posterior2 Ditto, but values < 0.50 are given the color for 0.50
-cm Defines the color mode
off Don't use colors (branches will be plotted in black)
gradient Branches will be a linear color gradient, starting from the color pertaining to the stem node to the color pertaining to the crown node
plain Branches will be plotted in a plain color pertaining to the node to which they lead
-gt Use this option to specify the gradient type. Two classes of gradients are implemented. Linear gradients are suitable for plotting continuous characters or probabilities of binary characters. Triangle gradients are suitable for plotting probabilities of three-state characters.
Linear gradients:
royg red – orange – yellow – green
rainbow red – orange – yellow – green – blue – indigo – violet
bly blue – yellow
blw blue – white
blg blue – green
bw black – white  (shades of gray)
g[x-y] shades of gray, from darkness x to darkness y
Triangle gradients:
byr blue - yellow - red
gyr green - yellow - red
gby green - blue - yellow
rgb red - green - blue
-gr This option allows specifying the number of gradient stops along each branch. Lots of stops means smooth color transitions at the expense of file size. Unless your characters change very rapidly, 5 stops will usually suffice.
-lo Use this option to specify how the gradient legend should be drawn.
h horizontal
v vertical

plotting labels

-pt Determines whether or not you want to plot the names of terminal taxa.
0 Don't plot them
1 Plot them
-ni This option allows you to plot one of the following labels at internal nodes.
nodeID Plots node IDs (these are usually support values)
value Plot the value of the variable that is plotted on the tree at the node in question
none Don't plot any values at nodes
-nd Specify the number of decimals you want to plot for the labels at internal nodes.

optional parameters for square trees

-re If this option is activated, the edges of the branches are rounded.
0 Straight edges
1 Round edges
-bs This option allows you to set the branch spacing (in mm).
-bw This option allows you to set the branch width (in mm).
-bs This option allows you to set the heigth-width ratio of the tree.