org.forester.phylogeny
Class Phylogeny

java.lang.Object
  extended by org.forester.phylogeny.Phylogeny

public class Phylogeny
extends Object


Field Summary
static boolean ALLOW_MULTIPLE_PARENTS_DEFAULT
           
 
Constructor Summary
Phylogeny()
          Default Phylogeny constructor.
 
Method Summary
 void addAsChild(PhylogenyNode parent)
          Adds this Phylogeny to the list of child nodes of PhylogenyNode parent and sets the parent of this to parent.
 void addAsSibling(PhylogenyNode sibling)
           
 double calculateSubtreeHeight(PhylogenyNode n)
          This calculates the height of the subtree emanating at n for rooted, tree-shaped phylogenies
 Phylogeny copy()
          Returns a deep copy of this Phylogeny.
 void deleteSubtree(PhylogenyNode remove_us, boolean collapse_resulting_node_with_one_desc)
          Need the delete and/or rehash _idhash (not done automatically to allow client multiple deletions in linear time).
 void externalNodesHaveChanged()
           
 String[] getAllExternalNodeNames()
           
 Confidence getConfidence()
           
 String getDescription()
           
 String getDistanceUnit()
           
 Set<PhylogenyNode> getExternalNodes()
          Warning.
 PhylogenyNode getFirstExternalNode()
          Returns the first external PhylogenyNode.
 double getHeight()
          This calculates the height for rooted, tree-shaped phylogenies.
 Identifier getIdentifier()
           
 String getName()
          Returns the name of this Phylogeny.
 PhylogenyNode getNode(int id)
          Finds the PhylogenyNode of this Phylogeny which has a matching ID number.
 PhylogenyNode getNode(String name)
          Returns a PhylogenyNode of this Phylogeny which has a matching name.
 List<PhylogenyNode> getNodes(String name)
          Returns a List with references to all Nodes of this Phylogeny which have a matching name.
 List<PhylogenyNode> getNodesViaSequenceName(String seq_name)
           
 List<PhylogenyNode> getNodesViaTaxonomyCode(String taxonomy_code)
           
 List<PhylogenyNode> getNodesWithMatchingSpecies(String specname)
          Returns a Vector with references to all Nodes of this Phylogeny which have a matching species name.
 PhylogenyNode getNodeViaSequenceName(String seq_name)
           
 PhylogenyNode getNodeViaTaxonomyCode(String taxonomy_code)
           
 int getNumberOfBranches()
           
 int getNumberOfExternalNodes()
          Returns the sum of external Nodes of this Phylogeny (int).
 List<PhylogenyNode> getParalogousNodes(PhylogenyNode n, String[] taxonomyCodeRange)
          Returns all paralogs of the external PhylogenyNode n of this Phylogeny.
 PhylogenyNode getRoot()
          Returns the root PhylogenyNode of this Phylogeny.
 String getType()
           
 void hashIDs()
          Hashes the ID number of each PhylogenyNode of this Phylogeny to its corresponding PhylogenyNode, in order to make method getNode( id ) run in constant time.
 void init()
          Deletes this Phylogeny.
 boolean isCompletelyBinary()
          Returns whether this is a completely binary tree (i.e.
 boolean isEmpty()
          Checks whether a Phylogeny object is deleted (or empty).
 boolean isRerootable()
           
 boolean isRooted()
          Returns true is this Phylogeny is rooted.
 boolean isTree()
           
 PhylogenyNodeIterator iteratorExternalForward()
           
 PhylogenyNodeIterator iteratorLevelOrder()
           
 PhylogenyNodeIterator iteratorPostorder()
           
 PhylogenyNodeIterator iteratorPreorder()
           
 int levelOrderReID(int start_label)
          Resets the ID numbers of the nodes of this Phylogeny in level order, starting with start_label (for the root).
 void orderAppearance(boolean order)
          Arranges the order of childern for each node of this Phylogeny in such a way that either the branch with more children is on top (right) or on bottom (left), dependent on the value of boolean order.
 void preOrderReId()
           
 int preOrderReId(int start_label)
          Resets the ID numbers of the Nodes of this Phylogeny in preorder, starting with i.
WARNING.
 void printExtNodes()
          Prints descriptions of all external Nodes of this Phylogeny to System.out.
 void recalculateNumberOfExternalDescendants(boolean consider_collapsed_nodes)
          (Re)counts the number of children for each PhylogenyNode of this Phylogeny.
 void reRoot(int id)
          Places the root of this Phylogeny on the parent branch of the PhylogenyNode with a corresponding ID.
 void reRoot(PhylogenyBranch b)
          Places the root of this Phylogeny on Branch b.
 void reRoot(PhylogenyNode n)
          Places the root of this Phylogeny on the parent branch PhylogenyNode n.
 void reRoot(PhylogenyNode n, double distance_n_to_parent)
           
 void setAllNodesToNotCollapse()
          Sets all Nodes of this Phylogeny to not-collapsed.
 void setConfidence(Confidence confidence)
           
 void setDescription(String description)
           
 void setDistanceUnit(String _distance_unit)
           
 void setIdentifier(Identifier identifier)
           
 void setIndicatorsToZero()
          Sets the indicators of all Nodes of this Phylogeny to 0.
 void setName(String s)
          Sets the name of this Phylogeny to s.
 void setRerootable(boolean rerootable)
           
 void setRoot(PhylogenyNode n)
           
 void setRooted(boolean b)
          Sets whether this Phylogeny is rooted or not.
 void setType(String type)
           
 Phylogeny subTree(PhylogenyNode node)
           
 void swapChildren(PhylogenyNode node)
          Swaps the the two childern of a PhylogenyNode node of this Phylogeny.
 String toNewHampshire(boolean simple_nh)
           
 String toNewHampshireX()
           
 String toNexus()
           
 String toPhyloXML(int phyloxml_level)
           
 String toString()
          Converts this Phylogeny to a New Hampshire X (String) representation.
 void unRoot()
          Removes the root PhylogenyNode this Phylogeny.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ALLOW_MULTIPLE_PARENTS_DEFAULT

public static final boolean ALLOW_MULTIPLE_PARENTS_DEFAULT
See Also:
Constant Field Values
Constructor Detail

Phylogeny

public Phylogeny()
Default Phylogeny constructor. Constructs an empty Phylogeny.

Method Detail

addAsChild

public void addAsChild(PhylogenyNode parent)
Adds this Phylogeny to the list of child nodes of PhylogenyNode parent and sets the parent of this to parent.

Parameters:
n - the PhylogenyNode to add

addAsSibling

public void addAsSibling(PhylogenyNode sibling)

calculateSubtreeHeight

public double calculateSubtreeHeight(PhylogenyNode n)
This calculates the height of the subtree emanating at n for rooted, tree-shaped phylogenies

Parameters:
n - the root-node of a subtree
Returns:
the height of the subtree emanating at n

copy

public Phylogeny copy()
Returns a deep copy of this Phylogeny.

(The resulting Phylogeny has its references in the external nodes corrected, if they are lacking/obsolete in this.)


deleteSubtree

public void deleteSubtree(PhylogenyNode remove_us,
                          boolean collapse_resulting_node_with_one_desc)
Need the delete and/or rehash _idhash (not done automatically to allow client multiple deletions in linear time). Need to call 'recalculateNumberOfExternalDescendants(boolean)' after this if tree is to be displayed.

Parameters:
remove_us - the parent node of the subtree to be deleted

externalNodesHaveChanged

public void externalNodesHaveChanged()

getAllExternalNodeNames

public String[] getAllExternalNodeNames()

getConfidence

public Confidence getConfidence()

getDescription

public String getDescription()

getDistanceUnit

public String getDistanceUnit()

getExternalNodes

public Set<PhylogenyNode> getExternalNodes()
Warning. The order of the returned nodes is random -- and hence cannot be relied on.

Returns:
Unordered set of PhylogenyNode

getFirstExternalNode

public PhylogenyNode getFirstExternalNode()
Returns the first external PhylogenyNode.


getHeight

public double getHeight()
This calculates the height for rooted, tree-shaped phylogenies. The height is the longest distance from the root to an external node. Please note. Child nodes of collapsed nodes are ignored -- which is useful for display purposes but might be misleading for other applications.

Returns:
the height for rooted, tree-shaped phylogenies

getIdentifier

public Identifier getIdentifier()

getName

public String getName()
Returns the name of this Phylogeny.


getNode

public PhylogenyNode getNode(int id)
                      throws NoSuchElementException
Finds the PhylogenyNode of this Phylogeny 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 PhylogenyNode to find
Returns:
PhylogenyNode with matching ID, null if not found
Throws:
NoSuchElementException

getNode

public PhylogenyNode getNode(String name)
Returns a PhylogenyNode of this Phylogeny which has a matching name. Throws an Exception if seqname is not present in this or not unique.

Parameters:
name - name (String) of PhylogenyNode to find
Returns:
PhylogenyNode with matchin name

getNodes

public List<PhylogenyNode> getNodes(String name)
Returns a List with references to all Nodes of this Phylogeny which have a matching name.

Parameters:
name - name (String) of Nodes to find
Returns:
Vector of references to Nodes of this Phylogeny with matching names
See Also:
getNodesWithMatchingSpecies(String)

getNodesViaSequenceName

public List<PhylogenyNode> getNodesViaSequenceName(String seq_name)

getNodesViaTaxonomyCode

public List<PhylogenyNode> getNodesViaTaxonomyCode(String taxonomy_code)

getNodesWithMatchingSpecies

public List<PhylogenyNode> getNodesWithMatchingSpecies(String specname)
Returns a Vector with references to all Nodes of this Phylogeny which have a matching species name.

Parameters:
specname - species name (String) of Nodes to find
Returns:
Vector of references to Nodes of this Phylogeny with matching species names.
See Also:
getNodes(String)

getNodeViaSequenceName

public PhylogenyNode getNodeViaSequenceName(String seq_name)

getNodeViaTaxonomyCode

public PhylogenyNode getNodeViaTaxonomyCode(String taxonomy_code)

getNumberOfBranches

public int getNumberOfBranches()

getNumberOfExternalNodes

public int getNumberOfExternalNodes()
Returns the sum of external Nodes of this Phylogeny (int).


getParalogousNodes

public List<PhylogenyNode> getParalogousNodes(PhylogenyNode n,
                                              String[] taxonomyCodeRange)
Returns all paralogs of the external PhylogenyNode n of this Phylogeny. paralog are returned as List of node references.

PRECONDITION: This tree must be binary and rooted, and speciation - duplication need to be assigned for each of its internal Nodes.

Returns null if this Phylogeny is empty or if n is internal.

(Last modified: 11/22/00) Olivier CHABROL : olivier.chabrol@univ-provence.fr

Parameters:
n - external PhylogenyNode whose orthologs are to be returned
Returns:
Vector of references to all orthologous Nodes of PhylogenyNode n of this Phylogeny, null if this Phylogeny is empty or if n is internal

getRoot

public PhylogenyNode getRoot()
Returns the root PhylogenyNode of this Phylogeny.


getType

public String getType()

hashIDs

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


init

public void init()
Deletes this Phylogeny.


isCompletelyBinary

public boolean isCompletelyBinary()
Returns whether this is a completely binary tree (i.e. all internal nodes are bifurcations).


isEmpty

public boolean isEmpty()
Checks whether a Phylogeny object is deleted (or empty).

Returns:
true if the tree is deleted (or empty), false otherwise

isRerootable

public boolean isRerootable()

isRooted

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


isTree

public boolean isTree()

iteratorExternalForward

public PhylogenyNodeIterator iteratorExternalForward()

iteratorLevelOrder

public PhylogenyNodeIterator iteratorLevelOrder()

iteratorPostorder

public PhylogenyNodeIterator iteratorPostorder()

iteratorPreorder

public PhylogenyNodeIterator iteratorPreorder()

levelOrderReID

public int levelOrderReID(int start_label)
Resets the ID numbers of the nodes of this Phylogeny in level order, starting with start_label (for the root).
WARNING. After this method has been called, node IDs are no longer unique.
WARNING. Afterwards static method getNodeCount of PhylogenyNode is might not be correct anymore (depending on what start_label was used). Returns the maximum used ID number which is used for the child nodes furthest away from the root.

Parameters:
start_label - the starting value for the ID numbers
Returns:
the maximum used ID number

orderAppearance

public void orderAppearance(boolean order)
                     throws IllegalStateException
Arranges the order of childern for each node of this Phylogeny in such a way that either the branch with more children is on top (right) or on bottom (left), dependent on the value of boolean order.

Parameters:
order - decides in which direction to order
Throws:
IllegalStateException

preOrderReId

public void preOrderReId()

preOrderReId

public int preOrderReId(int start_label)
Resets the ID numbers of the Nodes of this Phylogeny in preorder, starting with i.
WARNING. Afterwards static method getNodeCount of PhylogenyNode is might not be correct anymore (depending on what start_label was used).

Parameters:
start_label - the starting value (int)
Returns:
start_label plus the total number of Nodes of this Phylogeny (int)

printExtNodes

public void printExtNodes()
Prints descriptions of all external Nodes of this Phylogeny to System.out.


recalculateNumberOfExternalDescendants

public void recalculateNumberOfExternalDescendants(boolean consider_collapsed_nodes)
(Re)counts the number of children for each PhylogenyNode of this Phylogeny. As an example, this method needs to be called after a Phylogeny has been reRooted and it is to be displayed.

Parameters:
consider_collapsed_nodes - set to true to take into account collapsed nodes (collapsed nodes have 1 child).

reRoot

public void reRoot(int id)
Places the root of this Phylogeny on the parent branch of the PhylogenyNode with a corresponding ID. The new root is always placed on the middle of the branch. If the resulting reRooted Phylogeny is to be used any further, in most cases the following methods have to be called on the resulting Phylogeny:

  • recalculateNumberOfExternalDescendants(boolean)
  • recalculateAndReset()

    Parameters:
    id - ID (int) of PhylogenyNode of this Phylogeny

  • reRoot

    public void reRoot(PhylogenyBranch b)
    Places the root of this Phylogeny on Branch b. The new root is always placed on the middle of the branch b.


    reRoot

    public void reRoot(PhylogenyNode n)
    Places the root of this Phylogeny on the parent branch PhylogenyNode n. The new root is always placed on the middle of the branch.

    If the resulting reRooted Phylogeny is to be used any further, in most cases the following three methods have to be called on the resulting Phylogeny:

    (Last modified: 10/01/01)

    Parameters:
    n - PhylogenyNode of this Phylogeny\

    reRoot

    public void reRoot(PhylogenyNode n,
                       double distance_n_to_parent)

    setAllNodesToNotCollapse

    public void setAllNodesToNotCollapse()
    Sets all Nodes of this Phylogeny to not-collapsed.

    In most cases methods adjustNodeCount(false) and recalculateAndReset() need to be called after this method has been called.


    setConfidence

    public void setConfidence(Confidence confidence)

    setDescription

    public void setDescription(String description)

    setDistanceUnit

    public void setDistanceUnit(String _distance_unit)

    setIdentifier

    public void setIdentifier(Identifier identifier)

    setIndicatorsToZero

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


    setName

    public void setName(String s)
    Sets the name of this Phylogeny to s.


    setRerootable

    public void setRerootable(boolean rerootable)

    setRoot

    public void setRoot(PhylogenyNode n)

    setRooted

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


    setType

    public void setType(String type)

    subTree

    public Phylogeny subTree(PhylogenyNode node)
                      throws IllegalStateException
    Throws:
    IllegalStateException

    swapChildren

    public void swapChildren(PhylogenyNode node)
                      throws IllegalStateException
    Swaps the the two childern of a PhylogenyNode node of this Phylogeny.

    (Last modified: 06/13/01)

    Parameters:
    node - a PhylogenyNode of this Phylogeny
    Throws:
    IllegalStateException

    toNewHampshire

    public String toNewHampshire(boolean simple_nh)

    toNewHampshireX

    public String toNewHampshireX()

    toNexus

    public String toNexus()

    toPhyloXML

    public String toPhyloXML(int phyloxml_level)

    toString

    public String toString()
    Converts this Phylogeny to a New Hampshire X (String) representation.

    Overrides:
    toString in class Object
    Returns:
    New Hampshire X (String) representation of this
    See Also:
    toNewHampshireX()

    unRoot

    public void unRoot()
                throws IllegalStateException
    Removes the root PhylogenyNode this Phylogeny.

    Throws:
    IllegalStateException