.\" Automatically generated by Pod::Man 4.11 (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
..
.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::TreeFunctionsI 3pm"
.TH Bio::Tree::TreeFunctionsI 3pm "2020-10-28" "perl v5.30.3" "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::TreeFunctionsI \- Decorated Interface implementing basic Tree exploration methods
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Bio::TreeIO;
\&  my $in = Bio::TreeIO\->new(\-format => \*(Aqnewick\*(Aq, \-file => \*(Aqtree.tre\*(Aq);
\&
\&  my $tree = $in\->next_tree;
\&
\&  my @nodes = $tree\->find_node(\*(Aqid1\*(Aq);
\&
\&  if( $tree\->is_monophyletic(\-nodes => \e@nodes, \-outgroup => $outnode) ){
\&   #...
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This interface provides a set of implemented Tree functions which
only use the defined methods in the TreeI or NodeI interface.
.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, Aaron Mackey, Justin Reese"
.IX Header "AUTHOR - Jason Stajich, Aaron Mackey, Justin Reese"
Email jason-at-bioperl-dot-org
Email amackey\-at\-virginia.edu
Email jtr4v\-at\-virginia.edu
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Sendu Bala, bix@sendu.me.uk
.PP
Rerooting code was worked on by
.PP
.Vb 2
\&  Daniel Barker d.barker\-at\-reading.ac.uk
\&  Ramiro Barrantes Ramiro.Barrantes\-at\-uvm.edu
.Ve
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "find_node"
.IX Subsection "find_node"
.Vb 8
\& Title   : find_node
\& Usage   : my @nodes = $self\->find_node(\-id => \*(Aqnode1\*(Aq);
\& Function: returns all nodes that match a specific field, by default this
\&           is id, but different branch_length, 
\& Returns : List of nodes which matched search
\& Args    : text string to search for
\&           OR
\&           \-fieldname => $textstring
.Ve
.SS "remove_Node"
.IX Subsection "remove_Node"
.Vb 5
\& Title   : remove_Node
\& Usage   : $tree\->remove_Node($node)
\& Function: Removes a node from the tree
\& Returns : boolean represent status of success
\& Args    : either Bio::Tree::NodeI or string of the node id
.Ve
.SS "get_lineage_nodes"
.IX Subsection "get_lineage_nodes"
.Vb 7
\& Title   : get_lineage_nodes
\& Usage   : my @nodes = $tree\->get_lineage_nodes($node);
\& Function: Given a node or its ID, get its full lineage, i.e. all its ancestors,
\&           from the root to the most recent ancestor. Only use the node ID as
\&           input if the nodes have been added to the tree.
\& Returns : list of nodes
\& Args    : either Bio::Tree::NodeI (or string of the node id)
.Ve
.SS "get_lineage_string"
.IX Subsection "get_lineage_string"
.Vb 10
\& Title   : get_lineage_string
\& Usage   : my $lineage = $tree\->get_lineage_string($node);
\& Function: Get the string representation of the full lineage of a node, e.g.
\&           for the Enterobacteriales node, return
\&           Bacteria;Proteobacteria;Gammaproteobacteria;Enterobacteriales.
\&           This method uses get_lineage_nodes internally and therefore inherits
\&           of all of its caveats.
\& Returns : string
\& Args    : * either Bio::Tree::NodeI (or string of the node id)
\&           * an optional separator (default: \*(Aq;\*(Aq)
.Ve
.SS "splice"
.IX Subsection "splice"
.Vb 10
\& Title   : splice
\& Usage   : $tree\->splice(\-remove_id => \e@ids);
\& Function: Remove all the nodes from a tree that correspond to the supplied
\&           args, making all the descendents of a removed node the descendents
\&           of the removed node\*(Aqs ancestor.
\&           You can ask to explicitly remove certain nodes by using \-remove_*,
\&           remove them conditionally by using \-remove_* in combination with
\&           \-keep_*, or remove everything except certain nodes by using only
\&           \-keep_*.
\& Returns : n/a
\& Args    : just a list of Bio::Tree::NodeI objects to remove, OR
\&           \-key => value pairs, where \-key has the prefix \*(Aqremove\*(Aq or \*(Aqkeep\*(Aq,
\&           followed by an underscore, followed by a fieldname (like for the
\&           method find_node). Value should be a scalar or an array ref of
\&           scalars (again, like you might supply to find_node).
\&
\&           So (\-remove_id => [1, 2]) will remove all nodes from the tree that
\&           have an id() of \*(Aq1\*(Aq or \*(Aq2\*(Aq, while
\&           (\-remove_id => [1, 2], \-keep_id => [2]) will remove all nodes with
\&           an id() of \*(Aq1\*(Aq.
\&           (\-keep_id => [2]) will remove all nodes unless they have an id() of
\&           \*(Aq2\*(Aq (note, no \-remove_*).
\&
\&           \-preserve_lengths => 1 : setting this argument will splice out
\&           intermediate nodes, preserving the original total length between
\&           the ancestor and the descendants of the spliced node. Undef 
\&           by default.
.Ve
.SS "get_lca"
.IX Subsection "get_lca"
.Vb 8
\& Title   : get_lca
\& Usage   : get_lca(\-nodes => \e@nodes ); OR
\&           get_lca(@nodes);
\& Function: given two or more nodes, returns the lowest common ancestor (aka most
\&           recent common ancestor)
\& Returns : node object or undef if there is no common ancestor
\& Args    : \-nodes => arrayref of nodes to test, OR
\&           just a list of nodes
.Ve
.SS "merge_lineage"
.IX Subsection "merge_lineage"
.Vb 6
\& Title   : merge_lineage
\& Usage   : merge_lineage($node)
\& Function: Merge a lineage of nodes with this tree.
\& Returns : true for success, false (and a warning) otherwise
\& Args    : Bio::Tree::TreeI with only one leaf, OR
\&           Bio::Tree::NodeI which has an ancestor
\&
\& For example, if we are the tree $tree:
\&
\& +\-\-\-B
\& |
\& A
\& |
\& +\-\-\-C
\&
\& and we want to merge the lineage $other_tree:
\&
\& A\-\-\-C\-\-\-D
\&
\& After calling $tree\->merge_lineage($other_tree), $tree looks like:
\&
\& +\-\-\-B
\& |
\& A
\& |
\& +\-\-\-C\-\-\-D
.Ve
.SS "contract_linear_paths"
.IX Subsection "contract_linear_paths"
.Vb 7
\& Title   : contract_linear_paths
\& Usage   : contract_linear_paths()
\& Function: Splices out all nodes in the tree that have an ancestor and only one
\&           descendent.
\& Returns : n/a
\& Args    : none for normal behaviour, true to dis\-regard the ancestor requirement
\&           and re\-root the tree as necessary
\&
\& For example, if we are the tree $tree:
\&
\&             +\-\-\-E
\&             |
\& A\-\-\-B\-\-\-C\-\-\-D
\&             |
\&             +\-\-\-F
\&
\& After calling $tree\->contract_linear_paths(), $tree looks like:
\&
\&     +\-\-\-E
\&     |
\& A\-\-\-D
\&     |
\&     +\-\-\-F
\&
\& Instead, $tree\->contract_linear_paths(1) would have given:
\&
\& +\-\-\-E
\& |
\& D
\& |
\& +\-\-\-F
.Ve
.SS "is_binary"
.IX Subsection "is_binary"
.Vb 7
\&  Example    : is_binary(); is_binary($node);
\&  Description: Finds if the tree or subtree defined by
\&               the internal node is a true binary tree
\&               without polytomies
\&  Returns    : boolean
\&  Exceptions : 
\&  Args       : Internal node Bio::Tree::NodeI, optional
.Ve
.SS "force_binary"
.IX Subsection "force_binary"
.Vb 7
\& Title   : force_binary
\& Usage   : force_binary()
\& Function: Forces the tree into a binary tree, splitting branches arbitrarily
\&           and creating extra nodes as necessary, such that all nodes have
\&           exactly two or zero descendants.
\& Returns : n/a
\& Args    : none
\&
\& For example, if we are the tree $tree:
\&
\& +\-\-\-G
\& |
\& +\-\-\-F
\& |
\& +\-\-\-E
\& |
\& A
\& |
\& +\-\-\-D
\& |
\& +\-\-\-C
\& |
\& +\-\-\-B
\&
\& (A has 6 descendants B\-G)
\&
\& After calling $tree\->force_binary(), $tree looks like:
\&
\&         +\-\-\-X
\&         |
\&     +\-\-\-X
\&     |   |
\&     |   +\-\-\-X
\&     |
\& +\-\-\-X
\& |   |
\& |   |   +\-\-\-G
\& |   |   |
\& |   +\-\-\-X
\& |       |
\& |       +\-\-\-F
\& A
\& |       +\-\-\-E
\& |       |
\& |   +\-\-\-X
\& |   |   |
\& |   |   +\-\-\-D
\& |   |
\& +\-\-\-X
\&     |
\&     |   +\-\-\-C
\&     |   |
\&     +\-\-\-X
\&         |
\&         +\-\-\-B
\&
\& (Where X are artificially created nodes with ids \*(Aqartificial_n\*(Aq, where n is
\& an integer making the id unique within the tree)
.Ve
.SS "simplify_to_leaves_string"
.IX Subsection "simplify_to_leaves_string"
.Vb 9
\& Title   : simplify_to_leaves_string
\& Usage   : my $leaves_string = $tree\->simplify_to_leaves_string()
\& Function: Creates a simple textual representation of the relationship between
\&           leaves in self. It forces the tree to be binary, so the result may
\&           not strictly correspond to the tree (if the tree wasn\*(Aqt binary), but
\&           will be as close as possible. The tree object is not altered. Only
\&           leaf node ids are output, in a newick\-like format.
\& Returns : string
\& Args    : none
.Ve
.SS "distance"
.IX Subsection "distance"
.Vb 6
\& Title   : distance
\& Usage   : distance(\-nodes => \e@nodes )
\& Function: returns the distance between two given nodes
\& Returns : numerical distance
\& Args    : \-nodes => arrayref of nodes to test
\&           or ($node1, $node2)
.Ve
.SS "is_monophyletic"
.IX Subsection "is_monophyletic"
.Vb 8
\& Title   : is_monophyletic
\& Usage   : if( $tree\->is_monophyletic(\-nodes => \e@nodes, 
\&                                      \-outgroup => $outgroup)
\& Function: Will do a test of monophyly for the nodes specified
\&           in comparison to a chosen outgroup
\& Returns : boolean
\& Args    : \-nodes    => arrayref of nodes to test
\&           \-outgroup => outgroup to serve as a reference
.Ve
.SS "is_paraphyletic"
.IX Subsection "is_paraphyletic"
.Vb 10
\& Title   : is_paraphyletic
\& Usage   : if( $tree\->is_paraphyletic(\-nodes =>\e@nodes,
\&                                      \-outgroup => $node) ){ }
\& Function: Tests whether or not a given set of nodes are paraphyletic
\&           (representing the full clade) given an outgroup
\& Returns : [\-1,0,1] , \-1 if the group is not monophyletic
\&                       0 if the group is not paraphyletic
\&                       1 if the group is paraphyletic
\& Args    : \-nodes => Array of Bio::Tree::NodeI objects which are in the tree
\&           \-outgroup => a Bio::Tree::NodeI to compare the nodes to
.Ve
.SS "reroot"
.IX Subsection "reroot"
.Vb 5
\& Title   : reroot
\& Usage   : $tree\->reroot($node);
\& Function: Reroots a tree making a new node the root
\& Returns : 1 on success, 0 on failure
\& Args    : Bio::Tree::NodeI that is in the tree, but is not the current root
.Ve
.SS "reroot_at_midpoint"
.IX Subsection "reroot_at_midpoint"
.Vb 7
\& Title   : reroot_at_midpoint
\& Usage   : $tree\->reroot_at_midpoint($node, $new_root_id);
\& Function: Reroots a tree on a new node created halfway between the 
\&           argument and its ancestor
\& Returns : the new midpoint Bio::Tree::NodeIon success, 0 on failure
\& Args    : non\-root Bio::Tree::NodeI currently in $tree
\&           scalar string, id for new node (optional)
.Ve
.SS "findnode_by_id"
.IX Subsection "findnode_by_id"
.Vb 6
\& Title   : findnode_by_id
\& Usage   : my $node = $tree\->findnode_by_id($id);
\& Function: Get a node by its id (which should be 
\&           unique for the tree)
\& Returns : L<Bio::Tree::NodeI>
\& Args    : node id
.Ve
.SS "move_id_to_bootstrap"
.IX Subsection "move_id_to_bootstrap"
.Vb 5
\& Title   : move_id_to_bootstrap
\& Usage   : $tree\->move_id_to_bootstrap
\& Function: Move internal IDs to bootstrap slot
\& Returns : undef
\& Args    : undef
.Ve
.SS "add_trait"
.IX Subsection "add_trait"
.Vb 10
\& Title   : add_trait
\& Usage   : my $key = $tree\->add_trait($trait_file, 3);
\& Function: Add traits to the leaf nodes of a Bio::Tree:Tree from a file.
\&           The trait file is a tab\-delimited text file and needs to have a
\&           header line giving names to traits. The first column contains the
\&           leaf node ids. Subsequent columns contain different trait value sets.
\&           Single or double quotes are removed from the trait values. Traits
\&           are added to leaf nodes as a tag named $key using the add_tag_value()
\&           method. This means that you can retrieve the trait values using the
\&           get_tag_values() method (see the documentation for Bio::Tree::Node).
\& Returns : Trait name (a scalar) on success, undef on failure (for example, if
\&           the column index requested was too large).
\& Args    : * Name of trait file (scalar string).
\&           * Index of trait file column (scalar int). Note that numbering starts
\&             at 0. Default: 1 (second column).
\&           * Ignore missing values. Typically, if a leaf node has no value in
\&             the trait file, an exception is thrown. If you set this option to
\&             1, then no trait will be given to the node (no exception thrown).
.Ve