forester v1.3

forester.tree
Class Tree

java.lang.Object
  |
  +--forester.tree.Tree
All Implemented Interfaces:
java.io.Serializable

public class Tree
extends java.lang.Object
implements java.io.Serializable

Version:
1.442 -- last modified: 10/31/00
Author:
Christian M. Zmasek
See Also:
Serialized Form

Constructor Summary
Tree()
          Default Tree constructor.
Tree(java.lang.String nh_string)
          Tree constructor.
 
Method Summary
 void adjustNodeCount()
          (Re)counts the number of children for each Node of this Tree.
 void allowMoreThanBinaryNodesInNHoutput(boolean b)
          Sets whether to allow more than binary Nodes in New Hampshire (NH) output.
 boolean areBranchLenghtsBootstraps()
          Checks whether the branch length values actually are bootstrap values All external Nodes must have the same, >0, divisible by 10 branch length.
 void calculateNumberOfBranches()
          Calculates to number of branches of this Tree.
 Tree copyBranchLengthValuesFrom(Tree tree2)
          Returns a Tree which is a copy of this Tree, except it has the branch lenghts of tree2.
 Tree copyTree()
          Returns a deep copy of this Tree.
 void delete()
          Deletes this Tree.
 void findHighestLnL()
          Finds the highest of all log likelihood value associated with branches of this Tree.
 void findLowestLnL()
          Finds the lowest of all log likelihood value associated with branches of this Tree.
 Tree[] fuseToAllBranches(Tree t2)
          Returns an array of references to Trees which are the result of fusing Tree t2 to all possible branches of this Tree.
 Tree fuseTrees(int id, double d, double r, Tree t)
          Returns a Tree which is the result of fusing a rooted Tree to this Tree.
 Tree fuseTrees(int id, double d, double r, Tree t, Node n)
          Returns a Tree which is the result of fusing a rooted Tree to this Tree.
 Tree fuseTrees(int id, double d, Tree t)
          Returns a Tree which is the result of fusing a rooted Tree to this Tree.
 Tree fuseTrees(int id, double d, Tree t, Node n)
          Returns a Tree which is the result of fusing a rooted Tree to this Tree.
 Tree fuseTrees(int id, Tree t)
          Returns a Tree which is the result of fusing a rooted Tree to this Tree.
 Tree fuseTrees(int id, Tree t, Node n)
          Returns a Tree which is the result of fusing a rooted Tree to this Tree.
 Node getExtNode0()
          Returns the first external Node.
 double getHighestLnL()
          Returns the highest log likelihood value associated with branches of this Tree (double).
 Node getLastCommonAncestor(int id1, int id2)
          Finds the last common ancestor Node of two Nodes specified by their IDs id1 and id2.
 Node getLastCommonAncestor(java.lang.String seqname1, java.lang.String seqname2)
          Finds the last common ancestor Node of two Nodes specified by their sequence names seqname1 and seqname2.
 double getLongestDistance()
          Returns the longest distance of this Tree (double).
 double getLowestLnL()
          Returns the lowest log likelihood value associated with branches of this Tree (double).
 int getMostBranchesPerExtNode()
          Returns the maximum number of branches per external Node (int).
 java.lang.String getName()
          Returns the name of this Tree.
 Node getNode(int id)
          Finds the Node of this Tree which has a matching ID number.
 java.util.Vector getNodes(java.lang.String seqname)
          Returns a Vector with references to all Nodes of this Tree which have a matching sequence name.
 java.util.Vector getNodesWithMatchingSpecies(java.lang.String specname)
          Returns a Vector with references to all Nodes of this Tree which have a matching species name.
 int getNumberOfBranches()
          Returns the total number of branches of this Tree (int).
 int getNumberOfDuplications()
          Returns the number of duplications of this Tree (int).
 int getNumberOfExtNodes()
          Returns the sum of external Nodes of this Tree (int).
 java.util.Vector getPath(Node node1, Node node2, boolean ret_pseudo_nodes)
          Returns a Vector containing the Node IDs of all Nodes which are between two external Nodes (node2 and node1).
 Node getRoot()
          Returns the root Node of this Tree.
 java.util.Vector getSiblings(Node n)
          Returns a Vector of references to all external siblings and nieces of a external Node n.
 void hashIDs()
          Hashes the ID number of each Node of this Tree to its corresonding Node, in order to make method getNode( id ) run in constant time.
 boolean isEmpty()
          Checks whether a Tree object is deleted (or empty).
 boolean isRooted()
          Returns true is this Tree is rooted.
 void moveBranchLenghtsToBootstrap()
          Moves the values in the branch length field to the bootstrap field, for each Node of this Tree.
 int preorderReID(int i)
          Resets the ID values of the Nodes of this Tree in preorder, starting with i.
 void printAllNodes()
          Prints descriptions of all Nodes of this Tree to the console.
 void printExtNodes()
          Prints descriptions of all external Nodes of this Tree to the console.
 void recalculateAndReset()
          Recalculates and resets parameters of this Tree: most-branches-per-external-Node, highest and lowest lnL, longest distance, number of branches, sum of ext Nodes, deletes data of root Node if this Tree is unrooted.
 void removeExtNode(Node n)
          Removes external Node from this Tree.
 void reRoot(int id)
          Places the root of this Tree on the parent branch of the Node with a corresponding ID.
 void reRoot(int id, java.lang.String s)
          Places the root of this Tree on the parent branch of the Node with a corresponding ID.
 void reRoot(Node n)
          Places the root of this Tree on the parent branch Node n.
 void reRoot(Node n, java.lang.String s)
          Places the root of this Tree on the parent branch Node n.
 void setIndicatorsToZero()
          Sets the indicators of all Nodes of this Tree to 0.
 void setName(java.lang.String s)
          Sets the name of this Tree to s.
 void setNumberOfDuplications(int i)
          Sets the number of duplications of this Tree (int).
 void setRooted(boolean b)
          Sets whether this Tree is rooted or not.
 Tree subTree(int id)
          Returns the subtree of this Tree which has the Node with ID id as its root Node.
 void swapChildren(int id)
          Swaps the the two childern of a Node with ID id of this Tree.
 void swapChildren(Node node)
          Swaps the the two childern of a Node node of this Tree.
 java.lang.String toNewHampshire(boolean clean_nh)
          Converts this Tree to a New Hampshire (String) representation.
 java.lang.String toNewHampshireX()
          Converts this Tree to a New Hampshire X (String) representation.
 java.lang.String toString()
          Converts this Tree to a New Hampshire X (String) representation.
 void unRoot()
          Removes the root Node this Tree.
 void unRootAndTrifurcate()
          Removes the root Node of this Tree and makes at least a trifurcation at its basal node.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Tree

public Tree()
Default Tree constructor. Constructs empty Tree.

Tree

public Tree(java.lang.String nh_string)
     throws java.lang.Exception
Tree constructor.
Parameters:
nh_string - String in New Hampshire (NH) or New Hampshire X (NHX) format
Method Detail

isEmpty

public boolean isEmpty()
Checks whether a Tree object is deleted (or empty).
Returns:
true if the tree is deleted (or empty), false otherwise

delete

public void delete()
Deletes this Tree.

removeExtNode

public void removeExtNode(Node n)
Removes external Node from this Tree. Remark: getLongestDistance() and getMostBranchesPerExtNode() return incorrect values after this method has been called. If this tree has only one node, a empty tree will be returned.
Parameters:
n - Node to remove

getNodes

public java.util.Vector getNodes(java.lang.String seqname)
                          throws java.lang.Exception
Returns a Vector with references to all Nodes of this Tree which have a matching sequence name.
Parameters:
seqname - Sequence name (String) of Nodes to find
Returns:
Vector of references to Nodes of this Tree with matching sequence names
See Also:
getNodesWithMatchingSpecies(String)

getNodesWithMatchingSpecies

public java.util.Vector getNodesWithMatchingSpecies(java.lang.String specname)
                                             throws java.lang.Exception
Returns a Vector with references to all Nodes of this Tree which have a matching species name.
Parameters:
specname - species name (String) of Nodes to find
Returns:
Vector of references to Nodes of this Tree with matching species names.
See Also:
getNodes(String)

getNode

public Node getNode(int id)
Finds the Node of this Tree which has a matching ID number. Takes O(n) time. After method hashIDs() has been called it runs in constant time.
Parameters:
id - ID number (int) of the Node to find
Returns:
Node with matching ID, null if Node not found

swapChildren

public void swapChildren(int id)
Swaps the the two childern of a Node with ID id of this Tree.
Parameters:
id - ID (int) of Node

swapChildren

public void swapChildren(Node node)
Swaps the the two childern of a Node node of this Tree.
Parameters:
node - a Node of this Tree

subTree

public Tree subTree(int id)
             throws java.lang.Exception
Returns the subtree of this Tree which has the Node with ID id as its root Node.
Parameters:
id - ID (int) of Node

reRoot

public void reRoot(int id)
            throws java.lang.Exception
Places the root of this Tree on the parent branch of the Node with a corresponding ID. The new root is always placed on the middle of the branch. If the resulting reRooted Tree is to be used any further, in most cases the following three methods have to be called on the resulting Tree: adjustNodeCount() recalculateAndReset() setExtNodes( getRoot().getSumExtNodes() )
Parameters:
id - ID (int) of Node of this Tree

reRoot

public void reRoot(Node n)
            throws java.lang.Exception
Places the root of this Tree on the parent branch Node n. The new root is always placed on the middle of the branch. If the resulting reRooted Tree is to be used any further, in most cases the following three methods have to be called on the resulting Tree: adjustNodeCount() recalculateAndReset() setExtNodes( getRoot().getSumExtNodes() )
Parameters:
n - Node of this Tree

reRoot

public void reRoot(int id,
                   java.lang.String s)
            throws java.lang.Exception
Places the root of this Tree on the parent branch of the Node with a corresponding ID. Information for the new root Node is provided in a String using NHX tags. The new root is always placed on the middle of the branch. If the resulting reRooted Tree is to be used any further, in most cases the following three methods have to be called on the resulting Tree: adjustNodeCount() recalculateAndReset() setExtNodes( getRoot().getSumExtNodes() )
Parameters:
id - ID (int) of Node of this Tree
s - String describing new Node

reRoot

public void reRoot(Node n,
                   java.lang.String s)
            throws java.lang.Exception
Places the root of this Tree on the parent branch Node n. Information for the new root Node is provided in a String using NHX tags. The new root is always placed on the middle of the branch. If the resulting reRooted Tree is to be used any further, in most cases the following three methods have to be called on the resulting Tree: adjustNodeCount() recalculateAndReset() setExtNodes( getRoot().getSumExtNodes() )
Parameters:
n - Node of this Tree
s - String describing new Node

copyBranchLengthValuesFrom

public Tree copyBranchLengthValuesFrom(Tree tree2)
                                throws java.lang.Exception
Returns a Tree which is a copy of this Tree, except it has the branch lenghts of tree2. Important (but obvious): The topology of both trees needs to be the same. (The method is not robust in this point, and will produce wrong results if the internal topology differs.) Furthermore, the combination of sequence name, species, and EC number needs to be unique for each external node.
Parameters:
tree2 - the Tree to copy the branch lenghts from

recalculateAndReset

public void recalculateAndReset()
Recalculates and resets parameters of this Tree: most-branches-per-external-Node, highest and lowest lnL, longest distance, number of branches, sum of ext Nodes, deletes data of root Node if this Tree is unrooted. To be used after Tree has been modified.

copyTree

public Tree copyTree()
Returns a deep copy of this Tree.

unRootAndTrifurcate

public void unRootAndTrifurcate()
Removes the root Node of this Tree and makes at least a trifurcation at its basal node.

unRoot

public void unRoot()
Removes the root Node this Tree.

fuseTrees

public Tree fuseTrees(int id,
                      double d,
                      double r,
                      Tree t,
                      Node n)
               throws java.lang.Exception
Returns a Tree which is the result of fusing a rooted Tree to this Tree.
Parameters:
id - ID (int) of the Node of this Tree of whose parent branch to fuse to
d - distance to parent (double) of newly introduced Node
r - distance to parent (double) of Tree to fuse to this Tree
t - Tree to fuse to this Tree
n - the newly introduced Node

fuseTrees

public Tree fuseTrees(int id,
                      double d,
                      Tree t,
                      Node n)
               throws java.lang.Exception
Returns a Tree which is the result of fusing a rooted Tree to this Tree.
Parameters:
id - ID (int) of the Node of this Tree of whose parent branch to fuse to
d - distance to parent (double) of newly introduced Node
t - Tree to fuse to this Tree
n - the newly introduced Node

fuseTrees

public Tree fuseTrees(int id,
                      Tree t,
                      Node n)
               throws java.lang.Exception
Returns a Tree which is the result of fusing a rooted Tree to this Tree.
Parameters:
id - ID (int) of the Node of this Tree of whose parent branch to fuse to
t - Tree to fuse to this Tree
n - the newly introduced Node

fuseTrees

public Tree fuseTrees(int id,
                      double d,
                      double r,
                      Tree t)
               throws java.lang.Exception
Returns a Tree which is the result of fusing a rooted Tree to this Tree.
Parameters:
id - ID (int) of the Node of this Tree of whose parent branch to fuse to
d - distance to parent (double) of newly introduced Node
r - distance to parent (double) of Tree to fuse to this Tree
t - Tree to fuse to this Tree

fuseTrees

public Tree fuseTrees(int id,
                      double d,
                      Tree t)
               throws java.lang.Exception
Returns a Tree which is the result of fusing a rooted Tree to this Tree.
Parameters:
id - ID (int) of the Node of this Tree of whose parent branch to fuse to
d - distance to parent (double) of newly introduced Node
t - Tree to fuse to this Tree

fuseTrees

public Tree fuseTrees(int id,
                      Tree t)
               throws java.lang.Exception
Returns a Tree which is the result of fusing a rooted Tree to this Tree.
Parameters:
id - ID (int) of the Node of this Tree of whose parent branch to fuse to
t - Tree to fuse to this Tree

fuseToAllBranches

public Tree[] fuseToAllBranches(Tree t2)
                         throws java.lang.Exception
Returns an array of references to Trees which are the result of fusing Tree t2 to all possible branches of this Tree.
Parameters:
t2 - the Tree to fuse to all branches of this Tree

getRoot

public Node getRoot()
Returns the root Node of this Tree.

isRooted

public boolean isRooted()
Returns true is this Tree is rooted.

setRooted

public void setRooted(boolean b)
Sets whether this Tree is rooted or not.

getHighestLnL

public double getHighestLnL()
Returns the highest log likelihood value associated with branches of this Tree (double).
See Also:
findHighestLnL()

getLowestLnL

public double getLowestLnL()
Returns the lowest log likelihood value associated with branches of this Tree (double).
See Also:
findLowestLnL()

getLongestDistance

public double getLongestDistance()
Returns the longest distance of this Tree (double). Used for the drawing of Trees.

getNumberOfBranches

public int getNumberOfBranches()
Returns the total number of branches of this Tree (int).
See Also:
calculateNumberOfBranches()

getNumberOfDuplications

public int getNumberOfDuplications()
Returns the number of duplications of this Tree (int). A return value of -1 indicates that the number of duplications is unknown.

setNumberOfDuplications

public void setNumberOfDuplications(int i)
Sets the number of duplications of this Tree (int). A value of -1 indicates that the number of duplications is unknown.
Parameters:
clean_nh - set to true for clean NH format

getExtNode0

public Node getExtNode0()
Returns the first external Node.

getMostBranchesPerExtNode

public int getMostBranchesPerExtNode()
Returns the maximum number of branches per external Node (int). Used for the drawing of Trees.

getNumberOfExtNodes

public int getNumberOfExtNodes()
Returns the sum of external Nodes of this Tree (int).

allowMoreThanBinaryNodesInNHoutput

public void allowMoreThanBinaryNodesInNHoutput(boolean b)
Sets whether to allow more than binary Nodes in New Hampshire (NH) output. The basal node can always appear trifurcated in the NH output.

getName

public java.lang.String getName()
Returns the name of this Tree.

setName

public void setName(java.lang.String s)
Sets the name of this Tree to s.

printExtNodes

public void printExtNodes()
Prints descriptions of all external Nodes of this Tree to the console.

printAllNodes

public void printAllNodes()
Prints descriptions of all Nodes of this Tree to the console.

setIndicatorsToZero

public void setIndicatorsToZero()
Sets the indicators of all Nodes of this Tree to 0.

findLowestLnL

public void findLowestLnL()
Finds the lowest of all log likelihood value associated with branches of this Tree. The result can be obtained with "getLowestLnL()".
See Also:
getLowestLnL()

findHighestLnL

public void findHighestLnL()
Finds the highest of all log likelihood value associated with branches of this Tree. The result can be obtained with "getHighestLnL()".
See Also:
getHighestLnL()

calculateNumberOfBranches

public void calculateNumberOfBranches()
Calculates to number of branches of this Tree. The result can be obtained with "getNumberOfBranches()". E.g. (a,b): 1 branch (unrooted). (a,b)x: 3 branches (rooted).
See Also:
getNumberOfBranches()

moveBranchLenghtsToBootstrap

public void moveBranchLenghtsToBootstrap()
                                  throws java.lang.Exception
Moves the values in the branch length field to the bootstrap field, for each Node of this Tree. Converts a Tree originating from a phylip treefile after bootstrapping and which therefore has its bootstrap values where the branch lenghts would be.

areBranchLenghtsBootstraps

public boolean areBranchLenghtsBootstraps()
Checks whether the branch length values actually are bootstrap values All external Nodes must have the same, >0, divisible by 10 branch length. Boostrap of root must be assigned.

toString

public java.lang.String toString()
Converts this Tree to a New Hampshire X (String) representation.
Overrides:
toString in class java.lang.Object
Returns:
String
See Also:
toNewHampshireX()

toNewHampshire

public java.lang.String toNewHampshire(boolean clean_nh)
Converts this Tree to a New Hampshire (String) representation. If the boolean clean_nh is true, the length of sequence names will be truncated to MAX_LENGTH (usually 10) characters and everything after a "/" will be removed (including the "/").
Parameters:
clean_nh - set to true for clean NH format
Returns:
String

toNewHampshireX

public java.lang.String toNewHampshireX()
Converts this Tree to a New Hampshire X (String) representation.

getPath

public java.util.Vector getPath(Node node1,
                                Node node2,
                                boolean ret_pseudo_nodes)
                         throws java.lang.Exception
Returns a Vector containing the Node IDs of all Nodes which are between two external Nodes (node2 and node1). The order is so that element 0 is node2, and the last element is node1. Even if the Tree is rooted, this method does not return the root as part of the pathway (not ideal). The boolean ret_pseudo_nodes determines whether or not to return pseudo Nodes. (true: return pseudo nodes, false: only return real nodes.)

getSiblings

public java.util.Vector getSiblings(Node n)
                             throws java.lang.Exception
Returns a Vector of references to all external siblings and nieces of a external Node n. The order is the same as in the Tree.
Returns:
Vector of references to Nodes

getLastCommonAncestor

public Node getLastCommonAncestor(java.lang.String seqname1,
                                  java.lang.String seqname2)
                           throws java.lang.Exception
Finds the last common ancestor Node of two Nodes specified by their sequence names seqname1 and seqname2. This method obviously can produce a meaningful result only, if this Tree is correctly rooted.

getLastCommonAncestor

public Node getLastCommonAncestor(int id1,
                                  int id2)
                           throws java.lang.Exception
Finds the last common ancestor Node of two Nodes specified by their IDs id1 and id2. This method obviously can produce a meaningful result only, if this Tree is correctly rooted.

adjustNodeCount

public void adjustNodeCount()
(Re)counts the number of children for each Node of this Tree. As an example, this method needs to be called after a Tree has been reRooted.

preorderReID

public int preorderReID(int i)
Resets the ID values of the Nodes of this Tree in preorder, starting with i.
Parameters:
i - the starting value (int)
Returns:
i plus the total number of Nodes of this Tree (int)

hashIDs

public void hashIDs()
Hashes the ID number of each Node of this Tree to its corresonding Node, in order to make method getNode( id ) run in constant time. Important: The user is responsible for calling this method (again) after this Tree has been changed/created/renumbered.

forester v1.3