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

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

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

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"

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>

NAME

SYNOPSIS

DESCRIPTION

CLASS METHODS

SEE ALSO

CITATION