ace.datatypes
Class FeatureDefinition

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

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

Objects of this class each hold meta-data about a feature, as specified by the four public fields. Objects of this class do not hold any feature values of particular instances.

Methods are available for viewing the features, veryifying the uniqueness of their names, saving them to disk and loading the, from disk.

See Also:
Serialized Form

Field Summary
 java.lang.String description
          A description of what the feature represents.
 int dimensions
          The number of values that exist for the feature for a given section of a data set.
 boolean is_sequential
          Specifies whether a feature can be applied to sub-section of a data set (e.g.
 java.lang.String name
          The name of the feature.
 
Constructor Summary
FeatureDefinition()
          Generate an empty FeatureDefinition with the name "Undefined Feature".
FeatureDefinition(weka.core.Instances instances, int index)
          Generates a FeatureDefintition from a Weka ARFF file.
FeatureDefinition(java.lang.String name, java.lang.String description, boolean is_sequential, int dimensions)
          Explicitly define a new Feature Definition.
 
Method Summary
 java.lang.String getFeatureDescription()
          Returns a formatted text description of the FeatureDescription object.
static java.lang.String getFeatureDescriptions(FeatureDefinition[] definitions)
          Returns a formatted text description of the given FeatureDescription objects.
static FeatureDefinition[] getMergedFeatureDefinitions(FeatureDefinition[][] to_combine)
          Takes multiple different arrays of feature definitions and combines them.
static FeatureDefinition[] parseFeatureDefinitionsFile(java.lang.String feature_key_file_path)
          Parses a feature_key_file_path XML file and returns an array of FeatureDefinitionwith objects holding its contents.
static void saveFeatureDefinitions(FeatureDefinition[] definitions, java.io.File to_save_to, java.lang.String comments)
          Saves a feature_key_file_path XML file with the contents specified in the given FeatureDefinition array and the comments specified in the comments parameter.
static java.lang.String verifyFeatureNameUniqueness(FeatureDefinition[] definitions)
          Checks if the given FeatureDefinitions hold any features with the same names.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

name

public java.lang.String name
The name of the feature. This name should be unique among each set of features.


description

public java.lang.String description
A description of what the feature represents. May be left as an empty string.


is_sequential

public boolean is_sequential
Specifies whether a feature can be applied to sub-section of a data set (e.g. a window of audio). A value of true means that it can, and a value of false means that the feature may only be extracted per data set.


dimensions

public int dimensions
The number of values that exist for the feature for a given section of a data set. This value will be 1, except for multi-dimensional features.

Constructor Detail

FeatureDefinition

public FeatureDefinition()
Generate an empty FeatureDefinition with the name "Undefined Feature".


FeatureDefinition

public FeatureDefinition(java.lang.String name,
                         java.lang.String description,
                         boolean is_sequential,
                         int dimensions)
Explicitly define a new Feature Definition.

Parameters:
name - The name of the feature. This name should be unique among each set of features.
description - A description of what the feature represents. May be left as an empty string.
is_sequential - Specifies whether a feature can be applied to sequential windows of a data set. A value of true means that it can, and a value of false means that only one feature value may be extracted per data set.
dimensions - The number of values that exist for the feature for a given section of a data set. This value will be 1, except for multi-dimensional features.

FeatureDefinition

public FeatureDefinition(weka.core.Instances instances,
                         int index)
Generates a FeatureDefintition from a Weka ARFF file.

Parameters:
instances - The WEKA instances that were extracted from the ARFF file.
index - Specifies which attribute of the WEKA ARFF file should be used for this FeatureDefintion.
Method Detail

getFeatureDescription

public java.lang.String getFeatureDescription()
Returns a formatted text description of the FeatureDescription object.

Returns:
The formatted description.

getFeatureDescriptions

public static java.lang.String getFeatureDescriptions(FeatureDefinition[] definitions)
Returns a formatted text description of the given FeatureDescription objects.

Parameters:
definitions - The feature definitions to describe.
Returns:
The formatted description.

parseFeatureDefinitionsFile

public static FeatureDefinition[] parseFeatureDefinitionsFile(java.lang.String feature_key_file_path)
                                                       throws java.lang.Exception
Parses a feature_key_file_path XML file and returns an array of FeatureDefinitionwith objects holding its contents. An exception is thrown if the file is invalid in some way or if the file contains multiple features with the same name.

Parameters:
feature_key_file_path - The path of the XML file to parse.
Throws:
java.lang.Exception - Informative exceptions is thrown if an invalid file or file path is specified or if the file holds multiple features with the same name.

saveFeatureDefinitions

public static void saveFeatureDefinitions(FeatureDefinition[] definitions,
                                          java.io.File to_save_to,
                                          java.lang.String comments)
                                   throws java.lang.Exception
Saves a feature_key_file_path XML file with the contents specified in the given FeatureDefinition array and the comments specified in the comments parameter. Also verifies that all of the given definitions have unique names, and throws an exception if they do not.

Parameters:
definitions - The FeatureDefinitions 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 or if any of the given definitions have the same name.

verifyFeatureNameUniqueness

public static java.lang.String verifyFeatureNameUniqueness(FeatureDefinition[] definitions)
Checks if the given FeatureDefinitions hold any features with the same names. Returns null if there are no duplicates and a formatted string of the names which are duplicated if there are duplicates.

Parameters:
definitions - The FeatureDefinitions to check for duplicate names.
Returns:
Null if there are no duplicates and the names of the duplicates if there are duplicates.

getMergedFeatureDefinitions

public static FeatureDefinition[] getMergedFeatureDefinitions(FeatureDefinition[][] to_combine)
                                                       throws java.lang.Exception
Takes multiple different arrays of feature definitions and combines them.

Parameters:
to_combine - The feature definitions to combine. Ordering does not matter and they will not be changed.
Returns:
The feature definitions combined together into a single array.
Throws:
java.lang.Exception - An informative exception is thrown if there are any multiples of the same features.