ace.datatypes
Class Taxonomy

java.lang.Object
  extended by ace.datatypes.Taxonomy
All Implemented Interfaces:
java.io.Serializable

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

Objects of this class each hold a taxonomy. Each class is stored as a string giving its name. The taxonomy is stored as a tree, with the root giving the name of the taxonomy. A given class may occur at more than one node in the tree.

Methods are available for adding classes, deleting classes, viewing the classes and various sub-sets of the classes, saving the classes to disk and loading the classes from disk. Methods are also available for checking which classes are in a taxonomy but not in a set of classificatiosns, and vice versa.

If the user only wishes to use a flat taxonomy, the addClass, deleteClass and getLeafLabels methods will be the most useful.

See Also:
Serialized Form

Field Summary
 javax.swing.tree.DefaultTreeModel taxonomy
          The tree holding the taxonomy.
 
Constructor Summary
Taxonomy()
          Generate an empty taxonomy with the name "Taxonomy".
Taxonomy(javax.swing.tree.DefaultTreeModel existing_taxonomy)
          Set the taxonomy to an existing DefaultTreeModel.
Taxonomy(weka.core.Instances instances)
          Generates a Taxonomy from a Weka ARFF file.
Taxonomy(java.lang.String taxonomy_name)
          Generate an empty taxonomy with the specified name.
 
Method Summary
 void addChildClass(javax.swing.tree.DefaultMutableTreeNode new_node, javax.swing.tree.DefaultMutableTreeNode parent_node)
          Inserts the given new_node into the taxonomy as the last child of the given parent_node.
 void addClass(java.lang.String new_class_name)
          Adds a new class with the given name to the taxonomy.
 void addSiblingClass(javax.swing.tree.DefaultMutableTreeNode new_node, javax.swing.tree.DefaultMutableTreeNode sibling_node)
          Inserts the given new_node into the taxonomy next to the given sibling_node.
 void deleteBranchOfTaxonomy(javax.swing.tree.DefaultMutableTreeNode node_to_delete)
          Deletes the given node_to_delete and all of its children from the taxonomy.
 void deleteClass(java.lang.String name_of_class_to_delete)
          Searches through the taxonomy and deletes all classes with the given name.
static Taxonomy generateTaxonomy(SegmentedClassification[] classifications)
          Automatically generates a flat taxonomy based on the class labels in the given SegmentedClassification object.
 java.lang.String[][] getAllParentsAndTheirDirectChildren()
          Returns the name of each class with children and its direct descendants.
 java.lang.String[] getClassesInClassificationsButNotTaxonomy(SegmentedClassification[] seg_classes)
          Returns an array listing the classes that are found in the given classifications (either overall classifications or classifications of sub-sections) but not in this taxonomy.
 java.lang.String[] getClassesInTaxonomyButNotInClassifications(SegmentedClassification[] seg_classes)
          Returns an array listing the classes that are found in this taxonomy but not in the given classifications (either overall classifications or classifications of sub-sections).
 java.lang.String getFormattedTreeStructure()
          Returns a string showing the entire taxonomy.
 java.lang.String[] getLeafLabels()
          Returns an array holding the labels of all leaf classes in the taxonomy field.
 java.lang.String[][] getLeafsAndTheirParents()
          Returns each leaf class in the taxonomy field and its ancestry.
 java.lang.String[] getMiddleLabels()
          Returns an array holding the labels of the classes in the taxonomy field that are neither leaves nor parent classes.
 java.lang.String[] getParentLabels()
          Returns an array holding the labels of all parent classes (i.e.
 boolean isTreeEmpty()
          Returns true if the taxonomy field is empty and false if it is not.
static Taxonomy parseTaxonomyFile(java.lang.String taxonomy_file_path)
          Parses a taxonomy_file XML file and returns a Taxonomy object that has had its taxonomy field populated with the file's contents.
static void saveTaxonomy(Taxonomy taxonomy_to_save, java.io.File to_save_to, java.lang.String comments)
          Saves a taxonomy_file XML file with the contents specified in the taxonomy_to_save parameter and the comments specified in the comments parameter.
static void setRootName(Taxonomy given_taxonomy, java.lang.String file_path)
          Sets the root of the given taxonomy to the name of the given file path (with directory structure and extension stripped off.
 void setTaxonomyName(java.lang.String taxonomy_name)
          Sets the name of the stored taxonomy to the given taxonomy_name.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

taxonomy

public javax.swing.tree.DefaultTreeModel taxonomy
The tree holding the taxonomy. The root element is the name of the taxonomy.

Constructor Detail

Taxonomy

public Taxonomy()
Generate an empty taxonomy with the name "Taxonomy".


Taxonomy

public Taxonomy(java.lang.String taxonomy_name)
Generate an empty taxonomy with the specified name.

Parameters:
taxonomy_name - The name to set as the name of the taxonomy.

Taxonomy

public Taxonomy(javax.swing.tree.DefaultTreeModel existing_taxonomy)
Set the taxonomy to an existing DefaultTreeModel.

Parameters:
existing_taxonomy - The tree to set the taxonomy field to.

Taxonomy

public Taxonomy(weka.core.Instances instances)
Generates a Taxonomy from a Weka ARFF file. Generates an empty taxonomy with the name TaxonomyFromARFF then adds the values of the class attribute one by one.

Method Detail

addClass

public void addClass(java.lang.String new_class_name)
Adds a new class with the given name to the taxonomy. The new class is added as the last child of the root in the taxonomy. If the taxonomy is flat, then this is equivalent to adding the new class to the end of the list of categories.

Parameters:
new_class_name - The name of the new class that is to be added to the taxonomy.

addChildClass

public void addChildClass(javax.swing.tree.DefaultMutableTreeNode new_node,
                          javax.swing.tree.DefaultMutableTreeNode parent_node)
Inserts the given new_node into the taxonomy as the last child of the given parent_node. The parent_node should already be in the taxonomy.

Parameters:
new_node - The node that is to be inserted into the taxonomy.
parent_node - The node that is already in the taxonomy that is to be the parent of the new node.

addSiblingClass

public void addSiblingClass(javax.swing.tree.DefaultMutableTreeNode new_node,
                            javax.swing.tree.DefaultMutableTreeNode sibling_node)
                     throws java.lang.Exception
Inserts the given new_node into the taxonomy next to the given sibling_node. The sibling_node must already be in the taxonomy.

Parameters:
new_node - The node that is to be inserted into the taxonomy.
sibling_node - The node that is already in the taxonomy that is to be at the same level and just preceeding the new node.
Throws:
java.lang.Exception - Informative exceptions is thrown if the sibling_node is not already in the taxonomy or if the parent of the sibling_node is null.

deleteClass

public void deleteClass(java.lang.String name_of_class_to_delete)
Searches through the taxonomy and deletes all classes with the given name. If the taxonomy is hierarchical, then children of classes with the given name are also deleted.

Parameters:
name_of_class_to_delete - The name that classes must have in order to be deleted.

deleteBranchOfTaxonomy

public void deleteBranchOfTaxonomy(javax.swing.tree.DefaultMutableTreeNode node_to_delete)
                            throws java.lang.Exception
Deletes the given node_to_delete and all of its children from the taxonomy.

Parameters:
node_to_delete - The node that is to be deleted.
Throws:
java.lang.Exception - An informative exception is thrown if the parent of the node_to_delete is null.

setTaxonomyName

public void setTaxonomyName(java.lang.String taxonomy_name)
Sets the name of the stored taxonomy to the given taxonomy_name.

Parameters:
taxonomy_name - The name to set as the name of the taxonomy.

getFormattedTreeStructure

public java.lang.String getFormattedTreeStructure()
Returns a string showing the entire taxonomy. The string is formatted with spaces and new lines to reflect the potentially hierarchical structure of the taxonomy. An empty string is returned if the taxonomy is empty.

Returns:
The taxonomy in the form of a formatted string.

getLeafLabels

public java.lang.String[] getLeafLabels()
Returns an array holding the labels of all leaf classes in the taxonomy field. No duplicates are present.

Returns:
The labels of all leaf classes in the taxonomy field, with duplicates removed.

getParentLabels

public java.lang.String[] getParentLabels()
Returns an array holding the labels of all parent classes (i.e. classes at the highest level of the taxonomy) in the taxonomy field. No duplicates are present.

Returns:
The labels of all parent classes in the taxonomy field, with duplicates removed.

getMiddleLabels

public java.lang.String[] getMiddleLabels()
Returns an array holding the labels of the classes in the taxonomy field that are neither leaves nor parent classes. No duplicates are present.

Returns:
The labels of all mid-level categories in the taxonomy field, with duplicates removed.

getLeafsAndTheirParents

public java.lang.String[][] getLeafsAndTheirParents()
Returns each leaf class in the taxonomy field and its ancestry. Duplicates are removed (i.e. if the same leaf class appears more than once in the taxonomy then the duplicate is removed and the ancestors are combined).

This information is returned in the form of a 2-D array of Strings. The first indice specifies a particular leaf class and its ancestors. he second indice specifies the particular ancestor of a given leaf class or the leaf class itself. Indice 0 always corresponds to the name of the leaf class itself, but the order of the ancestors is not necessarily meaningful.

Returns:
The leaf categories and their ancestors.

getAllParentsAndTheirDirectChildren

public java.lang.String[][] getAllParentsAndTheirDirectChildren()
Returns the name of each class with children and its direct descendants. The first indice corresponds to the different parents. The second indice goes through the children. The first entry of each row is the name of the parent.

Returns:
The names of parent classes and their children.

isTreeEmpty

public boolean isTreeEmpty()
Returns true if the taxonomy field is empty and false if it is not.

Returns:
Whether or not the taxonomy field is empty.

getClassesInClassificationsButNotTaxonomy

public java.lang.String[] getClassesInClassificationsButNotTaxonomy(SegmentedClassification[] seg_classes)
Returns an array listing the classes that are found in the given classifications (either overall classifications or classifications of sub-sections) but not in this taxonomy. No name of a class witll be returned more than once in the returned array. Returns null if there are no such classes.

Parameters:
seg_classes - The classifications to check.
Returns:
The outstanding classes. Null is returned if there are no outstanding classes.

getClassesInTaxonomyButNotInClassifications

public java.lang.String[] getClassesInTaxonomyButNotInClassifications(SegmentedClassification[] seg_classes)
Returns an array listing the classes that are found in this taxonomy but not in the given classifications (either overall classifications or classifications of sub-sections). No name of a class witll be returned more than once in the returned array. Returns null if there are no such classes.

Parameters:
seg_classes - The classifications to check.
Returns:
The outstanding classes. Null is returned if there are no outstanding classes.

parseTaxonomyFile

public static Taxonomy parseTaxonomyFile(java.lang.String taxonomy_file_path)
                                  throws java.lang.Exception
Parses a taxonomy_file XML file and returns a Taxonomy object that has had its taxonomy field populated with the file's contents. Throws an informative exception if a problem occurs or if the file path or the file itself is invalid. Sets the name of the root to the file name of the taxonomy with the extension removed.

Parameters:
taxonomy_file_path - The path of the XML file to parse.
Returns:
The loaded taxonomy.
Throws:
java.lang.Exception - Informative exceptions is thrown if an invalid file or file path is specified.

saveTaxonomy

public static void saveTaxonomy(Taxonomy taxonomy_to_save,
                                java.io.File to_save_to,
                                java.lang.String comments)
                         throws java.lang.Exception
Saves a taxonomy_file XML file with the contents specified in the taxonomy_to_save parameter and the comments specified in the comments parameter.

Parameters:
taxonomy_to_save - The taxonomy to save.
to_save_to - The file to save to.
comments - Any comments to be saved inside the comments element of the XML file.
Throws:
java.lang.Exception - An informative exception is thrown if the file cannot be saved.

setRootName

public static void setRootName(Taxonomy given_taxonomy,
                               java.lang.String file_path)
Sets the root of the given taxonomy to the name of the given file path (with directory structure and extension stripped off.

Parameters:
given_taxonomy - The Taxonomy to update.
file_path - The path of the file to base the root name on.

generateTaxonomy

public static Taxonomy generateTaxonomy(SegmentedClassification[] classifications)
Automatically generates a flat taxonomy based on the class labels in the given SegmentedClassification object.

Parameters:
classifications - The SegmentedClassification object from which to derive the classes of the Taxonomy.
Returns:
A flat Taxonomy object containing the same classes as the given SegmentedClassification object.