.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::Taxonomy::Taxon 3pm"
.TH Bio::Taxonomy::Taxon 3pm "2018-10-27" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Taxonomy::Taxon \- Generic Taxonomic Entity object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    # 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;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Makes a taxonomic unit suitable for use in a taxonomic tree
.SH "AUTHOR"
.IX Header "AUTHOR"
Dan Kortschak email \fBkortschak@rsbs.anu.edu.au\fR
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Sendu Bala: bix@sendu.me.uk
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _
.SS "new"
.IX Subsection "new"
.Vb 9
\& 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\*(Aqs list preferably)
\&           \-rank  => the taxonomic level of the node (also from NCBI)
.Ve
.SS "add_Descendent"
.IX Subsection "add_Descendent"
.Vb 9
\& 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.
.Ve
.SS "each_Descendent"
.IX Subsection "each_Descendent"
.Vb 7
\& 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.
.Ve
.SS "remove_Descendent"
.IX Subsection "remove_Descendent"
.Vb 6
\& 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.
.Ve
.SS "remove_all_Descendents"
.IX Subsection "remove_all_Descendents"
.Vb 8
\& Title   : remove_all_Descendents
\& Usage   : $taxon\->remove_All_Descendents()
\& Function: Cleanup the taxon\*(Aqs reference to descendents and reset
\&           their ancestor pointers to undef, if you don\*(Aqt 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
.Ve
.SS "get_Descendents"
.IX Subsection "get_Descendents"
.Vb 6
\& 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
.Ve
.SS "ancestor"
.IX Subsection "ancestor"
.Vb 5
\& Title   : ancestor
\& Usage   : $taxon\->ancestor($newval)
\& Function: Set the Ancestor
\& Returns : value of ancestor
\& Args    : newvalue (optional)
.Ve
.SS "branch_length"
.IX Subsection "branch_length"
.Vb 6
\& Title   : branch_length
\& Usage   : $obj\->branch_length($newval)
\& Function:
\& Example :
\& Returns : value of branch_length
\& Args    : newvalue (optional)
.Ve
.SS "description"
.IX Subsection "description"
.Vb 5
\& Title   : description
\& Usage   : $obj\->description($newval)
\& Function:
\& Returns : value of description
\& Args    : newvalue (optional)
.Ve
.SS "rank"
.IX Subsection "rank"
.Vb 5
\& Title   : rank
\& Usage   : $obj\->rank($newval)
\& Function: Set the taxonomic rank
\& Returns : taxonomic rank of taxon
\& Args    : newvalue (optional)
.Ve
.SS "taxon"
.IX Subsection "taxon"
.Vb 6
\& Title   : taxon
\& Usage   : $obj\->taxon($newtaxon)
\& Function: Set the name of the taxon
\& Example :
\& Returns : name of taxon
\& Args    : newtaxon (optional)
.Ve
.SS "id"
.IX Subsection "id"
.Vb 6
\& Title   : id
\& Usage   : $obj\->id($newval)
\& Function:
\& Example :
\& Returns : value of id
\& Args    : newvalue (optional)
.Ve
.SS "internal_id"
.IX Subsection "internal_id"
.Vb 8
\& 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
.Ve
.SS "_creation_id"
.IX Subsection "_creation_id"
.Vb 5
\& 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)
.Ve
.SS "is_Leaf"
.IX Subsection "is_Leaf"
.Vb 5
\& Title   : is_Leaf
\& Usage   : if( $node\->is_Leaf )
\& Function: Get Leaf status
\& Returns : boolean
\& Args    : none
.Ve
.SS "to_string"
.IX Subsection "to_string"
.Vb 5
\& Title   : to_string
\& Usage   : my $str = $taxon\->to_string()
\& Function: For debugging, provide a taxon as a string
\& Returns : string
\& Args    : none
.Ve
.SS "height"
.IX Subsection "height"
.Vb 6
\& 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
.Ve
.SS "invalidate_height"
.IX Subsection "invalidate_height"
.Vb 5
\& Title   : invalidate_height
\& Usage   : private helper method
\& Function: Invalidate our cached value of the taxon\*(Aqs height in the tree
\& Returns : nothing
\& Args    : none
.Ve
.SS "classify"
.IX Subsection "classify"
.Vb 6
\& Title   : classify
\& Usage   : @obj\->classify()
\& Function: a method to return the classification of a species
\& Returns : name of taxon and ancestor\*(Aqs taxon recursively
\& Args    : boolean to specify whether we want all taxa not just ranked 
\&           levels
.Ve
.SS "has_rank"
.IX Subsection "has_rank"
.Vb 5
\& Title   : has_rank
\& Usage   : $obj\->has_rank($rank)
\& Function: a method to query ancestors\*(Aq rank
\& Returns : boolean
\& Args    : $rank
.Ve
.SS "has_taxon"
.IX Subsection "has_taxon"
.Vb 5
\& Title   : has_taxon
\& Usage   : $obj\->has_taxon($taxon)
\& Function: a method to query ancestors\*(Aq taxa
\& Returns : boolean
\& Args    : Bio::Taxonomy::Taxon object
.Ve
.SS "distance_to_root"
.IX Subsection "distance_to_root"
.Vb 5
\& Title   : distance_to_root
\& Usage   : $obj\->distance_to_root
\& Function: a method to query ancestors\*(Aq taxa
\& Returns : number of links to root
\& Args    :
.Ve
.SS "recent_common_ancestor"
.IX Subsection "recent_common_ancestor"
.Vb 5
\& 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
.Ve
.SS "species"
.IX Subsection "species"
.Vb 5
\& Title   : species
\& Usage   : $obj=$taxon\->species;
\& Function: Returns a Bio::Species object reflecting the taxon\*(Aqs tree position
\& Returns : a Bio::Species object
\& Args    : none
.Ve