forester v1.2

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.35 -- last modified: 07/23/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 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(long id, double d, double r, Tree t)
          Returns a Tree which is the result of fusing a rooted Tree to this Tree.
 Tree fuseTrees(long 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(long id, double d, Tree t)
          Returns a Tree which is the result of fusing a rooted Tree to this Tree.
 Tree fuseTrees(long id, double d, Tree t, Node n)
          Returns a Tree which is the result of fusing a rooted Tree to this Tree.
 Tree fuseTrees(long id, Tree t)
          Returns a Tree which is the result of fusing a rooted Tree to this Tree.
 Tree fuseTrees(long 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(long id1, long 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(long 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 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.
 boolean isEmpty()
          Checks whether a Tree object is deleted (or empty).
 boolean isRooted()
          Returns true is this Tree is rooted.
 Tree modify(java.io.File f)
          Rerootes and assignes sequence names to internal nodes.
 Tree modify(java.lang.String s)
          Rerootes and assignes sequence names to internal Nodes.
 Tree modify(java.net.URL url)
          Rerootes and assignes sequence names to internal nodes.
 void moveBranchLenghtsToBootstrap()
          Moves the values in the branch length field to the bootstrap field, for each Node of this Tree.
 long preorderReID(long l)
          Resets the ID values of the Nodes of this Tree in preorder, starting with l.
 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, deletes data of root Node if this Tree is unrooted.
 void removeExtNode(Node n)
          Removes external Node from this Tree.
 void reRoot(long id)
          Places the root of this Tree on the parent branch of the Node with a corresponding ID.
 Tree reRoot(long id1, long id2, long id3)
          Rerootes this Tree, given the IDs of three external nodes.
 void reRoot(long id, java.lang.String s)
          Places the root of this Tree on the parent branch of the Node with a corresponding ID.
 Tree reRoot(java.lang.String seqname1, java.lang.String seqname2, java.lang.String seqname3)
          Rerootes this Tree, given the sequence names of three external nodes.
 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 setRooted(boolean b)
          Sets whether this Tree is rooted or not.
 Tree subTree(long id)
          Returns the subtree of this Tree which has the Node with ID id as its root Node.
 void swapChildren(long id)
          Swaps the the two childern of a Node with ID id 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.
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(long id)
Finds the Node of this Tree which has a matching ID number.
Parameters:
id - ID number (long) of the Node to find
Returns:
Node with matching ID, null if Node not found

swapChildren

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

subTree

public Tree subTree(long 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 (long) of Node

reRoot

public void reRoot(long 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.
Parameters:
id - ID (long) of Node

reRoot

public void reRoot(long 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.
Parameters:
id - ID (long) of Node
s - String describing new Node

reRoot

public Tree reRoot(java.lang.String seqname1,
                   java.lang.String seqname2,
                   java.lang.String seqname3)
            throws java.lang.Exception
Rerootes this Tree, given the sequence names of three external nodes. The position of the root is determined in the following way: 1. The internal node whose children and parent lead to the three nodes specified by seqname1, 2, and 3 is determined. 2. The root is placed on the branch leading to the first external node (seqname1).
Returns:
rooted Tree

reRoot

public Tree reRoot(long id1,
                   long id2,
                   long id3)
            throws java.lang.Exception
Rerootes this Tree, given the IDs of three external nodes. The position of the root is determined in the following way: 1. The internal node whose children and parent lead to the three nodes specified by id1, 2, and 3 is determined. 2. The root is placed on the branch leading to the first external node (id1).
Returns:
rooted Tree

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, 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(long 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 (long) 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(long 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 (long) 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(long 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 (long) 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(long 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 (long) 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(long 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 (long) 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(long 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 (long) 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()

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(long id1,
                                  long 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.

modify

public Tree modify(java.lang.String s)
            throws java.lang.Exception
Rerootes and assignes sequence names to internal Nodes. The information is given as a String s which has the following format:
"ROOT: seqname1, seqname2, seqname3.
INTERNALNODE: seqname, seqname of outpost1, seqname of outpost2."
It can have has many INTERNALNODE fields as needed.
C style comments and white space will be removed.
Instead of white space, use "_".
"ROOT:" needs to be before "INTERNALNODE:"
Returns:
rooted Tree
See Also:
reRoot(String,String,String)

modify

public Tree modify(java.io.File f)
            throws java.lang.Exception
Rerootes and assignes sequence names to internal nodes. The information is read from a File f.
Returns:
rooted Tree
See Also:
modify(String)

modify

public Tree modify(java.net.URL url)
            throws java.lang.Exception
Rerootes and assignes sequence names to internal nodes. The information is read from a file at a given URL url.
Returns:
rooted Tree
See Also:
modify(String)

preorderReID

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

forester v1.2