.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Tree::Node 3pm"
.TH Bio::Tree::Node 3pm "2021-08-15" "perl v5.32.1" "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::Tree::Node \- A Simple Tree Node
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    use Bio::Tree::Node;
\&    my $nodeA = Bio::Tree::Node\->new();
\&    my $nodeL = Bio::Tree::Node\->new();
\&    my $nodeR = Bio::Tree::Node\->new();
\&
\&    my $node = Bio::Tree::Node\->new();
\&    $node\->add_Descendent($nodeL);
\&    $node\->add_Descendent($nodeR);
\&
\&    print "node is not a leaf \en" if( $node\->is_leaf);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Makes a Tree Node suitable for building a Tree.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to
the Bioperl mailing list.  Your participation is much appreciated.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
rather than to the module maintainer directly. Many experienced and 
reponsive experts will be able look at the problem and quickly 
address it. Please include a thorough description of the problem 
with code and data examples if at all possible.
.SS "Reporting Bugs"
.IX Subsection "Reporting Bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
of the bugs and their resolution. Bug reports can be submitted via
the web:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Jason Stajich"
.IX Header "AUTHOR - Jason Stajich"
Email jason-at-bioperl-dot-org
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Aaron Mackey, amackey-at-virginia-dot-edu
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 11
\& Title   : new
\& Usage   : my $obj = Bio::Tree::Node\->new();
\& Function: Builds a new Bio::Tree::Node object
\& Returns : Bio::Tree::Node
\& Args    : \-descendents   => arrayref of descendents (they will be
\&                             updated s.t. their ancestor point is this
\&                             node)
\&           \-branch_length => branch length [integer] (optional)
\&           \-bootstrap     => value   bootstrap value (string)
\&           \-description   => description of node
\&           \-id            => human readable id for node
.Ve
.SS "create_node_on_branch"
.IX Subsection "create_node_on_branch"
.Vb 10
\& Title   : create_node_on_branch
\& Usage   : $node\->create_node_on_branch($at_length)
\& Function: Create a node on the ancestral branch of the calling
\&           object. 
\& Example :
\& Returns : the created node
\& Args    : \-POSITION=>$absolute_branch_length_from_caller (default)
\&           \-FRACTION=>$fraction_of_branch_length_from_caller
\&           \-ANNOT=>{ \-id => "the id", \-desc => "the description" }
\&           \-FORCE, set to allow nodes with zero branch lengths
.Ve
.SS "add_Descendent"
.IX Subsection "add_Descendent"
.Vb 9
\& Title   : add_Descendent
\& Usage   : $node\->add_Descendent($node);
\& Function: Adds a descendent to a node
\& Returns : number of current descendents for this node
\& Args    : Bio::Node::NodeI
\&           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 @nodes = $node\->each_Descendent;
\& Function: all the descendents for this Node (but not their descendents
\&                                              i.e. not a recursive fetchall)
\& Returns : Array of Bio::Tree::NodeI objects
\& Args    : $sortby [optional] "height", "creation", "alpha", "revalpha",
\&           or coderef to be used to sort the order of children nodes.
.Ve
.SS "remove_Descendent"
.IX Subsection "remove_Descendent"
.Vb 6
\& Title   : remove_Descendent
\& Usage   : $node\->remove_Descendent($node_foo);
\& Function: Removes a specific node from being a Descendent of this node
\& Returns : nothing
\& Args    : An array of Bio::Node::NodeI objects which have been 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   : $node\->remove_All_Descendents()
\& Function: Cleanup the node\*(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 cleaned up \- so
\&           a get_nodes from the Tree object would be a safe thing to do first
\& Returns : nothing
\& Args    : none
.Ve
.SS "get_all_Descendents"
.IX Subsection "get_all_Descendents"
.Vb 6
\& Title   : get_all_Descendents
\& Usage   : my @nodes = $node\->get_all_Descendents;
\& Function: Recursively fetch all the nodes and their descendents
\&           *NOTE* This is different from each_Descendent
\& Returns : Array or Bio::Tree::NodeI objects
\& Args    : none
.Ve
.SS "ancestor"
.IX Subsection "ancestor"
.Vb 5
\& Title   : ancestor
\& Usage   : $obj\->ancestor($newval)
\& Function: Set the Ancestor
\& Returns : ancestral node
\& Args    : newvalue (optional)
.Ve
.SS "branch_length"
.IX Subsection "branch_length"
.Vb 5
\& Title   : branch_length
\& Usage   : $obj\->branch_length()
\& Function: Get/Set the branch length
\& Returns : value of branch_length
\& Args    : newvalue (optional)
.Ve
.SS "bootstrap"
.IX Subsection "bootstrap"
.Vb 5
\& Title   : bootstrap
\& Usage   : $obj\->bootstrap($newval)
\& Function: Get/Set the bootstrap value
\& Returns : value of bootstrap
\& Args    : newvalue (optional)
.Ve
.SS "description"
.IX Subsection "description"
.Vb 5
\& Title   : description
\& Usage   : $obj\->description($newval)
\& Function: Get/Set the description string
\& Returns : value of description
\& Args    : newvalue (optional)
.Ve
.SS "id"
.IX Subsection "id"
.Vb 5
\& Title   : id
\& Usage   : $obj\->id($newval)
\& Function: The human readable identifier for the node 
\& Returns : value of human readable id
\& Args    : newvalue (optional)
.Ve
.PP
\&\*(L"A name can be any string of printable characters except blanks,
colons, semicolons, parentheses, and square brackets. Because you may
want to include a blank in a name, it is assumed that an underscore
character (\*(R"_\*(L") stands for a blank; any of these in a name will be
converted to a blank when it is read in.\*(R"
.PP
from <http://evolution.genetics.washington.edu/phylip/newicktree.html>
.PP
Also note that these objects now support spaces, ();: because we can
automatically quote the strings if they contain these characters.  The
id_output method does this for you so use the \fBid()\fR method to get
the raw string while id_output to get the pre-escaped string.
.SS "Helper Functions"
.IX Subsection "Helper Functions"
.SS "id_output"
.IX Subsection "id_output"
.Vb 7
\& Title   : id_output
\& Usage   : my $id = $node\->id_output;
\& Function: Return an id suitable for output in format like newick
\&           so that if it contains spaces or ():; characters it is properly 
\&           quoted
\& Returns : $id string if $node\->id has a value
\& Args    : none
.Ve
.SS "internal_id"
.IX Subsection "internal_id"
.Vb 8
\& Title   : internal_id
\& Usage   : my $internalid = $node\->internal_id
\& Function: Returns the internal unique id for this Node
\&           (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 "Bio::Node::NodeI decorated interface implemented"
.IX Subsection "Bio::Node::NodeI decorated interface implemented"
The following methods are implemented by Bio::Node::NodeI decorated
interface.
.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 "height"
.IX Subsection "height"
.Vb 6
\& Title   : height
\& Usage   : my $len = $node\->height
\& Function: Returns the height of the tree starting at this
\&           node.  Height is the maximum branchlength to get to the tip.
\& 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 node height in the tree
\& Returns : nothing
\& Args    : none
.Ve
.SS "set_tag_value"
.IX Subsection "set_tag_value"
.Vb 7
\& Title   : set_tag_value
\& Usage   : $node\->set_tag_value($tag,$value)
\&           $node\->set_tag_value($tag,@values)
\& Function: Sets a tag value(s) to a node. Replaces old values.
\& Returns : number of values stored for this tag
\& Args    : $tag   \- tag name
\&           $value \- value to store for the tag
.Ve
.SS "add_tag_value"
.IX Subsection "add_tag_value"
.Vb 6
\& Title   : add_tag_value
\& Usage   : $node\->add_tag_value($tag,$value)
\& Function: Adds a tag value to a node 
\& Returns : number of values stored for this tag
\& Args    : $tag   \- tag name
\&           $value \- value to store for the tag
.Ve
.SS "remove_tag"
.IX Subsection "remove_tag"
.Vb 5
\& Title   : remove_tag
\& Usage   : $node\->remove_tag($tag)
\& Function: Remove the tag and all values for this tag
\& Returns : boolean representing success (0 if tag does not exist)
\& Args    : $tag \- tagname to remove
.Ve
.SS "remove_all_tags"
.IX Subsection "remove_all_tags"
.Vb 5
\& Title   : remove_all_tags
\& Usage   : $node\->remove_all_tags()
\& Function: Removes all tags
\& Returns : None
\& Args    : None
.Ve
.SS "get_all_tags"
.IX Subsection "get_all_tags"
.Vb 5
\& Title   : get_all_tags
\& Usage   : my @tags = $node\->get_all_tags()
\& Function: Gets all the tag names for this Node
\& Returns : Array of tagnames
\& Args    : None
.Ve
.SS "get_tag_values"
.IX Subsection "get_tag_values"
.Vb 7
\& Title   : get_tag_values
\& Usage   : my @values = $node\->get_tag_values($tag)
\& Function: Gets the values for given tag ($tag)
\& Returns : In array context returns an array of values
\&           or an empty list if tag does not exist.
\&           In scalar context returns the first value or undef.
\& Args    : $tag \- tag name
.Ve
.SS "has_tag"
.IX Subsection "has_tag"
.Vb 5
\& Title   : has_tag
\& Usage   : $node\->has_tag($tag)
\& Function: Boolean test if tag exists in the Node
\& Returns : Boolean
\& Args    : $tag \- tagname
.Ve
.SS "reverse_edge"
.IX Subsection "reverse_edge"
.Vb 6
\& Title   : reverse_edge
\& Usage   : $node\->reverse_edge(child);
\& Function: makes child be a parent of node
\& Requires: child must be a direct descendent of node
\& Returns : 1 on success, 0 on failure
\& Args    : Bio::Tree::NodeI that is in the tree
.Ve