NAME

       Bio::Taxonomy::Taxon - Generic Taxonomic Entity object

SYNOPSIS

           # NB: This module is deprecated. Use Bio::Taxon instead.

           use Bio::Taxonomy::Taxon;
           my $taxonA = Bio::Taxonomy::Taxon->new();
           my $taxonL = Bio::Taxonomy::Taxon->new();
           my $taxonR = Bio::Taxonomy::Taxon->new();

           my $taxon = Bio::Taxonomy::Taxon->new();
           $taxon->add_Descendents($taxonL);
           $taxon->add_Descendents($taxonR);

           my $species = $taxon->species;

DESCRIPTION

       Makes a taxonomic unit suitable for use in a taxonomic tree

AUTHOR

       Dan Kortschak email kortschak@rsbs.anu.edu.au

CONTRIBUTORS

       Sendu Bala: bix@sendu.me.uk

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

   new
        Title   : new
        Usage   : my $obj = Bio::Taxonomy::Taxon->new();
        Function: Builds a new Bio::Taxonomy::Taxon object
        Returns : Bio::Taxonomy::Taxon
        Args    : -descendents   => array pointer to descendents (optional)
                  -branch_length => branch length [integer] (optional)
                  -taxon     => taxon
                  -id     => unique taxon id for node (from NCBI's list preferably)
                  -rank  => the taxonomic level of the node (also from NCBI)

   add_Descendent
        Title   : add_Descendent
        Usage   : $taxon->add_Descendent($taxon);
        Function: Adds a descendent to a taxon
        Returns : number of current descendents for this taxon
        Args    : Bio::Taxonomy::Taxon
                  boolean flag, true if you want to ignore the fact that you are
                  adding a second node with the same unique id (typically memory
                  location reference in this implementation).  default is false and
                  will throw an error if you try and overwrite an existing node.

   each_Descendent
        Title   : each_Descendent($sortby)
        Usage   : my @taxa = $taxon->each_Descendent;
        Function: all the descendents for this taxon (but not their descendents
                                                     i.e. not a recursive fetchall)
        Returns : Array of Bio::Taxonomy::Taxon objects
        Args    : $sortby [optional] "height", "creation" or coderef to be used
                  to sort the order of children taxa.

   remove_Descendent
        Title   : remove_Descendent
        Usage   : $taxon->remove_Descedent($taxon_foo);
        Function: Removes a specific taxon from being a Descendent of this taxon
        Returns : nothing
        Args    : An array of Bio::taxonomy::Taxon objects which have be previously
                  passed to the add_Descendent call of this object.

   remove_all_Descendents
        Title   : remove_all_Descendents
        Usage   : $taxon->remove_All_Descendents()
        Function: Cleanup the taxon's reference to descendents and reset
                  their ancestor pointers to undef, if you don't have a reference
                  to these objects after this call they will be cleanedup - so
                  a get_nodes from the Tree object would be a safe thing to do first
        Returns : nothing
        Args    : none

   get_Descendents
        Title   : get_Descendents
        Usage   : my @taxa = $taxon->get_Descendents;
        Function: Recursively fetch all the taxa and their descendents
                  *NOTE* This is different from each_Descendent
        Returns : Array or Bio::Taxonomy::Taxon objects
        Args    : none

   ancestor
        Title   : ancestor
        Usage   : $taxon->ancestor($newval)
        Function: Set the Ancestor
        Returns : value of ancestor
        Args    : newvalue (optional)

   branch_length
        Title   : branch_length
        Usage   : $obj->branch_length($newval)
        Function:
        Example :
        Returns : value of branch_length
        Args    : newvalue (optional)

   description
        Title   : description
        Usage   : $obj->description($newval)
        Function:
        Returns : value of description
        Args    : newvalue (optional)

   rank
        Title   : rank
        Usage   : $obj->rank($newval)
        Function: Set the taxonomic rank
        Returns : taxonomic rank of taxon
        Args    : newvalue (optional)

   taxon
        Title   : taxon
        Usage   : $obj->taxon($newtaxon)
        Function: Set the name of the taxon
        Example :
        Returns : name of taxon
        Args    : newtaxon (optional)

   id
        Title   : id
        Usage   : $obj->id($newval)
        Function:
        Example :
        Returns : value of id
        Args    : newvalue (optional)

   internal_id
        Title   : internal_id
        Usage   : my $internalid = $taxon->internal_id
        Function: Returns the internal unique id for this taxon
                  (a monotonically increasing number for this in-memory implementation
                   but could be a database determined unique id in other
                   implementations)
        Returns : unique id
        Args    : none

   _creation_id
        Title   : _creation_id
        Usage   : $obj->_creation_id($newval)
        Function: a private method signifying the internal creation order
        Returns : value of _creation_id
        Args    : newvalue (optional)

   is_Leaf
        Title   : is_Leaf
        Usage   : if( $node->is_Leaf )
        Function: Get Leaf status
        Returns : boolean
        Args    : none

   to_string
        Title   : to_string
        Usage   : my $str = $taxon->to_string()
        Function: For debugging, provide a taxon as a string
        Returns : string
        Args    : none

   height
        Title   : height
        Usage   : my $len = $taxon->height
        Function: Returns the height of the tree starting at this
                  taxon.  Height is the maximum branchlength.
        Returns : The longest length (weighting branches with branch_length) to a leaf
        Args    : none

   invalidate_height
        Title   : invalidate_height
        Usage   : private helper method
        Function: Invalidate our cached value of the taxon's height in the tree
        Returns : nothing
        Args    : none

   classify
        Title   : classify
        Usage   : @obj->classify()
        Function: a method to return the classification of a species
        Returns : name of taxon and ancestor's taxon recursively
        Args    : boolean to specify whether we want all taxa not just ranked
                  levels

   has_rank
        Title   : has_rank
        Usage   : $obj->has_rank($rank)
        Function: a method to query ancestors' rank
        Returns : boolean
        Args    : $rank

   has_taxon
        Title   : has_taxon
        Usage   : $obj->has_taxon($taxon)
        Function: a method to query ancestors' taxa
        Returns : boolean
        Args    : Bio::Taxonomy::Taxon object

   distance_to_root
        Title   : distance_to_root
        Usage   : $obj->distance_to_root
        Function: a method to query ancestors' taxa
        Returns : number of links to root
        Args    :

   recent_common_ancestor
        Title   : recent_common_ancestor
        Usage   : $obj->recent_common_ancestor($taxon)
        Function: a method to query find common ancestors
        Returns : Bio::Taxonomy::Taxon of query or undef if no ancestor of rank
        Args    : Bio::Taxonomy::Taxon

   species
        Title   : species
        Usage   : $obj=$taxon->species;
        Function: Returns a Bio::Species object reflecting the taxon's tree position
        Returns : a Bio::Species object
        Args    : none