Bio::Tree::NodeI(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 Bio::Tree::NodeI 💖

okay bestie, so Bio::Tree::NodeI — that's the perl module name, she's a 3pm manual page, and she is literally the Interface describing a Tree Node. one node. one little link in your phylogenetic tree. but she's the blueprint for all of them. slay. 🎀

✨ NAME ✨

Bio::Tree::NodeI — the interface that describes a Tree Node. that's it, that's the whole name, no notes. 💅

🌈 SYNOPSIS 🌈

okay so here's the vibe in code, take notes:

# get a Tree::NodeI somehow
# like from a TreeIO
use Bio::TreeIO;
# read in a clustalw NJ in phylip/newick format
my $treeio = Bio::TreeIO->new(-format => 'newick', -file => 'file.dnd');

my $tree = $treeio->next_tree; # we'll assume it worked for demo purposes
                               # you might want to test that it was defined

my $rootnode = $tree->get_root_node;

# process just the next generation
foreach my $node ( $rootnode->each_Descendent() ) {
    print "branch len is ", $node->branch_length, "\n";
}

# process all the children
my $example_leaf_node;
foreach my $node ( $rootnode->get_all_Descendents() ) {
    if( $node->is_Leaf ) {
        print "node is a leaf ... ";
        # for example use below
        $example_leaf_node = $node unless defined $example_leaf_node;
    }
    print "branch len is ", $node->branch_length, "\n";
}

# The ancestor() method points to the parent of a node
# A node can only have one parent

my $parent = $example_leaf_node->ancestor;

# parent won't likely have an description because it is an internal node
# but child will because it is a leaf

print "Parent id: ", $parent->id," child id: ",
      $example_leaf_node->id, "\n";

like yes, read the whole thing, it's giving tutorial but make it fashion. 💖

🦋 DESCRIPTION 🦋

so. a NodeI can do the basic structure of building a tree and storing the branch length between nodes. and the branch length is the length of the branch between the node and its ancestor — which means a root node in a Tree will not typically have a valid branch length. no cap. the root is rootin'. it has no ancestor to measure against. 🌸

various implementations of NodeI may extend the basic functions and let you store other info too — like attaching a species object, or full sequences used to build a tree, or alternative sequences. if you don't know how to extend a Bioperl object, bestie, please just ask, happy to help 💜 — and we would also greatly appreciate contributions with improvements or extensions of the objects back to the Bioperl code base, so that others don't have to reinvent your ideas. sharing is caring, periodt.

👑 FEEDBACK 👑

💌 Mailing Lists

user feedback is an integral part of the evolution of this and other Bioperl modules. so send your comments and suggestions, preferably to the Bioperl mailing list. your participation is much appreciated, fr fr. 🫶

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

🩹 Support

please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. (yes, really, the whole list, not one poor human's inbox 🙈) many experienced and reponsive experts will be able look at the problem and quickly address it. and please include a thorough description of the problem with code and data examples if at all possible — the more context the better, iykyk.

🐛 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:

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

go off, file that bug. 💅

✍️ AUTHOR - Jason Stajich

email jason@bioperl.org

🌟 CONTRIBUTORS 🌟

Aaron Mackey amackey@virginia.edu

📚 APPENDIX 📚

the rest of the documentation details each of the object methods. internal methods are usually preceded with a _ — you know, the secret menu items. 🤫

add_Descendent

  • 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

each_Descendent

  • Title : each_Descendent
  • 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 : none

✨ Decorated Interface methods ✨

get_all_Descendents

  • Title : get_all_Descendents($sortby)
  • 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 : $sortby [optional] "height", "creation", "alpha", "revalpha", or a coderef to be used to sort the order of children nodes.

is_Leaf

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

descendent_count

  • Title : descendent_count
  • Usage : my $count = $node->descendent_count;
  • Function: counts the number of descendents a node has (and all of their subnodes)
  • Returns : integer
  • Args : none

to_string

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

height

  • 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

depth

  • Title : depth
  • Usage : my $len = $node->depth
  • Function: returns the depth of the tree starting at this node. Depth is the distance from this node to the root.
  • Returns : the branch length to the root.
  • Args : none

🎀 Get/Set methods 🎀

branch_length

  • Title : branch_length
  • Usage : $obj->branch_length()
  • Function: get/set the branch length
  • Returns : value of branch_length
  • Args : newvalue (optional)

id

  • Title : id
  • Usage : $obj->id($newval)
  • Function: the human readable identifier for the node
  • Returns : value of human readable id
  • Args : newvalue (optional)

internal_id

  • Title : internal_id
  • Usage : my $internalid = $node->internal_id
  • Function: returns the internal unique id for this Node
  • Returns : unique id
  • Args : none

description

  • Title : description
  • Usage : $obj->description($newval)
  • Function: get/set the description string
  • Returns : value of description
  • Args : newvalue (optional)

bootstrap

  • Title : bootstrap
  • Usage : $obj->bootstrap($newval)
  • Function: get/set the bootstrap value
  • Returns : value of bootstrap
  • Args : newvalue (optional)

ancestor

  • Title : ancestor
  • Usage : my $node = $node->ancestor;
  • Function: get/set the ancestor node pointer for a Node
  • Returns : Null if this is top level node
  • Args : none

invalidate_height

  • Title : invalidate_height
  • Usage : private helper method
  • Function: invalidate our cached value of the node height in the tree
  • Returns : nothing
  • Args : none

🏷️ Methods for associating Tag/Values with a Node 🏷️

these methods associate tag/value pairs with a Node. it's giving little sticky notes but for your nodes. 💜

set_tag_value

  • 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

add_tag_value

  • 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

remove_tag

  • 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

remove_all_tags

  • Title : remove_all_tags
  • Usage : $node->remove_all_tags()
  • Function: removes all tags
  • Returns : None
  • Args : None

get_all_tags

  • 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

get_tag_values

  • Title : get_tag_values
  • Usage : my @values = $node->get_tag_values($tag)
  • Function: gets the values for given tag ($tag)
  • Returns : Array of values or empty list if tag does not exist
  • Args : $tag — tag name

has_tag

  • Title : has_tag
  • Usage : $node->has_tag($tag)
  • Function: boolean test if tag exists in the Node
  • Returns : Boolean
  • Args : $tag — tagname

🧚 Helper Functions 🧚

id_output

  • 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
reminder bestie: internal methods are the ones usually preceded with a _. if you see an underscore, mind your business unless you know what you're doing. 💀

and that's the whole page, we ate and left no crumbs. 👑

this lil manual page was rendered by perl v5.32.1 and she's dated 2021-08-15 — Bio::Tree::NodeI(3pm), user contributed perl documentation, iconic behavior only. 💖✨🌸

📦 where this page comes from