NAME

Bio::Phylo::IO - Input and output of phylogenetic data.

SYNOPSIS

use Bio::Phylo::IO;
use Data::Dumper;

# 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 parser returns 'Bio::Phylo::Forest'! Call ->first to retrieve
# the first tree of the forest.

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

# 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',
   -type     => 'STANDARD',  # Data type, see Bio::Phylo::Parsers::Table
   -fieldsep => ',',         # field separator
   -linesep  => '|'          # line separator
);

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

# 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'

# unparsing to pagel format
$tree->cross_reference($taxa);    # matches taxon names in tree to $taxa object
$matrix->cross_reference($taxa);  # ditto for matrix

print Bio::Phylo::IO->unparse(
   -phylo => $tree,     # pass the tree object, crossreferenced to taxa, which
                        # are crossreferenced to the matrix
   -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 unified front end for parsing and unparsing 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, as in the synopsis. The parse and unparse subroutines load and dispatch the appropriate sub-modules at runtime, depending on the '-format' argument.

CLASS METHODS

parse()

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.

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)

unparse()

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)

SEE ALSO

Bio::Phylo::Parsers::Newick

Bio::Phylo::Parsers::Nexus

Bio::Phylo::Parsers::Table

Bio::Phylo::Parsers::Taxlist

Bio::Phylo::Unparsers::Newick

Bio::Phylo::Unparsers::Pagel

Bio::Phylo::Manual

Also see the manual: Bio::Phylo::Manual.

FORUM

CPAN hosts a discussion forum for Bio::Phylo. If you have trouble using this module the discussion forum is a good place to start posting questions (NOT bug reports, see below): http://www.cpanforum.com/dist/Bio-Phylo

BUGS

Please report any bugs or feature requests to bug-bio-phylo@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bio-Phylo. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. Be sure to include the following in your request or comment, so that I know what version you're using:

$Id: IO.pm,v 1.10 2005/09/29 20:31:17 rvosa Exp $

AUTHOR

Rutger A. Vos,

email: rvosa@sfu.ca

web page: http://www.sfu.ca/~rvosa/

ACKNOWLEDGEMENTS

The author would like to thank Jason Stajich for many ideas borrowed from BioPerl http://www.bioperl.org, and CIPRES http://www.phylo.org and FAB* http://www.sfu.ca/~fabstar for comments and requests.

COPYRIGHT & LICENSE

Copyright 2005 Rutger A. Vos, All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.