Bio::T...ctionsI(3pm)

💖 Bio::Tree::TreeFunctionsI — the manual, but make it a group chat 💖

okay so this is the user-contributed Perl documentation for Bio::Tree::TreeFunctionsI, and bestie, we are going to get you so comfortable with tree exploration. no cap. 🌳✨

---

🌸 NAME 🌸

Bio::Tree::TreeFunctionsI — a decorated interface that implements the basic tree exploration methods. it's giving "interface, but make it useful." 💅

---

🎀 SYNOPSIS 🎀

here's the vibe, copy-paste it, you got this:

use Bio::TreeIO;
my $in = Bio::TreeIO->new(-format => 'newick', -file => 'tree.tre');

my $tree = $in->next_tree;

my @nodes = $tree->find_node('id1');

if( $tree->is_monophyletic(-nodes => \@nodes, -outgroup => $outnode) ){
 #...
}

like. read a newick file, grab the tree, find your nodes, check if they're monophyletic. iconic behavior fr fr. 🦋

---

✨ DESCRIPTION ✨

this interface hands you a whole set of already implemented tree functions. and the way that it does it? 🥹 it only ever uses the methods that are actually defined in the TreeI or NodeI interface. so it's self-contained, it plays nice, it doesn't go reaching into random internals. queen behavior. 👑

---

💌 FEEDBACK 💌

🌈 Mailing Lists 🌈

user feedback is literally an integral part of the evolution of this and other Bioperl modules. no seriously, your comments and suggestions are wanted. send them preferably to the Bioperl mailing list. your participation is so appreciated, i cannot stress this enough 🫶

bioperl-l@bioperl.org                  - General discussion
http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

🩷 Support 🩷

okay bestie, please direct usage questions and support issues to the mailing list:

bioperl-l@bioperl.org

rather than going straight to the module maintainer. lowkey this is the move because so many experienced and responsive experts will be able to look at the problem and quickly address it. 💖

and if at all possible, include a thorough description of the problem, plus code and data examples. the more context, the faster the slay. 📝

🐛 Reporting Bugs 🐛

report bugs to the Bioperl bug tracking system so we can keep track of the bugs and their resolution. bug reports can be submitted via the web:

https://github.com/bioperl/bioperl-live/issues

go off, tell them everything. 🙈

---

👑 AUTHOR - Jason Stajich, Aaron Mackey, Justin Reese 👑

Email jason-at-bioperl-dot-org Email amackey-at-virginia.edu Email jtr4v-at-virginia.edu

---

🌟 CONTRIBUTORS 🌟

Sendu Bala, bix@sendu.me.uk

rerooting code was worked on by:

Daniel Barker d.barker-at-reading.ac.uk
Ramiro Barrantes Ramiro.Barrantes-at-uvm.edu

legends, honestly. 💜

---

part 2 is coming, bestie — don't go anywhere, we're just getting started ✨

✨ APPENDIX ✨

okay so the rest of this doc is the deep-dive on every single object method, one by one 💖 internal methods usually start with an underscore (_), so if you see that, it's a "you probably shouldn't be here unless you know what you're doing" situation, bestie.

---

find_node

• Title: find_node
• Usage: my @nodes = $self->find_node(-id => 'node1');
• Function: hands you back every node that matches a specific field — by default that field is id, but it can be different, like branch_length
• Returns: a list of nodes that matched the search
• Args: a text string to search for, OR -fieldname => $textstring

remove_Node

• Title: remove_Node
• Usage: $tree->remove_Node($node)
• Function: removes a node from the tree
• Returns: boolean, so it tells you whether it actually worked or not
• Args: either a Bio::Tree::NodeI or a string of the node id

get_lineage_nodes

• Title: get_lineage_nodes
• Usage: my @nodes = $tree->get_lineage_nodes($node);
• Function: give it a node or its ID and it gets the full lineage — like, all its ancestors, going from the root down to the most recent ancestor. Only use the node ID as input if the nodes have already been added to the tree, okay?
• Returns: a list of nodes
• Args: either a Bio::Tree::NodeI (or a string of the node id)

get_lineage_string

• Title: get_lineage_string
• Usage: my $lineage = $tree->get_lineage_string($node);
• Function: gets you the string version of a node's full lineage. like for the Enterobacteriales node, it returns Bacteria;Proteobacteria;Gammaproteobacteria;Enterobacteriales. This one uses get_lineage_nodes under the hood, so it inherits all of its caveats, no cap
• Returns: string
• Args:
  • either Bio::Tree::NodeI (or a string of the node id)
  • an optional separator (default: ;)

splice

• Title: splice
• Usage: $tree->splice(-remove_id => \@ids);
• Function: removes all the nodes from a tree that match the args you give it, and makes all the descendants of a removed node become the descendants of that removed node's ancestor. You can ask to explicitly remove certain nodes using -remove_*, remove them conditionally by using -remove_* together with -keep_*, or remove literally 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 remove or keep, then an underscore, then a fieldname (same deal as the find_node method). The value should be a scalar or an array ref of scalars (again, like what you might hand to find_node).

So (-remove_id => [1, 2]) will remove all nodes from the tree that have an id() of '1' or '2', while (-remove_id => [1, 2], -keep_id => [2]) will remove all nodes with an id() of '1'. And (-keep_id => [2]) will remove all nodes unless they have an id() of '2' (note: no -remove_* here).

-preserve_lengths => 1 : setting this argument will splice out intermediate nodes while preserving the original total length between the ancestor and the descendants of the spliced node. Undef by default.

get_lca

• Title: get_lca
• Usage: get_lca(-nodes => \@nodes ); OR get_lca(@nodes);
• Function: give it two or more nodes and it returns the lowest common ancestor (aka the most recent common ancestor) 💅
• Returns: a node object, or undef if there's no common ancestor
• Args: -nodes => arrayref of nodes to test, OR just a list of nodes

merge_lineage

• Title: merge_lineage
• Usage: merge_lineage($node)
• Function: merges a lineage of nodes with this tree
• Returns: true for success, false (plus a warning) otherwise
• Args: a Bio::Tree::TreeI with only one leaf, OR a Bio::Tree::NodeI which has an ancestor

so for example, if we're the tree $tree:

+---B
|
A
|
+---C

and we wanna merge the lineage $other_tree:

A---C---D

after calling $tree->merge_lineage($other_tree), $tree looks like:

+---B
|
A
|
+---C---D

contract_linear_paths

• Title: contract_linear_paths
• Usage: contract_linear_paths()
• Function: splices out all nodes in the tree that have an ancestor and only one descendant
• 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're 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

is_binary

• Example: is_binary(); is_binary($node);
• Description: finds out 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

force_binary

• 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're 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 'artificial_n', where n is an integer making the id unique within the tree)

simplify_to_leaves_string

• 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't binary), but it'll 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

distance

• Title: distance
• Usage: distance(-nodes => \@nodes )
• Function: returns the distance between two given nodes
• Returns: numerical distance
• Args: -nodes => arrayref of nodes to test, or ($node1, $node2)

is_monophyletic

• Title: is_monophyletic
• Usage: if( $tree->is_monophyletic(-nodes => \@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

is_paraphyletic

• Title: is_paraphyletic
• Usage: if( $tree->is_paraphyletic(-nodes =>\@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

reroot

• 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

reroot_at_midpoint

• 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::NodeI on success, 0 on failure
• Args: non-root Bio::Tree::NodeI currently in $tree, scalar string, id for new node (optional)

findnode_by_id

• 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: Bio::Tree::NodeI
• Args: node id

move_id_to_bootstrap

• Title: move_id_to_bootstrap
• Usage: $tree->move_id_to_bootstrap
• Function: move internal IDs to the bootstrap slot
• Returns: undef
• Args: undef

add_trait

• Title: add_trait
• Usage: my $key = $tree->add_trait($trait_file, 3);
• Function: adds 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 the 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 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 you asked for 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)

---

and that's a wrap, bestie 🎀 this page ships with perl v5.32.1, dated 2021-08-15, and it lives under the Bio::T...ctionsI(3pm) name in the User Contributed Perl Documentation. go forth and tree responsibly 💖✨🦋