FANNy: Modern Node.JS Bindings for FANN (Fast Artificial Neural Network library)
Obligatory Brief Example
var fanny = ;// Create a neural network with 2 input nodes, 5 hidden nodes, and 1 output nodevar ann = fanny;// Boolean XOR function training datasetvar dataset = input: 0 0 output: 0 input: 0 1 output: 1 input: 1 0 output: 1 input: 1 1 output: 0 ;// Train until a MSE (mean squared error) of 0.025. Returns a Promise.ann ;
Supported Features
Nearly all features of FANN are supported, including different datatypes (float, double, fixed) and
training progress callbacks. Multi-epoch training operations are asynchronous and run in a separate
thread. run()
can be called either synchronously or asynchronously, as its speed can vary widely
depending on the network size.
Interfaces
FANNy's primary interface roughly mirrors FANN's C++ interface, but with a number of changes and tweaks to make it better fit Javascript paradigms. This is the interface described in the rest of this file.
FANNy also provides a lower-level interface more directly in-line with FANN's own C++ interface.
This can be accessed by including the native addon itself: require('fanny').getAddon('float')
.
Getting FANN
This module is currently built on FANN git as of Jan. 2017. However, the original author no longer seems to be maintaining the library, and several bugs in the current official version break some features of FANNy. A maintained version with the appropriate bugfixes is available here.
When you npm install fanny, it should automatically fetch and compile this version of FANN
in a sandbox. You will need standard build tools along with cmake
installed.
Creating a Neural Network
To create a new neural network, use the createANN()
function. It takes two parameters.
The first (required) parameter is an object containing configuration information for the
neural network. The second parameter is an object containing a set of options. See the
section on setting options for a list.
var config = type: 'standard' // 'standard' (default), 'sparse', or 'shortcut' layers: 2 10 3 1 // Sizes of layers in the neural network. Required. // connectionRate: 0.5, // Connection rate, for sparse networks datatype: 'float' // 'float' (default), 'double', or 'fixed', for libfloatfann, libdoublefann, libfixedfann, respectively activationFunctions: // override default activation functions for layers or individual neurons // Possible values: 'LINEAR', 'THRESHOLD', 'THRESHOLD_SYMMETRIC', 'SIGMOID', 'SIGMOID_STEPWISE', // 'SIGMOID_SYMMETRIC', 'SIGMOID_SYMMETRIC_STEPWISE', 'GAUSSIAN', 'GAUSSIAN_SYMMETRIC', // 'ELLIOT', 'ELLIOT_SYMMETRIC', 'LINEAR_PIECE', 'LINEAR_PIECE_SYMMETRIC', 'SIN_SYMMETRIC', // 'COS_SYMMETRIC', 'SIN', 'COS' hidden: 'LINEAR' // all hidden nodes output: 'THRESHOLD' // all output nodes '2': 'LINEAR' // nodes on layer 2 (indexed from 0) '1-2': 'LINEAR' // node 2 on layer 1 activationSteepnesses: // override default activation steepnesses for layers or individual neurons // keys are same as for activationFunctions hidden: 02 ;var options = ... ;var ann = fanny;
Loading and Saving a Neural Network
Neural networks are saved by default in floating points. FANN fixed point saving can be enabled by
passing boolean true
as a second argument to save()
.
fanny.loadANN()
will, by default, load neural networks using libfloatfann. A second argument can
be passed with the datatype ('float', 'double', or 'fixed') to change this.
ann;fanny;
Options
Many of FANN's getter and setter functions are instead exposed as options that can easily be set in batches.
ann;ann;ann;ann; // returns object
The full list of possible options and available values can be found in common-schema
format in
the file src/ann.js
.
Training Data
Training data is represented by a TrainingData
class. It's constructed, saved, and loaded like
an ANN
:
var trainingData = fanny;trainingData;fanny;
Note that training data must be instantiated with the same datatype as the ANN it's used with.
The functions fanny.loadTrainingData()
and fanny.createTrainingData()
both take an optional
second argument containing the datatype, if different from the default ('float').
The data
parameter can take several different formats of data:
var data1 = input: 02 07 ... output: 03 08 05 ... input: ... output: ... ...;fanny; var data2 = 02 07 ... 03 08 05 ... ... ... ...;fanny; var inputs = 02 07 ... ...;var outputs = 03 08 05 ... ...;fanny;
TrainingData
also has several other methods that can get and manipulate the data. These
are direct equivalents of their corresponding FANN functions. Here are the available functions:
shuffle()
merge()
getLength()
getNumInputs()
getNumOutputs()
getInputData()
getOutputData()
getOneInputData()
getOneOutputData()
getMinInput()
getMaxInput()
getMinOutput()
getMaxOutput()
scaleInput()
scaleOutput()
scale()
subset()
setData()
clone()
Training
Training a single datapair is easy and synchronous:
ann;
Training a single epoch with a training dataset returns a Promise:
ann;
To train for multiple epochs, you can pass a set of options to train()
as a
second argument. All options are optional, but it is highly recommended to set at least
desiredError
.
ann;
train()
can also be given a third argument, a callback function that is called periodically
during training (defined by progressInterval
).
var { console;};
The progress function can optionally return false
to cancel training (and immediately reject the promise).
Instead of passing a progress function as the third argument, the special value 'default' can be passed (as a string) to enable FANN's default behavior of printing status reports to stdout.
Running
The neural network can be run either synchronously or asynchronously:
var outputs = ann;ann;
Getting Current Information and Stats
The ANN
object has a property called info
containing current information about the network. Keys include:
numInput
numOutput
totalNeurons
totalConnections
decimalPoint
multiplier
networkType
connectionRate
numLayers
Each of these corresponds to a FANN getter.
User Data
The ANN
object has a property called userData
which is initialized to an empty object. You can store
any data you need to in there, and it will be saved and loaded with the neural network. The data is
stored as a JSON object in the FANN user_data_string
field.
Other ANN Functions
These functions correspond directly (insofar as translation to Javascript allows) to functions
on the FANN C++ neural_net
class.
randomizeWeights
initWeights
printConnections
getMSE
resetMSE
printParameters
getActivationFunction
setActivationFunction
setActivationFunctionLayer
setActivationFunctionHidden
setActivationFunctionOutput
getActivationSteepness
setActivationSteepness
setActivationSteepnessLayer
setActivationSteepnessHidden
setActivationSteepnessOutput
getLayerArray
getBiasArray
getConnectionArray
setWeightArray
setWeight
scaleTrainingData
descaleTrainingData
setInputScalingParams
setOutputScalingParams
setScalingParams
clearScalingParams
scaleInput
scaleOutput
descaleInput
descaleOutput
testOne
testData