marf.Classification.NeuralNetwork
Class NeuralNetwork

java.lang.Object
  marf.Storage.StorageManager
      marf.Classification.Classification
          marf.Classification.NeuralNetwork.NeuralNetwork

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, IClassification, IStorageManager

public class NeuralNetwork
extends Classification

Artificial Neural Network-based Classifier.

$Id: NeuralNetwork.java,v 1.61 2008/02/05 22:13:30 mokhov Exp $

Since:

0.0.1

Version:

$Revision: 1.61 $

Author:

Ian Clement, Serguei Mokhov

See Also:

Serialized Form

Nested Class Summary

private static class

NeuralNetwork.NeuralNetworkErrorHandler Error handler to report errors and warnings.

Field Summary

static int	DEFAULT_EPOCH_NUMBER Default number of epoch iterations of 64 if none supplied.
static double	DEFAULT_MIN_ERROR Default minimum training error of 0.1 if none supplied.
static int	DEFAULT_OUTPUT_NEURON_BITS How many binary Neurons in the output layer.
static double	DEFAULT_TRAINING_CONSTANT Default training constant of 1 if none supplied.
private int	iCurrenLayer Current layer's #.
private int	iCurrLayerBuf Number of the buffered layer.
private int	iNeuronType Neuron Type.
static java.lang.String	JAXP_SCHEMA_LANGUAGE JAXP 1.2 Schema.
static java.lang.String	JAXP_SCHEMA_SOURCE JAXP 1.2 Schema URL.
private Layer	oCurrentLayer Current layer.
private Neuron	oCurrNeuron Current Neuron.
private Layer	oInputs Input layer.
private java.util.ArrayList	oLayers Collection of layers.
private Layer	oOutputs Output layer.
static java.lang.String	OUTPUT_ENCODING All output will use this encoding.
private static long	serialVersionUID For serialization versioning.
static java.lang.String	W3C_XML_SCHEMA XML 2001 Schema.

Fields inherited from class marf.Classification.Classification

adFeatureVector, oFeatureExtraction, oResultSet, oTrainingSet

Fields inherited from class marf.Storage.StorageManager

bDumpOnNotFound, iCurrentDumpMode, oObjectToSerialize, strFilename

Fields inherited from interface marf.Classification.IClassification

MARF_INTERFACE_CODE_REVISION

Fields inherited from interface marf.Storage.IStorageManager

DUMP_BINARY, DUMP_CSV_TEXT, DUMP_GZIP_BINARY, DUMP_HTML, DUMP_SQL, DUMP_XML, MARF_INTERFACE_CODE_REVISION, STORAGE_FILE_EXTENSIONS

Constructor Summary

NeuralNetwork(IFeatureExtraction poFeatureExtraction)
NeuralNetwork Constructor.

Method Summary

void	backSynchronizeObject() Must to be overridden by the modules that use object serialization with the generic implementation of restore().
private void	buildNetwork(org.w3c.dom.Node poNode) Performs DOM tree traversal to build neural network structure.
boolean	classify(double[] padFeatureVector) Neural Network implementation of classification routine.
void	commit() Applies changes made to neurons on every net's layer.
private void	createLinks(org.w3c.dom.Node poNode) DOM tree traversal -- create input and output links.
void	dump() Dumps Neural Net to an XML or serialized file.
void	dumpXML() Overrides the default implementation of dumpXML().
void	dumpXML(java.lang.String pstrFilename) Dumps Neural Network as XML file.
void	eval() Evaluates the entire neural network.
void	generate() Generates the initial network at random with the default parameters.
void	generate(int piNumOfInputs, int[] paiHiddenLayers, int piNumOfOutputs) Generates a virgin net at random.
protected java.lang.String	getDefaultFilename() Generates typical filename for dump/restore.
static java.lang.String	getMARFSourceCodeRevision() Retrieves class' revision.
double[]	getOutputResults() Gets outputs of a neural network run.
Result	getResult() Retrieves the minimum-error classification result.
static void	indent(java.io.BufferedWriter poWriter, int piTabsNum) Indents the output according to the requested tabulation for pretty indentation.
void	initialize(java.lang.String pstrFilename, boolean pbValidateDTD) Parses XML and produces a neural network data structure.
private int	interpretAsBinary() Interprets net's binary output as an ID for the final classification result.
void	restore() Restores Neural Net from an XML or serialized file.
void	restoreXML() Overrides the default implementation of restoreXML().
private void	runNNet() Evaluates the entire neural network.
void	setInputs(double[] padInputs) Sets inputs.
boolean	train() Implements training of Neural Net.
boolean	train(double[] padFeatureVector) Implements training of Neural Net given the feature vector.
void	train(double[] padInput, int piExpectedLength, double pdTrainConst) Performs Actual training of the net.
private boolean	trainImplementation(double[] padFeatureVector) Implements training of Neural Net.

Methods inherited from class marf.Classification.Classification

classify, clone, getFeatureExtraction, getResultSet, getTrainingSetFilename, loadTrainingSet, setFeatureExtraction

Methods inherited from class marf.Storage.StorageManager

dumpBinary, dumpCSV, dumpGzipBinary, dumpHTML, dumpSQL, enableDumpOnNotFound, equals, getDefaultExtension, getDefaultExtension, getDumpMode, getFilename, getObjectToSerialize, hashCode, restoreBinary, restoreCSV, restoreGzipBinary, restoreHTML, restoreSQL, setDumpMode, setFilename, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_OUTPUT_NEURON_BITS

public static final int DEFAULT_OUTPUT_NEURON_BITS

How many binary Neurons in the output layer. Presumably int (our ID) is 4 bytes, hence 4 * 8 = 32 bits, and so many outputs.

Since:

0.2.0

See Also:

Constant Field Values

DEFAULT_TRAINING_CONSTANT

public static final double DEFAULT_TRAINING_CONSTANT

Default training constant of 1 if none supplied.

Since:

0.2.0

See Also:

Constant Field Values

DEFAULT_EPOCH_NUMBER

public static final int DEFAULT_EPOCH_NUMBER

Default number of epoch iterations of 64 if none supplied.

Since:

0.2.0

See Also:

Constant Field Values

DEFAULT_MIN_ERROR

public static final double DEFAULT_MIN_ERROR

Default minimum training error of 0.1 if none supplied.

Since:

0.2.0

See Also:

Constant Field Values

oLayers

private java.util.ArrayList oLayers

Collection of layers.

oCurrentLayer

private transient Layer oCurrentLayer

Current layer.

iCurrenLayer

private transient int iCurrenLayer

Current layer's #.

iCurrLayerBuf

private transient int iCurrLayerBuf

Number of the buffered layer.

oCurrNeuron

private transient Neuron oCurrNeuron

Current Neuron.

iNeuronType

private transient int iNeuronType

Neuron Type.

oInputs

private Layer oInputs

Input layer.

oOutputs

private Layer oOutputs

Output layer.

OUTPUT_ENCODING

public static final java.lang.String OUTPUT_ENCODING

All output will use this encoding.

See Also:

Constant Field Values

JAXP_SCHEMA_LANGUAGE

public static final java.lang.String JAXP_SCHEMA_LANGUAGE

JAXP 1.2 Schema.

See Also:

Constant Field Values

W3C_XML_SCHEMA

public static final java.lang.String W3C_XML_SCHEMA

XML 2001 Schema.

See Also:

Constant Field Values

JAXP_SCHEMA_SOURCE

public static final java.lang.String JAXP_SCHEMA_SOURCE

JAXP 1.2 Schema URL.

See Also:

Constant Field Values

serialVersionUID

private static final long serialVersionUID

For serialization versioning. When adding new members or make other structural changes regenerate this number with the serialver tool that comes with JDK.

Since:

0.3.0.4

See Also:

Constant Field Values

Constructor Detail

NeuralNetwork

public NeuralNetwork(IFeatureExtraction poFeatureExtraction)

NeuralNetwork Constructor.

Parameters:

poFeatureExtraction - FeatureExtraction module reference

Method Detail

train

public final boolean train()
                    throws ClassificationException

Implements training of Neural Net.

Specified by:

train in interface IClassification

Overrides:

train in class Classification

Returns:

true if training was successful

Throws:

ClassificationException - if there are any errors

java.lang.NullPointerException - if module parameters are incorrectly set

See Also:

TrainingSet

train

public final boolean train(double[] padFeatureVector)
                    throws ClassificationException

Implements training of Neural Net given the feature vector.

Specified by:

train in interface IClassification

Overrides:

train in class Classification

Parameters:

padFeatureVector - the feature vector to train on

Returns:

true if training was successful

Throws:

ClassificationException - if there are any errors

java.lang.NullPointerException - if module parameters are incorrectly set

Since:

0.3.0.6

See Also:

TrainingSet

trainImplementation

private final boolean trainImplementation(double[] padFeatureVector)
                                   throws ClassificationException

Implements training of Neural Net.

Parameters:

padFeatureVector - the feature vector to train on; if null pipelining mode is used

Returns:

true if training was successful

Throws:

ClassificationException - if there are any errors

java.lang.NullPointerException - if module parameters are incorrectly set

Since:

0.3.0.6

classify

public final boolean classify(double[] padFeatureVector)
                       throws ClassificationException

Neural Network implementation of classification routine. In 0.3.0.6 the generic pipelined version of this API classify() was refactored into the Classification.

Parameters:

padFeatureVector - vector of features to compare with the stored ones

Returns:

true upon successful classification

Throws:

ClassificationException - when input feature vector length does not match the size of the input neuron layer or if there was a StorageException during dump/restore.

Since:

0.3.0.6

eval

public final void eval()

Evaluates the entire neural network.

Since:

0.3.0.5

runNNet

private final void runNNet()

Evaluates the entire neural network.

initialize

public final void initialize(java.lang.String pstrFilename,
                             boolean pbValidateDTD)
                      throws StorageException

Parses XML and produces a neural network data structure.

Parameters:

pstrFilename - net's XML filename

pbValidateDTD - if true DTD will be validated

Throws:

StorageException - if there was an I/O or otherwise error during initialization of the net

generate

public void generate()
              throws ClassificationException

Generates the initial network at random with the default parameters. The defaults include the number of input neurons is the same as number of features f, the number of output layer neurons is the same as the number of bits in an integer n, and one middle (hidden) layer that has h = |f - n| / 2. If f = n, then h = f / 2.

Throws:

ClassificationException

Since:

0.3.0.6

See Also:

DEFAULT_OUTPUT_NEURON_BITS

buildNetwork

private final void buildNetwork(org.w3c.dom.Node poNode)

Performs DOM tree traversal to build neural network structure.

Parameters:

poNode - current root Node

createLinks

private final void createLinks(org.w3c.dom.Node poNode)
                        throws ClassificationException

DOM tree traversal -- create input and output links.

Parameters:

poNode - Node to create links to and from

Throws:

ClassificationException - if net's configuration is out order

setInputs

public final void setInputs(double[] padInputs)
                     throws ClassificationException

Sets inputs.

Parameters:

padInputs - double array of input features

Throws:

ClassificationException - if the input array's length isn't equal to the size of the input layer

getOutputResults

public double[] getOutputResults()

Gets outputs of a neural network run.

Returns:

array of doubles read off the output layer's neurons

indent

public static final void indent(java.io.BufferedWriter poWriter,
                                int piTabsNum)
                         throws java.io.IOException

Indents the output according to the requested tabulation for pretty indentation. TODO: move elsewhere to some utility module.

Parameters:

poWriter - Writer object to write tabs to.

piTabsNum - number of tabs

Throws:

java.io.IOException - if there is an error writing out the tabs

dumpXML

public final void dumpXML(java.lang.String pstrFilename)
                   throws StorageException

Dumps Neural Network as XML file.

Parameters:

pstrFilename - XML file name to write to

Throws:

StorageException - in case of an I/O error

generate

public final void generate(int piNumOfInputs,
                           int[] paiHiddenLayers,
                           int piNumOfOutputs)
                    throws ClassificationException

Generates a virgin net at random.

Parameters:

piNumOfInputs - number of input Neurons in the input layer

paiHiddenLayers - arrays of numbers of Neurons in the hidden layers

piNumOfOutputs - number of output Neurons in the output layer

Throws:

ClassificationException - if the hidden layers array has nothing or is null

Since:

0.2.0, Serguei

train

public final void train(double[] padInput,
                        int piExpectedLength,
                        double pdTrainConst)
                 throws ClassificationException

Performs Actual training of the net.

Parameters:

padInput - the input feature vector

piExpectedLength - expected length of the output layer

pdTrainConst - training constant to use for neurons

Throws:

ClassificationException - if the training constant less than zero or sizes of the inputs do not match or there is a problem evaluating the network

commit

public final void commit()

Applies changes made to neurons on every net's layer.

interpretAsBinary

private final int interpretAsBinary()

Interprets net's binary output as an ID for the final classification result.

Returns:

ID, integer

dump

public void dump()
          throws StorageException

Dumps Neural Net to an XML or serialized file.

Specified by:

dump in interface IStorageManager

Overrides:

dump in class Classification

Throws:

StorageException

See Also:

IStorageManager.DUMP_GZIP_BINARY, IStorageManager.DUMP_BINARY, StorageManager.dumpGzipBinary(), StorageManager.dumpCSV(), StorageManager.dumpBinary(), StorageManager.dumpXML(), StorageManager.dumpHTML(), StorageManager.dumpSQL(), StorageManager.backSynchronizeObject(), StorageManager.iCurrentDumpMode

restore

public void restore()
             throws StorageException

Restores Neural Net from an XML or serialized file.

Specified by:

restore in interface IStorageManager

Overrides:

restore in class Classification

Throws:

StorageException

See Also:

IStorageManager.DUMP_GZIP_BINARY, IStorageManager.DUMP_BINARY, StorageManager.dumpGzipBinary(), StorageManager.dumpCSV(), StorageManager.dumpBinary(), StorageManager.dumpXML(), StorageManager.dumpHTML(), StorageManager.dumpSQL(), StorageManager.backSynchronizeObject(), StorageManager.iCurrentDumpMode

dumpXML

public void dumpXML()
             throws StorageException

Overrides the default implementation of dumpXML(). Merely calls dumpXML(String).

Specified by:

dumpXML in interface IStorageManager

Overrides:

dumpXML in class StorageManager

Throws:

StorageException - in case of I/O or otherwise error

Since:

0.3.0.6

See Also:

IStorageManager.dumpXML(), dumpXML(String)

restoreXML

public void restoreXML()
                throws StorageException

Overrides the default implementation of restoreXML(). Merely calls initialize().

Specified by:

restoreXML in interface IStorageManager

Overrides:

restoreXML in class StorageManager

Throws:

StorageException - in case of I/O or otherwise error

Since:

0.3.0.6

See Also:

IStorageManager.restoreXML(), initialize(String, boolean)

backSynchronizeObject

public void backSynchronizeObject()

Description copied from class: StorageManager

Must to be overridden by the modules that use object serialization with the generic implementation of restore(). By default this method is unimplemented.

Overrides:

backSynchronizeObject in class StorageManager

Since:

0.3.0.6

See Also:

StorageManager.backSynchronizeObject()

getDefaultFilename

protected java.lang.String getDefaultFilename()

Generates typical filename for dump/restore.

Returns:

canonical filename for dump/restore based on the current dump mode.

Since:

0.3.0.6

getResult

public Result getResult()

Retrieves the minimum-error classification result.

Returns:

Result object

Since:

0.3.0.2

getMARFSourceCodeRevision

public static java.lang.String getMARFSourceCodeRevision()

Retrieves class' revision.

Returns:

revision string

Since:

0.3.0.2