org.joone.helpers.factory

Class JooneTools

java.lang.Object

org.joone.helpers.factory.JooneTools

public class JooneTools
extends java.lang.Object

Utility class to build/train/interrogate neural networks. By using this class, it's possible to easily build/train and interrogate a neural network with only 3 rows of code, as in this example: // Create an MLP network with 3 layers [2,2,1 nodes] with a logistic output layer NeuralNet nnet = JooneTools.create_standard(new int[]{2,2,1}, JooneTools.LOGISTIC); // Train the network for 5000 epochs, or until the rmse < 0.01 double rmse = JooneTools.train(nnet, inputArray, desiredArray, 5000, 0.01, 0, null); // Interrogate the network double[] output = JooneTools.interrogate(nnet, testArray);

Field Summary

Fields

Modifier and Type	Field and Description
static int	BPROP_BATCH Backprop batch learning algorithm
static int	BPROP_ONLINE Backprop on-line (incremental) learning algorithm
static int	GAUSSIAN Gaussian output layer (unsupervised Kohonen)
static int	LINEAR Linear output layer
static int	LOGISTIC Logistic (sigmoid) output layer
static int	RPROP Resilient Backprop learning algorithm
static int	SOFTMAX Softmax output layer
static int	WTA WTA output layer (unsupervised Kohonen)

Constructor Summary

Constructors

Constructor and Description
JooneTools()

Method Summary

Modifier and Type	Method and Description
static double[][]	compare_on_stream(NeuralNet nnet, StreamInputSynapse input, StreamInputSynapse desired) Permits to compare the output and target data of a trained neural network using StreamInputSynapses as the input/desired data sources.
static double[][]	compare(NeuralNet nnet, double[][] input, double[][] desired) Permits to compare the output and target data of a trained neural network using 2D array of double as the input/desired data sources.
static NeuralNet	create_standard(int[] nodes, int outputType) Creates a feed forward neural network without I/O components.
static NeuralNet	create_timeDelay(int[] nodes, int taps, int outputType) Creates a feed forward neural network without I/O components.
static NeuralNet	create_unsupervised(int[] nodes, int outputType) Creates an unsupervised neural network without I/O components.
static double[][]	getDataFromStream(StreamInputSynapse dataSet, int firstRow, int lastRow, int firstCol, int lastCol) Extracts a subset of data from the StreamInputSynapse passed as parameter.
static double[]	interrogate(NeuralNet nnet, double[] input) Interrogate a neural network with an array of doubles and returns the output of the neural network.
static NeuralNet	load_fromStream(java.io.InputStream stream) Loads a neural network from an InputStream
static NeuralNet	load(java.lang.String fileName) Loads a neural network from a file
static void	save_toStream(NeuralNet nnet, java.io.OutputStream stream) Saves a neural network to an OutputStream
static void	save(NeuralNet nnet, java.io.File fileName) Saves a neural network to a file
static void	save(NeuralNet nnet, java.lang.String fileName) Saves a neural network to a file
static double	test_on_stream(NeuralNet nnet, StreamInputSynapse input, StreamInputSynapse desired) Tests a neural network using using StreamInputSynapses as the input/desired data sources.
static double	test(NeuralNet nnet, double[][] input, double[][] desired) Tests a neural network using the input/desired pairs contained in 2D arrays of double.
static double	train_complete(NeuralNet nnet, int epochs, double stopRMSE, int epochs_btw_reports, java.lang.Object stdOut, boolean async) Trains a complete neural network, i.e.
static double	train_on_stream(NeuralNet nnet, StreamInputSynapse input, StreamInputSynapse desired, int epochs, double stopRMSE, int epochs_btw_reports, java.lang.Object stdOut, boolean async) Trains a neural network using StreamInputSynapses as the input/desired data sources.
static void	train_unsupervised(NeuralNet nnet, double[][] input, int epochs, int epochs_btw_reports, java.lang.Object stdOut, boolean async) Trains a neural network in unsupervised mode (SOM and PCA networks) using the input contained in a 2D array of double.
static double	train(NeuralNet nnet, double[][] input, double[][] desired, int epochs, double stopRMSE, int epochs_btw_reports, java.lang.Object stdOut, boolean async) Trains a neural network using the input/desired pairs contained in 2D arrays of double.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LINEAR

public static final int LINEAR

Linear output layer

See Also:

Constant Field Values

LOGISTIC

public static final int LOGISTIC

Logistic (sigmoid) output layer

See Also:

Constant Field Values

SOFTMAX

public static final int SOFTMAX

Softmax output layer

See Also:

Constant Field Values

WTA

public static final int WTA

WTA output layer (unsupervised Kohonen)

See Also:

Constant Field Values

GAUSSIAN

public static final int GAUSSIAN

Gaussian output layer (unsupervised Kohonen)

See Also:

Constant Field Values

BPROP_ONLINE

public static final int BPROP_ONLINE

Backprop on-line (incremental) learning algorithm

See Also:

Constant Field Values

BPROP_BATCH

public static final int BPROP_BATCH

Backprop batch learning algorithm

See Also:

Constant Field Values

RPROP

public static final int RPROP

Resilient Backprop learning algorithm

See Also:

Constant Field Values

Constructor Detail

JooneTools

public JooneTools()

Method Detail

create_standard

public static NeuralNet create_standard(int[] nodes,
                                        int outputType)
                                 throws java.lang.IllegalArgumentException

Creates a feed forward neural network without I/O components.

Parameters:

nodes - array of integers containing the nodes of each layer

outputType - the type of output layer. One of 'LINEAR', 'SOFTMAX', 'LOGISTIC'

Returns:

The neural network created

Throws:

java.lang.IllegalArgumentException - .

create_timeDelay

public static NeuralNet create_timeDelay(int[] nodes,
                                         int taps,
                                         int outputType)
                                  throws java.lang.IllegalArgumentException

Creates a feed forward neural network without I/O components.

Parameters:

nodes - array of integers containing the nodes of each layer

outputType - the type of output layer. One of 'LINEAR', 'SOFTMAX', 'LOGISTIC'

Returns:

The neural network created

Throws:

java.lang.IllegalArgumentException - .

create_unsupervised

public static NeuralNet create_unsupervised(int[] nodes,
                                            int outputType)
                                     throws java.lang.IllegalArgumentException

Creates an unsupervised neural network without I/O components. This method is able to build the following kind of networks, depending on the 'outputType' parameter: WTA - Kohonen network with a WinnerTakeAll output layer GAUSSIAN - Kohonen network with a gaussian output layer The nodes array must contain 3 elements, with the following meaning: nodes[0] = Rows of the input layer nodes[1] = Width of the output map nodes[2] = Height of the output map

Parameters:

nodes - array of integers containing the nodes of each layer (see note above)

outputType - the type of output layer. One of 'WTA', 'GAUSSIAN'

Returns:

The neural network created

Throws:

java.lang.IllegalArgumentException

interrogate

public static double[] interrogate(NeuralNet nnet,
                                   double[] input)

Interrogate a neural network with an array of doubles and returns the output of the neural network.

Parameters:

nnet - The neural network to interrogate

input - The input pattern (must have the size = # of input nodes)

Returns:

An array of double having size = # of output nodes

train

public static double train(NeuralNet nnet,
                           double[][] input,
                           double[][] desired,
                           int epochs,
                           double stopRMSE,
                           int epochs_btw_reports,
                           java.lang.Object stdOut,
                           boolean async)

Trains a neural network using the input/desired pairs contained in 2D arrays of double. If Monitor.trainingPatterns = 0, all the input array's rows will be used for training.

Parameters:

nnet - The neural network to train

input - 2D array of double containing the training data. The # of columns must be equal to the # of input nodes

desired - 2D array of double containing the target data. The # of columns must be equal to the # of output nodes

epochs - Number of max training epochs

stopRMSE - The desired min error at which the training must stop. If zero, the training continues until the last epoch is reached.

epochs_btw_reports - Number of epochs between the notifications on the stdOut

stdOut - The object representing the output. It can be either a PrintStream or a NeuralNetListener instance. If null, no notifications will be made.

async - if true, the method returns after having stated the network, without waiting for the completition. In this case, the value returned is zero.

Returns:

The final training RMSE (or MSE)

train_unsupervised

public static void train_unsupervised(NeuralNet nnet,
                                      double[][] input,
                                      int epochs,
                                      int epochs_btw_reports,
                                      java.lang.Object stdOut,
                                      boolean async)

Trains a neural network in unsupervised mode (SOM and PCA networks) using the input contained in a 2D array of double.

Parameters:

nnet - The neural network to train

input - 2D array of double containing the training data. The # of columns must be equal to the # of input nodes

epochs - Number of max training epochs

epochs_btw_reports - Number of epochs between the notifications on the stdOut

stdOut - The object representing the output. It can be either the System.out or a NeuralNetListener instance.

async - if true, the method returns after having stated the network, without waiting for the completition. In this case, the value returned is zero.

train_on_stream

public static double train_on_stream(NeuralNet nnet,
                                     StreamInputSynapse input,
                                     StreamInputSynapse desired,
                                     int epochs,
                                     double stopRMSE,
                                     int epochs_btw_reports,
                                     java.lang.Object stdOut,
                                     boolean async)

Trains a neural network using StreamInputSynapses as the input/desired data sources. The Monitor.trainingPatterns must be set before to call this method.

Parameters:

nnet - The neural network to train

input - the StreamInputSynapse containing the training data. The advColumnSelector must be set according to the # of input nodes

desired - the StreamInputSynapse containing the target data. The advColumnSelector must be set according to the # of output nodes

epochs - Number of max training epochs

stopRMSE - The desired min error at which the training must stop. If zero, the training continues until the last epoch is reached.

epochs_btw_reports - Number of epochs between the notifications on the stdOut

stdOut - The object representing the output. It can be either a PrintStream or a NeuralNetListener instance. If null, no notifications will be made.

async - if true, the method returns after having stated the network, without waiting for the completition. In this case, the value returned is zero.

Returns:

The final training RMSE (or MSE)

train_complete

public static double train_complete(NeuralNet nnet,
                                    int epochs,
                                    double stopRMSE,
                                    int epochs_btw_reports,
                                    java.lang.Object stdOut,
                                    boolean async)

Trains a complete neural network, i.e. a network having all the parameters and the I/O components already set.

Parameters:

nnet - The neural network to train

epochs - Number of max training epochs

stopRMSE - The desired min error at which the training must stop. If zero, the training continues until the last epoch is reached.

epochs_btw_reports - Number of epochs between the notifications on the stdOut

stdOut - The object representing the output. It can be either a PrintStream or a NeuralNetListener instance. If null, no notifications will be made.

async - if true, the method returns after having stated the network, without waiting for the completition. In this case, the value returned is zero.

Returns:

The final training RMSE (or MSE)

test

public static double test(NeuralNet nnet,
                          double[][] input,
                          double[][] desired)

Tests a neural network using the input/desired pairs contained in 2D arrays of double. This method doesn't change the weights, but calculates only the RMSE. If Monitor.validationPatterns = 0, all the input array's rows will be used for testing.

Parameters:

nnet - The neural network to test

input - 2D array of double containing the test data. The # of columns must be equal to the # of input nodes

desired - 2D array of double containing the target data. The # of columns must be equal to the # of output nodes

Returns:

The test RMSE (or MSE)

test_on_stream

public static double test_on_stream(NeuralNet nnet,
                                    StreamInputSynapse input,
                                    StreamInputSynapse desired)

Tests a neural network using using StreamInputSynapses as the input/desired data sources. This method doesn't change the weights, but calculates only the RMSE. The Monitor.validationPatterns must be set before the call to this method.

Parameters:

nnet - The neural network to test

input - the StreamInputSynapse containing the test data. The advColumnSelector must be set according to the # of input nodes

desired - the StreamInputSynapse containing the target data. The advColumnSelector must be set according to the # of output nodes

Returns:

The test RMSE (or MSE)

compare

public static double[][] compare(NeuralNet nnet,
                                 double[][] input,
                                 double[][] desired)

Permits to compare the output and target data of a trained neural network using 2D array of double as the input/desired data sources. If Monitor.validationPatterns = 0, all the input array's rows will be used for testing.

Parameters:

nnet - The neural network to test

input - 2D array of double containing the test data. The # of columns must be equal to the # of input nodes

desired - 2D array of double containing the target data. The # of columns must be equal to the # of output nodes

Returns:

a 2D of double containing the output+desired data for each pattern.

compare_on_stream

public static double[][] compare_on_stream(NeuralNet nnet,
                                           StreamInputSynapse input,
                                           StreamInputSynapse desired)

Permits to compare the output and target data of a trained neural network using StreamInputSynapses as the input/desired data sources.

Parameters:

nnet - The neural network to train

input - the StreamInputSynapse containing the training data. The advColumnSelector must be set according to the # of input nodes

desired - the StreamInputSynapse containing the target data. The advColumnSelector must be set according to the # of output nodes

Returns:

a 2D of double containing the output+desired data for each pattern.

getDataFromStream

public static double[][] getDataFromStream(StreamInputSynapse dataSet,
                                           int firstRow,
                                           int lastRow,
                                           int firstCol,
                                           int lastCol)

Extracts a subset of data from the StreamInputSynapse passed as parameter.

Parameters:

dataSet - The input StreamInputSynapse. Must be buffered.

firstRow - The first row (relative to the internal buffer) to extract

lastRow - The last row (relative to the internal buffer) to extract

firstCol - The first column (relative to the internal buffer) to extract

lastCol - The last column (relative to the internal buffer) to extract

Returns:

A 2D array of double containing the extracted data

save

public static void save(NeuralNet nnet,
                        java.lang.String fileName)
                 throws java.io.FileNotFoundException,
                        java.io.IOException

Saves a neural network to a file

Parameters:

nnet - The network to save

fileName - the file name on which the network is saved

Throws:

java.io.FileNotFoundException - if the file name is invalid

java.io.IOException - when an IO error occurs

save

public static void save(NeuralNet nnet,
                        java.io.File fileName)
                 throws java.io.FileNotFoundException,
                        java.io.IOException

Saves a neural network to a file

Parameters:

nnet - The network to save

fileName - the file on which the network is saved

Throws:

java.io.FileNotFoundException - if the file name is invalid

java.io.IOException - when an IO error occurs

save_toStream

public static void save_toStream(NeuralNet nnet,
                                 java.io.OutputStream stream)
                          throws java.io.IOException

Saves a neural network to an OutputStream

Parameters:

nnet - The neural network to save

stream - The OutputStream on which the network is saved

Throws:

java.io.IOException - when an IO error occurs

load

public static NeuralNet load(java.lang.String fileName)
                      throws java.io.FileNotFoundException,
                             java.io.IOException,
                             java.lang.ClassNotFoundException

Loads a neural network from a file

Parameters:

fileName - the name of the file from which the network is loaded

Returns:

The loaded neural network

Throws:

java.io.IOException - when an IO error occurs

java.io.FileNotFoundException - if the file name is invalid

java.lang.ClassNotFoundException - if some neural network's object is not found in the classpath

load_fromStream

public static NeuralNet load_fromStream(java.io.InputStream stream)
                                 throws java.io.IOException,
                                        java.lang.ClassNotFoundException

Loads a neural network from an InputStream

Parameters:

stream - The InputStream from which the network is loaded

Returns:

The loaded neural network

Throws:

java.io.IOException - when an IO error occurs

java.lang.ClassNotFoundException - some neural network's object is not found in the classpath