Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bio::Tree::TreeFunctioUser3Contributed Perl DocumeBio::Tree::TreeFunctionsI(3)

NAME
       Bio::Tree::TreeFunctionsI - Decorated Interface implementing basic Tree
       exploration methods

SYNOPSIS
	 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) ){
	  #...
	 }

DESCRIPTION
       This interface provides a set of	implementated Tree functions which
       only use	the defined methods in the TreeI or NodeI interface.

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

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

   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

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

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

   find_node
	Title	: find_node
	Usage	: my @nodes = $self->find_node(-id => 'node1');
	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

   remove_Node
	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

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

   get_lineage_string
	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: ';')

   splice
	Title	: splice
	Usage	: $tree->splice(-remove_id => \@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's	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 'remove' or 'keep',
		  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 '1' or '2', while
		  (-remove_id => [1, 2], -keep_id => [2]) will remove all nodes	with
		  an id() of '1'.
		  (-keep_id => [2]) will remove	all nodes unless they have an id() of
		  '2' (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.

   get_lca
	Title	: get_lca
	Usage	: get_lca(-nodes => \@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

   merge_lineage
	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

   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
		  descendent.
	Returns	: n/a
	Args	: none for normal behaviour, true to dis-regard	the ancestor requirment
		  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

   is_binary
	 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

   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 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 '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
		  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

   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::NodeIon 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	: L<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 bootstrap slot
	Returns	: undef
	Args	: undef

   add_trait
	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).

perl v5.24.1			  2017-07-08	  Bio::Tree::TreeFunctionsI(3)

NAME | SYNOPSIS | DESCRIPTION | FEEDBACK | AUTHOR - Jason Stajich, Aaron Mackey, Justin Reese | CONTRIBUTORS | APPENDIX

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bio::Tree::TreeFunctionsI&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help