Bio::Phylo::Taxa(3)

NAME
Bio::Phylo::Taxa - Container of taxon objects

SYNOPSIS
 use Bio::Phylo::Factory;
 my $fac = Bio::Phylo::Factory->new;

 # A mesquite-style default
 # taxa block for 10 taxa.
 my $taxa  = $fac->create_taxa;
 for my $i ( 1 .. 10 ) {
     $taxa->insert( $fac->create_taxon( '-name' => "taxon_${i}" ) );
 }

 # prints a taxa block in nexus format
 print $taxa->to_nexus;

DESCRIPTION
The Bio::Phylo::Taxa object models a set of operational taxonomic units. The object subclasses the Bio::Phylo::Listable object, and so the filtering methods of that class are available.

A taxa object can link to multiple forest and matrix objects.

METHODS

  CONSTRUCTOR

new()
    Taxa constructor.

     Type    : Constructor
     Title   : new
     Usage   : my $taxa = Bio::Phylo::Taxa->new;
     Function: Instantiates a Bio::Phylo::Taxa object.
     Returns : A Bio::Phylo::Taxa object.
     Args    : none.

  MUTATORS

set_forest()
    Sets associated Bio::Phylo::Forest object.

     Type    : Mutator
     Title   : set_forest
     Usage   : $taxa->set_forest( $forest );
     Function: Associates forest with the
               invocant taxa object (i.e.
               creates reference).
     Returns : Modified object.
     Args    : A Bio::Phylo::Forest object
     Comments: A taxa object can link to multiple
               forest and matrix objects.

set_matrix()
    Sets associated Bio::Phylo::Matrices::Matrix object.

     Type    : Mutator
     Title   : set_matrix
     Usage   : $taxa->set_matrix($matrix);
     Function: Associates matrix with the
               invocant taxa object (i.e.
               creates reference).
     Returns : Modified object.
     Args    : A Bio::Phylo::Matrices::Matrix object
     Comments: A taxa object can link to multiple
               forest and matrix objects.

unset_forest()
    Removes association with argument Bio::Phylo::Forest object.

     Type    : Mutator
     Title   : unset_forest
     Usage   : $taxa->unset_forest($forest);
     Function: Disassociates forest from the
               invocant taxa object (i.e.
               removes reference).
     Returns : Modified object.
     Args    : A Bio::Phylo::Forest object

unset_matrix()
    Removes association with Bio::Phylo::Matrices::Matrix object.

     Type    : Mutator
     Title   : unset_matrix
     Usage   : $taxa->unset_matrix($matrix);
     Function: Disassociates matrix from the
               invocant taxa object (i.e.
               removes reference).
     Returns : Modified object.
     Args    : A Bio::Phylo::Matrices::Matrix object

  ACCESSORS

get_forests()
    Gets all associated Bio::Phylo::Forest objects.

     Type    : Accessor
     Title   : get_forests
     Usage   : @forests = @{ $taxa->get_forests };
     Function: Retrieves forests associated
               with the current taxa object.
     Returns : An ARRAY reference of
               Bio::Phylo::Forest objects.
     Args    : None.

get_matrices()
    Gets all associated Bio::Phylo::Matrices::Matrix objects.

     Type    : Accessor
     Title   : get_matrices
     Usage   : @matrices = @{ $taxa->get_matrices };
     Function: Retrieves matrices associated
               with the current taxa object.
     Returns : An ARRAY reference of
               Bio::Phylo::Matrices::Matrix objects.
     Args    : None.

get_ntax()
    Gets number of contained Bio::Phylo::Taxa::Taxon objects.

     Type    : Accessor
     Title   : get_ntax
     Usage   : my $ntax = $taxa->get_ntax;
     Function: Retrieves the number of taxa for the invocant.
     Returns : INT
     Args    : None.
     Comments:

  METHODS

merge_by_name()
    Merges argument Bio::Phylo::Taxa object with invocant.

     Type    : Method
     Title   : merge_by_name
     Usage   : $merged = $taxa->merge_by_name($other_taxa);
     Function: Merges two or more taxa objects such that
               internally different taxon objects
               with the same name become a single
               object with the combined references
               to datum objects and node objects
               contained by the two.
     Returns : A merged Bio::Phylo::Taxa object.
     Args    : Bio::Phylo::Taxa objects.

merge_by_meta()
    Merges argument Bio::Phylo::Taxa object with invocant.

     Type    : Method
     Title   : merge_by_meta
     Usage   : $taxa->merge_by_name('dc:identifier',$other_taxa);
     Function: Merges two taxa objects such that
               internally different taxon objects
               with the same annotation value become
               a single object with the combined references
               to datum objects, node objects and
               metadata annotations contained by
               the two.
     Returns : A merged Bio::Phylo::Taxa object.
     Args    : a CURIE predicate and Bio::Phylo::Taxa objects.

prune_taxa()
    Removes taxa by name or object

     Type    : Method
     Title   : prune_taxa
     Usage   : $taxa->prune_taxa([$t1, $t2]);
     Function: Prunes taxa from the taxa object
     Returns : A pruned Bio::Phylo::Taxa object.
     Args    : An array reference of taxa, either by name or as taxon objects

to_nexus()
    Serializes invocant to nexus format.

     Type    : Format convertor
     Title   : to_nexus
     Usage   : my $block = $taxa->to_nexus;
     Function: Converts $taxa into a nexus taxa block.
     Returns : Nexus taxa block (SCALAR).
     Args    : -links => 1 (optional, adds 'TITLE' token)
     Comments:

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::Listable
    The Bio::Phylo::Taxa object inherits from the Bio::Phylo::Listable object. Look there for more methods applicable to the taxa object.

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>