NAME

Bio::Phylo::IO - Front end for parsers and serializers

SYNOPSIS

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
)->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

DESCRIPTION

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.

CLASS METHODS

parse()

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),
          -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.          

parse_matrix()

Parses a file or string.

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

parse_tree()

Parses a file or 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

unparse()

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.
Returns : SCALAR
Args    : -phylo   => (Bio::Phylo object),
          -format  => (description format),
          -(other) => (parser specific options)

can_read()

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"

can_write()

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"

SEE ALSO

There is a mailing list at https://groups.google.com/forum/#!forum/bio-phylo for any user or developer questions and discussions.

Bio::Phylo::Parsers::Fasta

Bio::Phylo::Parsers::Newick

Bio::Phylo::Parsers::Nexml

Bio::Phylo::Parsers::Nexus

Bio::Phylo::Parsers::Phylip

Bio::Phylo::Parsers::Phyloxml

Bio::Phylo::Parsers::Table

Bio::Phylo::Parsers::Taxlist

Bio::Phylo::Parsers::Tolweb

Bio::Phylo::Unparsers::Mrp

Bio::Phylo::Unparsers::Newick

Bio::Phylo::Unparsers::Nexml

Bio::Phylo::Unparsers::Nexus

Bio::Phylo::Unparsers::Pagel

Bio::Phylo::Unparsers::Phylip

Bio::Phylo::Unparsers::Phyloxml

Bio::Phylo::Manual

Also see the manual: Bio::Phylo::Manual and http://rutgervos.blogspot.com

CITATION

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