One-liners

First steps

Problem

No concept is valid in Perl if it cannot be expressed in a one-liner. For the Bio::Phylo package, some operations can be performed using a single expression from the command line. Here are some examples.

Solution 1: downloading and converting Tree of Life data

 perl -MBio::Phylo::IO=parse -e 'print parse->to_nexus' format tolweb as_project 1 url $URL
    

Discussion

Assuming that the environment variable $URL has been set to point to a node in the XML web service of the Tree of Life (<http://tolweb.org>), this command will download the output, parse it, and print the parsed output as nexus. As an example, using this url:

 http://tolweb.org/onlinecontributors/app?service=external&page=xml/TreeStructureService&node_id=133799
    

Something like the following output would be produced:

 #NEXUS
 BEGIN TAXA;
 [! Taxa block written by Bio::Phylo::Taxa 0.31_1520 on Thu Nov 25 20:49:54 2010 ]      
         DIMENSIONS NTAX=3;
         TAXLABELS
                        'Bembidion alaskense'
                        'Bembidion argenteolum'
                        'Bembidion semenovi'
                 ;
 END;
 BEGIN TREES;
 [! Trees block written by Bio::Phylo::Forest 0.31_1520 on Thu Nov 25 20:49:54 2010 ]
        TRANSLATE
                1 'Bembidion alaskense',
                2 'Bembidion argenteolum',
                3 'Bembidion semenovi';
        TREE Tree2 = [&R] (((2,3),1));
 END;
    

So what is happening here? Firstly, we provide the "-MBio::Phylo::IO" switch, to which we add "=parse", which means we import the "parse" function from Bio::Phylo::IO. This function is supplied with named arguments, which can also be provided on the command line, i.e. as part of the @ARGV array.

Secondly, we use the "-e 'print parse->to_nexus'" switch. Here we tell perl to execute the parse function, transform its return value to nexus, and print that to STDOUT.

Following that, we provide the named command line arguments. "format tolweb" specifies that the input for the parse function is in the Tree of Life XML format. "as_project 1" specifies that the parse function should return its contents as a newly created Bio::Phylo::Project object. "url $URL" specifies the data source to parse; in this case the data source lives at $URL. Other possible options for a data source are "file" with a file name, "string" with a string of phylogenetic data in some recognized format, or "handle" with an open file handle.

(This example requires the otherwise optional modules LWP::UserAgent and XML::Twig to be installed on your system.)

Solution 2: calculating tree balance

 perl -MBio::Phylo::IO=parse -e 'print \
 parse(-format=>"newick",-string=>"((A,B),C);")->first->calc_imbalance'
    

Discussion

The "-MModule" switch is the equivalent of using "use Module;" in a script. Here we use the Bio::Phylo::IO module, which is Bio::Phylo's entry point into file parsing and file writing.

The "-e" switch is used to evaluate the subsequent expression. We parse a string, "((A,B),C);", of format "newick". The parser returns a Bio::Phylo::Forest object (i.e. a set of trees, in this case a set of one). From this set we retrieve the first (and only) tree, and calculate Colless' imbalance, which returns a number, which we print to standard out.

This would print "1", because the tree is a ladder, and therefore completely unbalanced. Note how this example uses the standard interface for Bio::Phylo::IO as you would normally use it in code you write in a script or a module. As the arguments to the "parse" function can also be supplied in @ARGV (useful for one-liners or other processes that launch shell commands) the example can be rewritten as:

 perl -MBio::Phylo::IO=parse -e 'print parse()->first->calc_imbalance' \
 format newick string "((A,B),C);"
    

In this alternative invocation, note how the arguments to the parse call are now outside of the '...command...' quotes, making them "shell words", which for various reasons may not be preceded by dashes.

Sets of trees

Problem

You want a one-liner to iterate over a set of trees:

Solution

 perl -MBio::Phylo::IO=parse -lne 'print \
 parse(-format=>"newick",-string=>$_)->first->calc_i2' <file>
    

Discussion

The "-n" switch wraps a "while(<>) { ... }" around the program, so the trees from file (that is, if they are one newick tree description per line) are copied into $_ one tree at a time. The "-l" switch appends a line break to the printed output.

Stringifying trees

Problem

You don't want a number printed to "STDOUT", you want a tree:

Solution

 perl -MBio::Phylo::IO=parse -e 'print \
 parse(-format=>"newick",-string=>"((A,B),C);")->first->to_newick'
    

Discussion

If you try to print a tree object, what's written is something like "Bio::Phylo::Forest::Tree=SCALAR(0x1a337dc)" (that is, the memory address of the object reference). This is probably not what you want, so the tree object has a "to_newick" method that stringifies the tree to a newick string. Likewise, matrices, taxa and tree blocks can write a NEXUS block using "to_nexus", and all of them can also be written to NeXML (<http://www.nexml.org>) using "to_xml" and to a JSON mapping thereof using "to_json".

Input and output

Parsing trees

Problem

You want to create a Bio::Phylo::Forest::Tree object from a newick string.

Solution

 use Bio::Phylo::IO;

 # get a newick string from some source
 my $tree_string = '(((A,B),C),D);';

 # Call class method parse from Bio::Phylo::IO
 my $tree = Bio::Phylo::IO->parse(
    -string => $tree_string,
    -format => 'newick'
 )->first;

 # note: newick parser returns 'Bio::Phylo::Forest'
 # Call ->first to retrieve the first tree of the forest.

 print ref $tree, "\n"; # prints 'Bio::Phylo::Forest::Tree'
    

Discussion

The Bio::Phylo::IO module invokes format specific parser and unparser modules. It is Bio::Phylo's front door for data input and output from files, raw strings and file handles.

In the solution the IO module calls the Bio::Phylo::Parsers::Newick parser which turns a tree description into a Bio::Phylo::Forest object. (Several other parser and unparser modules live in the Bio::Phylo::Parsers::* and Bio::Phylo::Unparsers::* namespaces, respectively.)

The returned forest object subclasses Bio::Phylo::Listable, as a forest models a list of trees that you can iterate over. By calling the "->first" method, we get the first tree in the forest - a Bio::Phylo::Forest::Tree object (in the example it's a very small forest, consisting of just this single tree).

Parsing tables

Problem

You want to create a Bio::Phylo::Matrices::Matrix object from a string.

Solution

 use Bio::Phylo::IO;

 # parsing a table
 my $table_string = qq(A,1,2|B,1,2|C,2,2|D,2,1);
 my $matrix = Bio::Phylo::IO->parse(
    -string   => $table_string,
    -format   => 'table',     # See Bio::Phylo::Parsers::Table
    -type     => 'STANDARD',  # Data type
    -fieldsep => ',',         # field separator
    -linesep  => '|'          # line separator
 );

 print ref $matrix, "\n"; # prints 'Bio::Phylo::Matrices::Matrix'
    

Discussion

Here the Bio::Phylo::Parsers::Table module parses a string "A,1,2|B,1,2|C,2,2|D,2,1", where the "|" is considered a record or line separator, and the "," as a field separator. The default field and line separators are the tabstop character "\t" and the line break "\n".

Parsing taxa

Problem

You want to create a Bio::Phylo::Taxa object from a string.

Solution

 use Bio::Phylo::IO;

 # parsing a list of taxa
 my $taxa_string = 'A:B:C:D';
 my $taxa = Bio::Phylo::IO->parse(
    -string   => $taxa_string,
    -format   => 'taxlist',
    -fieldsep => ':'
 );

 print ref $taxa, "\n"; # prints 'Bio::Phylo::Taxa'
    

Discussion

Here the Bio::Phylo::Parsers::Taxlist module parses a string "A:B:C:D", where the ":" is considered a field separator. The parser returns a Bio::Phylo::Taxa object. Note that the same result can be obtained by building the taxa object from scratch (a more feasible proposition than building trees or matrices from scratch):

 use Bio::Phylo::Factory; 
 
 # first instantiate the factory...
 my $factory = Bio::Phylo::Factory->new;
 
 # ...then use it to create other objects, such as taxa blocks
 my $taxa = $factory->create_taxa( -name => 'MyTaxa' );
 
 # or taxa, (with names A, B, C and D), and add them to the taxa block
 $taxa->insert( $factory->create_taxon( -name => $_ ) ) for qw(A B C D);
 
 # and write out as a nexus block
 print $taxa->to_nexus( -header => 1, -links => 1 );
    

This example uses the Bio::Phylo::Factory, which is an object that can create other objects. Here we have it create a Bio::Phylo::Taxa block, which we populate with four Bio::Phylo::Taxa::Taxon objects. We then write out the taxa block as nexus, complete with the #NEXUS header (this is optional so that we can combine multiple blocks in the same file), and a title, using the "-links" switch. The latter is a facility that only seems to be used by Mesquite (<http://mesquiteproject.org>) and Bio::Phylo. It adds a "title" to the taxa block in the nexus output, and other blocks (character state matrices and tree blocks) refer to this using a "links" statement. This is useful if you want to have multiple taxa blocks in the same file and you want to distinguish them. Putting this all together, the output is thus:

 #NEXUS
 BEGIN TAXA;
 [! Taxa block written by Bio::Phylo::Taxa 0.31_1520 on Thu Nov 25 21:31:58 2010 ]
        TITLE MyTaxa;
         DIMENSIONS NTAX=4;
         TAXLABELS
                        A
                        B
                        C
                        D
         ;
 END;
    

Iterating

Iterating over trees and nodes.

Problem

You want to access trees and nodes contained in a Bio::Phylo::Forest object.

Solution

  use Bio::Phylo::IO qw(parse);

  my $string = '((A,B),(C,D));(((A,B),C)D);';
  my $forest = parse( -format => 'newick', -string => $string );

  print ref $forest; # prints 'Bio::Phylo::Forest'

  # access trees in $forest
  foreach my $tree ( @{ $forest->get_entities } ) {
      print ref $tree; # prints 'Bio::Phylo::Forest::Tree';

      # access nodes in $tree
      foreach my $node ( @{ $tree->get_entities } ) {
          print ref $node; # prints 'Bio::Phylo::Forest::Node';

      }
  }
    

Discussion

Bio::Phylo::Forest and Bio::Phylo::Forest::Tree are nested subclasses of the iterator class Bio::Phylo::Listable. Nested iterator calls (such as "->get_entities") can be invoked on the objects.

Iterating over taxa.

Problem

You want to access the individual taxa in a Bio::Phylo::Taxa object.

Solution

 use Bio::Phylo::IO qw(parse);

 my $string = 'A|B|C|D|E|F|G|H';
 my $taxa = parse(
     -string   => $string,
     -format   => 'taxlist',
     -fieldsep => '|'
 );
 print ref $taxa; # prints 'Bio::Phylo::Taxa';

 while ( my $taxon = $taxa->next ) {
     print ref $taxon; # prints 'Bio::Phylo::Taxa::Taxon'
 }
    

Discussion

A Bio::Phylo::Taxa object is a subclass of the Bio::Phylo::Listable class. Hence, you could also call "->get_entities" on the taxa object, which returns a reference to an array of taxon objects contained by the taxa object. Note however the shorthand:

 while ( my $taxon = $taxa->next ) { ... }
    

Iterating over datum objects.

Problem

You want to access the datum objects contained by a Bio::Phylo::Matrices::Matrix object.

Solution

 use Bio::Phylo::IO;

 # parsing a table
 my $table_string = qq(A,1,2|B,1,2|C,2,2|D,2,1);
 my $matrix = Bio::Phylo::IO->parse(
    -string   => $table_string,
    -format   => 'table',     # See Bio::Phylo::Parsers::Table
    -type     => 'STANDARD',  # Data type
    -fieldsep => ',',         # field separator
    -linesep  => '|'          # line separator
 );

 print ref $matrix, "\n"; # prints 'Bio::Phylo::Matrices::Matrix'

 my $datum = $matrix->get_by_index( 0, -1 );
 print ref $datum; # NOTE: prints 'ARRAY'!
    

Discussion

The Bio::Phylo::Matrices::Matrix object subclasses the Bio::Phylo::Listable object. Hence, its iterator methods are applicable here as well. In the above example, the get_by_index method is used. With a single argument it returns a Bio::Phylo object. With multiple arguments the semantics are nearly identical to array slicing (see perldata), except that an array reference is returned. Bio::Phylo generally passes lists by reference (see perlref).

Simulating trees

Generating Yule trees.

Here's how to generate a forest of ten trees with ten tips:

  use Bio::Phylo::Generator;
  my $gen = Bio::Phylo::Generator->new;
  my $trees = $gen->gen_rand_pure_birth(
      -trees => 10,
      -tips  => 10,
      -model => 'yule'
  );
  print ref $trees; # prints 'Bio::Phylo::Forest'
    

Expected versus randomly drawn waiting times.

The generator object simulates trees under the Yule or the Hey model. The "gen_rand_pure_birth" method call returns branch lengths drawn from the appropriate distribution, while "gen_exp_pure_birth" returns the expected waiting times (e.g. 1/n where n=number of lineages for the Yule model).

Filtering

Filtering objects by numerical value.

To retrieve, for example, the nodes from a tree that are close to the root, call:

 my @deep_nodes = @{ $tree->get_by_value(
    -value => 'calc_nodes_to_root',
    -le    => 2
 ) };
    

Which retrieves the nodes no more than 2 ancestors away from the root. Any method that returns a numerical value can be specified with the "-value" flag. The "-le" flag specifies that the returned value is less-than-or-equal to 2.

Filtering objects by regular expression.

String values that are returned by objects can be filtered using a compiled regular expression. For example:

 my @lemurs = @{ $tree->get_by_regular_expression(
      -value => 'get_name',
      -match => qr/[Ll]emur_.+$/
 ) };
    

Retrieves all nodes whose genus name matches Eulemur, Lemur or Hapalemur.

Drawing trees

  use Bio::Phylo::Treedrawer;
  use Bio::Phylo::IO;

  my $treedrawer = Bio::Phylo::Treedrawer->new(
     -width  => 400,
     -height => 600,
     -shape  => 'CURVY',
     -mode   => 'CLADO',
     -format => 'SVG'
  );

  my $tree = Bio::Phylo::IO->parse(
     -format => 'newick',
     -string => '((A,B),C);'
  )->first;

  $treedrawer->set_tree($tree);
  $treedrawer->set_padding(50);

  my $string = $treedrawer->draw;

Read the Bio::Phylo::Treedrawer perldoc for more info.

Tips and tricks

Generic metadata

You can append generic key/value pairs to any object, by calling "$obj->set_generic( 'key' => 'value');". Subsequently calling "$obj->get_generic('key');" returns 'value'. This is a very useful feature in many situations where you may want to attach, for example, results from analyses by outside programs (e.g. likelihood scores) to the tree objects they refer to. Likewise, multiple numbers (e.g. bootstrap values, posteriors, bremer values) can be attached to the same node in this way.

Perl objects

perlboot

Introduction to OO perl. Read at least this one if you have no experience with OO perl.

perlobj

Details about perl objects.

perltooc

Class data.

perltoot

Advanced objects: "Tom's object-oriented tutorial for perl"

perlbot

The "Bag'o Object Tricks" (the BOT).

The Bio::Phylo object model

The Bio::Phylo root object.

The Bio::Phylo object is never used directly. However, all other objects inherit from it, which means that all objects have getters and setters for their name, description, score. They can all return a globally unique ID, log messages, and keep track of more administrative things such as the version number of the release.

The Bio::Phylo::Forest::* namespace

According to Bio::Phylo, there is a Forest (which is modelled by the Bio::Phylo::Forest object), which contains Bio::Phylo::Forest::Tree objects, which contain Bio::Phylo::Forest::Node objects.

The Bio::Phylo::Forest::Node object

A node 'knows' a couple of things: its name, its branch length (i.e. the length of the branch connecting it and its parent), who its parent is, its next sister (on its right), its previous sister (on the left), its first daughter and its last daughter. Also, a taxon can be specified that the node refers to (this makes most sense when the node is terminal). These properties can be retrieved and modified by methods classified as ACCESSORS and MUTATORS.

From this set of properties follows a number of things which must be either true or false. For example, if a node has no children it is a terminal node. By asking a node whether it "is_terminal", it replies either with true (i.e. 1) or false (undef). Methods such as this are classified as TESTS.

Likewise, based on the properties of an individual node we can perform a query to retrieve nodes related to it. For example, by asking the node to "get_ancestors" it returns a list of its ancestors, being all the nodes and the path from its parent to, and including, the root. These methods are QUERIES.

Lastly, some CALCULATIONS can be performed by the node. By asking the node to "calc_path_to_root" it calculates the sum of the lengths of the branches connecting it and the root. Of course, in order to make all this possible, a node has to exist, so it needs to be constructed. The CONSTRUCTOR is the Bio::Phylo::Node->new() method.

Once a node has served its purpose it can be destroyed. For this purpose there is a DESTRUCTOR, which cleans up once we're done with the node. However, in most cases you don't have to worry about constructing and destroying nodes as this is handled by Bio::Phylo and perl for you.

For a detailed description of all the node methods, their arguments and return values, consult the node documentation, which, after install, can be viewed by issuing the "perldoc Bio::Phylo::Forest::Node" command.

The Bio::Phylo::Forest::Tree object

A tree knows very little. All it really holds is a set of nodes, which are there because of TREE POPULATION, i.e. the process of inserting nodes in the tree. The tree can be queried in a number of ways, for example, we can ask the tree to "get_entities", to which the tree replies with a list of all the nodes it holds. Be advised that this doesn't mean that the nodes are connected in a meaningful way, if at all. The tree doesn't care, the nodes are supposed to know who their parents, sisters, and daughters are. But, we can still get, for example, all the terminal nodes (i.e. the tips) in the tree by retrieving all the nodes in the tree and asking each one of them whether it "is_terminal", discarding the ones that aren't.

Based on the set of nodes the tree holds it can perform calculations, such as "calc_tree_length", which simply means that the tree iterates over all its nodes, summing their branch lengths, and returning the total.

The tree object also has a constructor and a destructor, but normally you don't have to worry about that. All the tree methods can be viewed by issuing the "perldoc Bio::Phylo::Forest::Tree" command.

The Bio::Phylo::Forest object

The object containing all others is the Forest object. It serves merely as a container to hold multiple trees, which are inserted in the Forest object using the "insert()" method, and retrieved using the "get_entities" method. More information can be found in the Bio::Phylo::Forest perldoc page.

The Bio::Phylo::Matrices::* namespace

Objects in the Bio::Phylo::Matrices namespace are used to handle comparative data, as single observations, and in larger container objects.

The Bio::Phylo::Matrices::Datum object

The datum object holds observations of a predefined type, such as molecular data, or continuous character states. The Datum object can be linked to a taxon object, to specify which OTU the observation refers to.

The Bio::Phylo::Matrices::Matrix object

The matrix object is used to aggregate datum objects into a larger, iterator object, which can be accessed using the methods of the Bio::Phylo::Listable class.

The Bio::Phylo::Matrices object

The top level opject in the Bio::Phylo::Matrices namespace is used to contain multiple matrix or alignment objects, again implementing an iterator interface.

The Bio::Phylo::Taxa::* namespace

Sets of taxa are modelled by the Bio::Phylo::Taxa object. It is a container that holds Bio::Phylo::Taxa::Taxon objects. The taxon objects at present provide no other functionality than to serve as a means of crossreferencing nodes in trees, and datum or sequence objects. This, however, is a very important feature. In order to be able to write, for example, files formatted for Mark Pagel's Discrete, Continuous and Multistate programs a taxa object, a matrix and a tree object must be crossreferenced.

The Bio::Phylo::Taxa object

The taxa object is analogous to a taxa block as implemented by Mesquite (<http://mesquiteproject.org>). Multiple matrix objects and forests can be linked to a single taxa object, using "$taxa->set_matrix( $matrix )". Conversely, the relationship from matrix to taxa and from forest to taxa is a one-to-one relationship.

The Bio::Phylo::Taxa::Taxon object

Just as forests can be linked to taxa objects, so too can individual node and datum objects be linked to individual taxon objects. Again, the taxon can hold references to multiple nodes or multiple datum objects, but conversely there is a one-to-one relationship. There is a constraint on these relationships: a node can only refer to a taxon that belongs to a taxa object that the forest object that contains the node references:

       YES!
  ______________    
 |FOREST        |  The taxon and node objects can
 |  __________  |  link to each other, because
 | |TREE      | |  their containers do also.
 | |  ______  | |  
 | | |NODE  | | |  
 | | |______| | |  
 | |_____^____| |                 
 |_______|______|              NO!       
      ^  |               ______________  
  ____|__|__            |FOREST 'B'    |  The taxon object 
 |TAXA   |  |           |  __________  |  cannot reference
 |  _____|  |           | |TREE      | |  forest 'A' while
 | |TAXON | |           | |  ______  | |  its container 
 | |______| |           | | |NODE  | | |  references forest
 |__________|           | | |______| | |  'B'. 
                        | |__________| |  
                        |______________|    ______________   
                             ^             |FOREST 'A'    |   
                         ____|_____        |  __________  |  
                        |TAXA      |       | |TREE      | |  
                        |  ______  |       | |  ______  | |  
                        | |TAXON |------------>|NODE  | | |  
                        | |______| |       | | |______| | |  
                        |__________|       | |__________| |  
                                           |______________|
    

Trying to set the links in the example on the right will result in errors: "Attempt to link X to taxon from wrong block". So what happens if a taxon already links to a node in forest 'A', and you link its enclosing taxa block to forest 'B'? The links at the taxon and node level will be removed, and the link between forest and taxa object will be enforced, yielding the warning "Reset X references from node objects to taxa outside taxa block".

Encapsulation

'Is-a' relationships: Inheritance

'Has-a' relationships

Named arguments when number of arguments >= 2.

  use Bio::Phylo::Forest::Tree;

  my $node = Bio::Phylo::Forest::Tree->new(
      -name  => 'PHYLIP_1',
      -score => 123,
  );

Type checking

 use Bio::Phylo::Util::CONSTANT qw(:objecttypes);
 use Bio::Phylo::Forest::Node;
 my $node = Bio::Phylo::Forest::Node->new;
 print "It's a node!" if $node->_type == _NODE_;

Hence, Bio::Phylo uses a form of "duck typing" ("if it walks like a duck, and quacks like a duck, it probably is a duck"), as opposed to one that is based on inheritance from a java-like interface, as is the convention in bioperl. Both systems have their advantages and drawbacks, but luckily they can coexist side by without problems.

As a new feature, a utility function is provided that does this type checking for you, returning true or throwing an exception (see below), so that the following will either succeed or die (so you might want to put it inside an eval{} block):

 if ( looks_like_object( $node, _NODE_ ) ) {
      # do something
 }

Constructor arguments

 use Bio::Phylo::Forest::Node;
 my $node = Bio::Phylo::Forest::Node->new( -name => "node1" );

The arguments will be passed up the inheritance tree, and will eventually be turned into method calls by the root class.

Retun values

Lists returned as array references

Multiple return values are never returned as a list, always as an array reference:

 my $nodes = $tree->get_entities;
 print ref $nodes;

 #prints ARRAY.
    

To receive nodes in @nodes, dereference the returned array reference (for clarity, all array dereferencing in this document is indicated by using braces in addition to this sigil):

 my @nodes = @{ $tree->get_entities };
    

Returns self on mutators

Mutator method calls always return the modified object, and so they can be chained:

 $node->set_name('Homo_sapiens')->set_branch_length(0.2343);
    

False but defined return values

When a value requested through an Accessor hasn't been set, the return value is "undef". Here you should take care how you test. For example:

 if ( ! $node->get_parent ) {
        $root = $node;
 }
    

This works as expected - object references are always "true", so if "get_parent" returns "false", $node has no parent - hence it must be the root. However:

 if ( ! $node->get_branch_length ) {

        # is there really no branch length?
        if ( defined $node->get_branch_length ) {

                # perhaps there is, but of length 0.
        }
 }
    

...warrants caution. Zero is evaluated as false-but-defined.

Exceptions

Trying/Catching exceptions

If some method call returns an exception, wrap the call inside an "eval" block. The error now becomes non-fatal:

 # try something:
 eval { $node->set_branch_length('a bad value'); };

 # handle exception, if any
 if ($@) {
    # do something, e.g.:
    print $@->trace->as_string; # <- $@ is an object!
 }
    

Stack traces

If an exception of a particular type is caught, you can print a stack trace and find out what might have gone wrong starting from your script drilling into the module code.

 # exception caught.
 if ( UNIVERSAL::isa( $@, 'Bio::Phylo::Util::Exceptions::BadNumber' ) ) {

    # prints stack trace in addition to error
    warn $@->error, "\n, $@->trace->as_string, "\n";

    # further metadata from exception object
    warn join ' ',  $@->euid, $@->egid, $@->uid, $@->gid, $@->pid, $@->time;
    exit;
 }
    

As a new feature (from v.0.17 onwards) exceptions have become more descriptive, with a generic explanation of what the thrown exception class typically means added to the error message, and stack traces are printed out by default.

Exception types

Several exception classes are defined. The type of the thrown exception should give you a hint as to what might be wrong. The types are specified in the Bio::Phylo::Util::Exceptions perldoc.