bodhidharma.classifiers.feedforward_neural_networks
Class FeedForwardNeuralNetwork

java.lang.Object
  extended by bodhidharma.classifiers.SupervisedClassifier
      extended by bodhidharma.classifiers.feedforward_neural_networks.FeedForwardNeuralNetwork

public class FeedForwardNeuralNetwork
extends SupervisedClassifier

An interface for using a backpropagation feedforward neural network that is actually implemented as a LinkedNodes object. The neural networks used here are limited to perceptrons and networks with one layer of hidden nodes. The learning rate, the momentum and the range of initial seed weights are user definable. The number of hidden nodes is set to a user definable coefficient multiplied by the square root of the sum of the number of input and output nodes.

One input node is assigned for each feature and one output node is assigned for each category. The sigmoidal activation function is used, and all values of output nodes are trained to fall between 0.2 and 0.8. Output nodes are trained to 0.8 if a feature set belongs to the corresponding feature set and to 0.2 if it does not. However, these are scaled by the classify method to fall between 0.0 and 1.0, so this detail is hidden from the user.

This classifier can be trained using exemplar based learning to classify arbitrary feature sets. This implementation makes it possible to assign more than one label to a single feature set.

Feature sets are fed into the classifier as arrays of doubles. Categories are specified as arrays of Strings.

Use the train method to train the classifier (the getFeatureNames method is useful for deteriming the features that can be fed to the classifer).

One constructor is provided for creating a new network and one is provided for parsing XML code and using it to reconstruct a trained network.

Use the classify method to classify feature sets once training has been completed (the getCategories method is useful for determining what categories feature sets can be classified into and for determining the order of the categories when parsing classification results).

Use the save method to save the classifier and its current state to disk.

Use the getClassifierName and getClassifierParameters methods to obtain information about the classifier.

Use the getClassifierIdentifier method to get a name or code that was given to an instantiation of the classifier when it was constructed. This identifier can be used by external classes to identify the instantiation.

Author:
Cory McKay

Field Summary
 
Fields inherited from class bodhidharma.classifiers.SupervisedClassifier
categories, feature_names, identifier, training_monitor
 
Constructor Summary
FeedForwardNeuralNetwork(java.lang.String file_path)
          Parse the file specified by the given file path to recreate the specificed trained classifier.
FeedForwardNeuralNetwork(java.lang.String[] labels_of_features, java.lang.String[] labels_of_categories, java.lang.String identification_string, NeuralNetworkJFrame network_settings)
          Generate a neural network with the given parameters and randomly generated weights.
 
Method Summary
 double[][] classify(double[][] feature_sets, java.lang.String[] feature_labels)
          Returns the relative scores of each of the possible categories when the given sets of features are classified.
 java.lang.String getClassifierName()
          Returns the name of the type of classifier.
 java.lang.String getClassifierParameters()
          Returns a String describing the parameters of the classifier.
 void save(java.io.File place_to_save)
          Saves all of the fields to the given file.
 double[] train(double[][] unscrambled_feature_sets, java.lang.String[] feature_labels, java.lang.String[][] unscrambled_model_categories, int iterations, double acceptable_threshold, int consecutive_iterations)
          Trains the network using the given feature sets.
 
Methods inherited from class bodhidharma.classifiers.SupervisedClassifier
getCategories, getClassifierIdentifier, getFeatureNames, getModelResults, getOrderedFeatureSets, setTrainingMonitor
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FeedForwardNeuralNetwork

public FeedForwardNeuralNetwork(java.lang.String[] labels_of_features,
                                java.lang.String[] labels_of_categories,
                                java.lang.String identification_string,
                                NeuralNetworkJFrame network_settings)
Generate a neural network with the given parameters and randomly generated weights. Sets the number of hidden units to the coefficient specified in the network_settings parameter multiplied by the square root of the sum of the number of input and output nodes.

Parameters:
labels_of_features - The names of the features that will be fed into the input nodes.
labels_of_categories - The names of categories that correspond to the output nodes.
identification_string - An identifier that can be associated with the network so that outside classes can identify it.
network_settings - Contains network initialization settings.

FeedForwardNeuralNetwork

public FeedForwardNeuralNetwork(java.lang.String file_path)
                         throws java.lang.Exception
Parse the file specified by the given file path to recreate the specificed trained classifier. Throws an exception if problems occur during parsing.

Parameters:
file_path - The file path of a FeedForwardNeuralNetwork_file that this instantiation is to be based on.
Throws:
java.lang.Exception
Method Detail

getClassifierName

public java.lang.String getClassifierName()
Returns the name of the type of classifier. This information can be used by external classes to identify the type of classifier in situations such as when the configuration of a trained classifier is being read from a file.

Specified by:
getClassifierName in class SupervisedClassifier

getClassifierParameters

public java.lang.String getClassifierParameters()
Returns a String describing the parameters of the classifier. This includes classifier name, learning rate, momentum and number of hidden nodes.

Specified by:
getClassifierParameters in class SupervisedClassifier

train

public double[] train(double[][] unscrambled_feature_sets,
                      java.lang.String[] feature_labels,
                      java.lang.String[][] unscrambled_model_categories,
                      int iterations,
                      double acceptable_threshold,
                      int consecutive_iterations)
               throws java.lang.Exception
Trains the network using the given feature sets. The first indice of the unscrambled_feature_sets parameter corresponds to different feature sets. The second indice corresponds to different features in the given featue set. It should be noted that all feature sets must use the same features in the same order as given in the feature_labels parameter.

The feature_labels parameter specifies the names of each of the features in the unscrambled_feature_sets parameter. The features in the unscrambled_feature_sets parameter will automatically matched to the features in the feature_names field based on the content of the feature_labels parameter unless a value of null is passed to the feature_labels. In this case, the feature values in the unscrambled_feature_sets parameter will simply be fed into the classifier in the order that they occur.

The unscrambled_model_categories parameter gives the categories of each of the given feature sets. The first indice corresponds to the feature set. The second indice corresponds to different model categories for the given feature set. Only categories to which the feature set belongs should be included.

The iterations parameter specifies the number of training iterations performed. If a negative value is passed here, then the number of iterations to perform is calculated automatically based on the acceptable_threshold parameter, which specifies the absolute rate of change of the sum of squared error below which training will stop, and the consecutive_iterations parameter, which specifies the number of consecutive iterations for which the rate of change must be below this threshold in order for training to stop. The number of iterations that go by will never exceed the absolute valud of the iterations value, irregardless of the other parameters.

For example, if a value of 1000 is given for iterations, then 1000 iterations will be performed irregardless of the other parameters. If a value of -1000 is given, then training will automatically stop if the absolute value of the rate of change of the sum of squared error from one sample to the next falls below the acceptable_threshold parameter for consecutive_iterations iterations, but no more than 1000 iterations will be performed in any case.

The returned double is an average sum of squared error after training iterations. The indice of the returned array corresponds to the iteration of training that the error is associated with.

An exception if thrown if the feature_labels do not contain the same names as feature_names (although a different ordering is permitted) or if any of the feature sets in unscrambled_feature_sets have a different number of features than feature_names. An exception is also thrown if unscrambled_feature_sets and unscrambled_model_categories have different sizes in regard to their first parameters. An exception is thrown if the given_results parameter contains a name not present in the categories field or if it contains the same category more than once.

Specified by:
train in class SupervisedClassifier
Throws:
java.lang.Exception

classify

public double[][] classify(double[][] feature_sets,
                           java.lang.String[] feature_labels)
                    throws java.lang.Exception
Returns the relative scores of each of the possible categories when the given sets of features are classified. There is one entry in the returned array for each of the entries in the categories field, and they appear in the same order. Higher scores in the returned array correspond to a greater certainty that the feature set should have the corresponding label. Scores fall in the range between 0.0 and 1.0. The first indice of the returned array corresponds to the feature set and the second corresponds to the category. The order of the categories is the same as in the categories field and the order of the feature sets is the same as the order in which they were passed to the feature_sets parameter.

The feature_sets parameter specifies the feature sets to be classified. The first indice corresponds to different feature sets. The second indice corresponds to different features in the given featue set. It should be noted that all feature sets must use the same features in the same order as given in the feature_labels parameter.

The feature_labels parameter specifies the names of each of the features in the feature_sets parameter. The features in the feature_sets parameter will automatically matched to the features in the feature_names field based on the content of the feature_labels parameter unless a value of null is passed to the feature_labels. In this case, the feature values in the feature_sets parameter will simply be fed into the classifier in the order that they occur.

An exception if thrown if the feature_labels do not contain the same names as feature_names (although a different ordering is permitted) or if any of the feature sets in feature_sets have a different number of features than feature_names.

Specified by:
classify in class SupervisedClassifier
Throws:
java.lang.Exception

save

public void save(java.io.File place_to_save)
          throws java.lang.Exception
Saves all of the fields to the given file. Throws an exception if a problem occurs.

Specified by:
save in class SupervisedClassifier
Throws:
java.lang.Exception