TreeExtender.pl reads phylogenetic trees in Newick format and converts them to the phyloXML format. It can also read ancestral state probabilities or ancestral state values from external programs and annotate the phyloXML tree with these probabilities. At present, ancestral state values for continuous variables can be taken from the ace function of the ape package and ancestral state probabilities of discrete characters can be taken from BayesTraits output. TreeExtender.pl can import phyloXML files, which allows the possibility to sequentially add various traits to the same phyloXML tree. The program's main function is to prepare trees for the TreeGradients.pl script.

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
• IO::File
• XML::DOM
• XML::Writer

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

activating the ancestral character state parser

options for parsing Mesquite files

options for parsing BayesTraits files

options for parsing list files

The list file contains ancestral character state values in a very straightforward format. It is a plain text file in which each line has a character value followed by a tab character and a list of the terminal taxa subtended by the node to which the character value applies. The list of terminal taxa must have a space character between each taxon. So, obviously, you're not supposed to have spaces in your taxon names. This easy list format allows users to come up with hypothetical ancestral values and plot them with TreeGradients. For example, states for all nodes in a rooted a four-taxon tree can be listed as follows:

• example tree

• hypothetical list file for this tree

4.13 orangutan
3.75 gorilla
2.15 chimpanzee
2.23 human
2.35 chimpanzee human
4.02 chimpanzee human gorilla
4.88 orangutan chimpanzee human gorilla

When TreeExtender.pl is asked to parse output from ancestral trait reconstruction programs, it creates phyloXML files with custom tags at nodes. The tags are self-explanatory but I'm pasting some examples below to show what they look like.

• example of tag for discrete character

<custom>
 <name>name_of_character</name>
 <type>discrete</type>
 <state>
 <state>0</state>
 <probability>0.85</probability>
 </state>
 <state>
 <state>1</state>
 <probability>0.15</probability>
 </state>
</custom>

• example of tag for double_discrete character

<custom>
 <name>name_of_character</name>
 <type>discrete</type>
 <state>
 <state>00</state>
 <probability>0.65</probability>
 </state>
 <state>
 <state>01</state>
 <probability>0.05</probability>
 </state>
 <state>
 <state>10</state>
 <probability>0.20</probability>
 </state>
 <state>
 <state>11</state>
 <probability>0.10</probability>
 </state>
</custom>

• example of tag for multistate character

<custom>
 <name>name_of_character</name>
 <type>multistate</type>
 <state>
 <state>0</state>
 <probability>0.519707</probability>
 </state>
 <state>
 <state>1</state>
 <probability>0.116460</probability>
 </state>
 <state>
 <state>2</state>
 <probability>0.363833</probability>
 </state>
</custom>
 

• example of tag for continuous character

<custom>
 <name>name_of_character</name>
 <type>continuous</type>
 <value>2.659123</value>
</custom>

This program uses Bio::Tree::Tree objects to store trees in memory and attach data to the tree nodes. Character data are added as tags; the tag name corresponding to the name of the character. Tags have the following structure:

• example of tag for discrete character

$tag = {
 'type'  =>  'discrete',
 'name'  =>  'name_of_character',
 'state' =>  [
 {'state' => 0, 'probability' => 0.85},
 {'state' => 1, 'probability' => 0.15}
 ]
};

• example of tag for double_discrete character

$tag = {
 'type'  =>  'double_discrete',
 'name'  =>  'name_of_character',
 'state' =>  [
 {'state' => 00, 'probability' => 0.65},
 {'state' => 01, 'probability' => 0.05}
 {'state' => 10, 'probability' => 0.20},
 {'state' => 11, 'probability' => 0.10}
 ]
};

• example of tag for multistate character

$tag = {
 'type'  =>  'multistate',
 'name'  =>  'name_of_character',
 'state' =>  [
 {'state' => 0, 'probability' => 0.519707},
 {'state' => 1, 'probability' => 0.116460},
 {'state' => 2, 'probability' => 0.363833}
 ]
};

• example of tag for continuous character

$tag = {
 'type'  =>  'continuous',
 'name'  =>  'name_of_character',
 'value' =>  2.659123
};