Bio::Phylo::IO - Front end for parsers and serializers
use Bio::Phylo::IO qw(parse unparse); # returns an unblessed array reference of block objects, # i.e. taxa, matrix or forest objects my $blocks = parse( '-file' => $file, '-format' => 'nexus', '-encoding' => ':encoding(UTF-8)', # optional, default is system-dependent ); for my $block ( @{ $blocks } ) { if ( $block->isa('Bio::Phylo::Taxa') ) { my $taxa = $block; # do something with the taxa } } # returns a Bio::Phylo::Project object my $project = parse( '-file' => $file, '-format' => 'nexus', '-as_project' => 1 ) my ($taxa) = @{ $project->get_taxa }; # parsing a tree from a newick string my $tree_string = '(((A,B),C),D);'; my $tree = Bio::Phylo::IO->parse( '-string' => $tree_string, '-format' => 'newick', )->first; # note: newick parsers return # 'Bio::Phylo::Forest'! Call # ->first to retrieve the first # tree of the forest. # prints 'Bio::Phylo::Forest::Tree' print ref $tree, "\n"; # if the tree is very large and you need only some terminal nodes from it $simplified_tree = Bio::Phylo::IO->parse( '-string' => $tree_string, '-format' => 'newick', '-keep' => ['A', 'D'], # nodes to keep '-ignore_comments' => 1, # treats [] symbols as part of taxon name )->first; # 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', # Data type, see Bio::Phylo::Parsers::Table '-type' => 'STANDARD', # field separator '-fieldsep' => ',', # line separator '-linesep' => '|' ); # prints 'Bio::Phylo::Matrices::Matrix' print ref $matrix, "\n"; # parsing a list of taxa my $taxa_string = 'A:B:C:D'; my $taxa = Bio::Phylo::IO->parse( '-string' => $taxa_string, '-format' => 'taxlist', '-fieldsep' => ':' ); # prints 'Bio::Phylo::Taxa' print ref $taxa, "\n"; # matches taxon names in tree to $taxa object $tree->cross_reference($taxa); # likewise for matrix $matrix->cross_reference($taxa); print unparse( # pass the tree object, # crossreferenced to taxa, which # are crossreferenced to the matrix '-phylo' => $tree, '-format' => 'pagel' ); # prints a pagel data file: #4 2 #A,n1,0.000000,1,2 #B,n1,0.000000,1,2 #n1,n2,0.000000 #C,n2,0.000000,2,2 #n2,n3,0.000000 #D,n3,0.000000,2,1
The IO module is the front end for parsing and serializing phylogenetic data objects. It is a non-OO module that optionally exports the 'parse' and 'unparse' subroutines into the caller's namespace, using the use Bio::Phylo::IO qw(parse unparse); directive. Alternatively, you can call the subroutines as class methods. The parse and unparse subroutines load and dispatch the appropriate sub-modules at runtime, depending on the '-format' argument.
use Bio::Phylo::IO qw(parse unparse);
parse
unparse
Parses a file or string.
Type : Class method Title : parse Usage : my $obj = Bio::Phylo::IO->parse(%options); Function: Creates (file) handle, instantiates appropriate parser. Returns : A Bio::Phylo::* object Args : -file => (path), or -string => (scalar), or -handle => (IO::Handle object) or -url => (url string) -format => (description format), -(other) => (parser specific options) Comments: The parse method makes assumptions about the capabilities of Bio::Phylo::Parsers::* modules: i) their names match those of the -format => (blah) arguments, insofar that ucfirst(blah) . '.pm' is an existing module; ii) the modules implement a _from_handle, or a _from_string method. Exceptions are thrown if either assumption is violated. If @ARGV contains even key/value pairs such as "format newick file <filename>" (note: no dashes) these will be prepended to @_, for one-liners.
Type : Class method Title : parse_matrix Usage : my $matrix = Bio::Phylo::IO->parse_matrix(%options); Function: Creates (file) handle, instantiates appropriate parser. Returns : A Bio::Phylo::Matrices::Matrix object Args : Same as parse() Comments: This method is syntactical sugar to get the first matrix out of a file/handle/string
Type : Class method Title : parse_tree Usage : my $tree = Bio::Phylo::IO->parse_tree(%options); Function: Creates (file) handle, instantiates appropriate parser. Returns : A Bio::Phylo::Forest::Tree object Args : Same as parse() Comments: This method is syntactical sugar to get the first tree out of a file/handle/string
Unparses object(s) to a string.
Type : Class method Title : unparse Usage : my $string = Bio::Phylo::IO->unparse( %options ); Function: Turns Bio::Phylo object into a string according to specified format. If an optional -file or -handle argument is provided the string is also written to that. Returns : SCALAR Args : -phylo => (Bio::Phylo object), -format => (description format), -(other) => (parser specific options) -file => (optional: a file path to open and write to) or -handle => (optional: a handle to write to)
Tests whether Bio::Phylo::IO can read provided syntax format.
Type : Class method Title : can_read Usage : &do_something if Bio::Phylo::IO->can_read('foo'); Function: Tests whether Bio::Phylo::IO can read provided syntax format. Returns : Boolean Args : A syntax format name, like "nexml"
Tests whether Bio::Phylo::IO can write provided syntax format.
Type : Class method Title : can_write Usage : &do_something if Bio::Phylo::IO->can_write('foo'); Function: Tests whether Bio::Phylo::IO can write provided syntax format. Returns : Boolean Args : A syntax format name, like "nexml"
There is a mailing list at https://groups.google.com/forum/#!forum/bio-phylo for any user or developer questions and discussions.
Also see the manual: Bio::Phylo::Manual and http://rutgervos.blogspot.com
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
To install Bio::Phylo, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Bio::Phylo
CPAN shell
perl -MCPAN -e shell install Bio::Phylo
For more information on module installation, please visit the detailed CPAN module installation guide.