Bio::Tree::Node(3pm)

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

💖 Bio::Tree::Node 💖

okay bestie, gather round — this is the manual page for Bio::Tree::Node(3pm), like, the actual Perl doc for it. It's a Simple Tree Node and honestly? it eats. Let's get into it. 🎀

✨ NAME ✨

Bio::Tree::Node — A Simple Tree Node. that's it, that's the whole vibe. 🌸

✨ SYNOPSIS ✨

okay so here's the whole flex in code form, copy it exactly bestie:

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 \n" if( $node->is_leaf);

like, you build nodes, you glue them together, you check if something's a leaf. slay. 💅

✨ DESCRIPTION ✨

It makes a Tree Node that's suitable for building a Tree. lowkey does exactly what it says on the tin and we respect that. 🦋

✨ FEEDBACK ✨

💌 Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. So like, send your comments and suggestions, preferably to the Bioperl mailing list. Your participation is much appreciated — fr fr, they mean it. 🫶

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. There are so many experienced and reponsive experts who 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. (yes they wrote "reponsive", we're leaving it, no cap 🙈)

🐛 Reporting Bugs

Report bugs to the Bioperl bug tracking system so they 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 👑

Email jason-at-bioperl-dot-org — iconic. main character energy. we stan. ✨

🌈 CONTRIBUTORS 🌈

  • Aaron Mackey, amackey-at-virginia-dot-edu
  • Sendu Bala, bix@sendu.me.uk

🎀 APPENDIX 🎀

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _. iykyk. 🧚

🌟 new

  • 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

🌟 create_node_on_branch

  • 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

🌟 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
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.
heads up bestie: default is false and it will throw an error if you try and overwrite an existing node. so don't be messy. 💀

🌟 each_Descendent

  • 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.

🌟 remove_Descendent

  • 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.

🌟 remove_all_Descendents

  • Title: remove_all_Descendents
  • Usage: $node->remove_All_Descendents()
  • Function: Cleanup the node's reference to descendents and reset their ancestor pointers to undef, if you don't 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
not me warning you: if you don't hold a reference after this, those objects are gone. do the get_nodes thing first if you need them. 🫣

🌟 get_all_Descendents

  • 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

🌟 ancestor

  • Title: ancestor
  • Usage: $obj->ancestor($newval)
  • Function: Set the Ancestor
  • Returns: ancestral node
  • Args: newvalue (optional)

🌟 branch_length

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

🌟 bootstrap

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

🌟 description

  • Title: description
  • Usage: $obj->description($newval)
  • Function: Get/Set the description string
  • Returns: value of description
  • 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)

okay this next bit is a whole quote, and it's giving ✨citation✨ so we keep it word for word:

"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 ("_") stands for a blank; any of these in a name will be converted to a blank when it is read in."

from <http://evolution.genetics.washington.edu/phylip/newicktree.html>

Also note that these objects now support spaces, ();: because they can automatically quote the strings if they contain these characters. The id_output method does this for you so use the id() method to get the raw string while id_output to get the pre-escaped string. literally so convenient, obsessed. 💅

🌟 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

💫 internal_id

  • 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

💫 _creation_id

  • 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)

🌸 Bio::Node::NodeI decorated interface implemented 🌸

The following methods are implemented by Bio::Node::NodeI decorated interface. bestie it's a whole interface moment. ✨

⭐ is_Leaf

  • Title: is_Leaf
  • Usage: if( $node->is_Leaf )
  • Function: Get Leaf status
  • Returns: boolean
  • 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

⭐ 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

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

⭐ has_tag

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

⭐ reverse_edge

  • 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

and that's the whole page bestie, you ate it up 💅

This doc was rendered by perl v5.32.1, dated 2021-08-15, and it's the manual page for Bio::Tree::Node(3pm). no cap, go build a tree, you've got this 🫶✨🌈

📦 where this page comes from