|
API Documentation
Documetation and examples will be made for the API PHP version, so they can be tested online. Links: API Usage | Class Reference API Usage The first step for creating the neural network is, besides including the API (Syntax: require "nn.php";), creating the network's structure as a jagged-double-array of neuron class instances. The model does not include the input layer of the network, as this must be a simple array of values, but it DOES include the output layer as this must be an array of neurons. So, let's say we want to create a neural network which will have 3 input values and 3 layers; as for neurons on each layer let's say 5 on layer 1, 3 on layer 2 and 1 on the output layer. Here is a graphic representation of what we want to create:  In the PHP code this can be done like this: //Defining the Input Layer $inputLayer[0] = 0.1; $inputLayer[1] = 0.25; $inputLayer[2] = 0.9; //Defining the network model $net_model = array(); for($layer=0;$layer<3;$layer++){ $net_model[$layer] = array(); if($layer == 0){ for($neuron_no=0;$neuron_no<5;$neuron_no++) $net_model[$layer][$neuron_no] = new neuron(); } else if($layer == 1){ for($neuron_no=0;$neuron_no<3;$neuron_no++) $net_model[$layer][$neuron_no] = new neuron(); } else if($layer == 2){ for($neuron_no=0;$neuron_no<1;$neuron_no++) $net_model[$layer][$neuron_no] = new neuron(); } } Now we have the model of our neural network stored in the $net_model variable and the input layer in the $inputLayer variable, so we can initialize our network by doing something like this: $neuralNet = new nn($inputLayer,$net_model); At this point we have our neural network stored in the $neuralNet variable, with random-assigend values to the synaptic weights. We can display our entire neural network using the nnPrint() method: $neuralNet->nnPrint(); So far, so good, but now we want to train our network so we can actually use it. The fastest and easiest way is by loading synaptic weights values from a compatible file. Of course, this method implies the fact that we have such a file (could be from an earlier-training process or from our site's resources). So, assuming that we have the file we could load it by using the nnLoadWeights($filePath) method: $neuralNet->nnLoadWeights("path/to/file"); Most probably is that we won't have such a file at-hand, so we must train the network our-selfs. To do this, we will use the nnBackpropagation class (so far the API uses only backpropagation algorithm to train a network) but first we will need a training set that suits the problem we want to solve. A training set is mainly formed by a collection of input values and the desired output values for those inputs. This API uses a double-array data structure both for the input values and their corresponding outputs. For this tutorial we'll use some simple and few training data, but for real problems some big amounts of data should be used in order to achieve a good accuracy. So, let's assume that we want to teach our network a SUM function( f(x,y,z)=x+y+z ), than the training data definition for our neural network should look something like this: $tIn[0][0] = 0.1; $tIn[0][1] = 0.2; $tIn[0][2] = 0.15; $tOut[0][0] = 0.45; $tIn[1][0] = 0.3; $tIn[1][1] = 0.03; $tIn[1][2] = 0.1; $tOut[1][0] = 0.43; Now we have the training data stored in the variables $tIn and $tOut; it's needless to say that just 2 datas (as in our example) are insufficient for a neural network to be trained. Usually the training data is aquired from a database, transferred into PHP as a double-array. Ok, back to our tutorial, we assume that we have sufficient training data, so we will instanciate an object from nnBackpropagation class: $backprop = new nnBackpropagation($neuralNet,$tIn,$tOut); Good, now we can use the $backprop object to train the associated network (received as parameter), using the training data. We first customize the learning parameters and than we call the performLearning() method to train our network: $backprop->learningRate = 0.2; //Sets the learning rate $backprop->numberOfEpochs = 10000; //Sets the maximum number of epochs to be performed $backprop->timeout = 5; //Sets the time limit for the learning process $backprop->acceptError = 0.005; //Sets the error level for which the network should be considered trained $backprop->performLearning(); Learning can run smoothly and acheive the desired accuracy, but also can get stuck in local minimum throughout the error function graph and compromise the learning process; in this case you should restart the process, maybe change some parameters or apply other training techniques. Anyway, you can check out the learning statistics, and when you are satisfied with a result, you should save the weight values to a file: echo "<br>Time passed: ".$backprop->timePassed." secs"; echo "<br>Performed epochs: ".$backprop->performedEpochs; echo "<br>Error: ".$backprop->currentError; $neuralNet->nnSaveWeights("path/to/savefile"); This is the way this API works. Now we'll talk a little about the dataNormalization class. We use this class to normalize values. To be more specific, we use it to reduce the interval of values; let's say we want to work with integer values in the interval [-1000,1000]. We can't use the raw values in this interval because a neural network outputs values either in interval [0,1], or in [-1,1], depending on outputs layer's neuron's activation function (sigmoidal for [0,1] and hyperbolic tangent and linear for [-1,1]). That is why we must 'normalize' values. So having the input interval [-1000,1000] and output interval [0,1], the normalized version of number 0 would be 0.5, for -1000 is 0 and for 1000 is 1. The normalization class of this API has methods for normalizing one value or an entire array of values, and also their corresponding methods for de-normalization, or the "real" value of a normalized one. The usage of this class goes like this: $dn = new dataNormalization(-1000,1000,0,1); $normedVal = $dn->normalizeValue(0); //$normedVal will be 0.5 $realVal = $dn->realValue($normedVal); //$realVal is 0 To normalize/de-normalize arrays of values use methods normalizeValues($array_of_values) and realValues($array_of_normalized_values) Now that we know how to use the API there are still a few things to be said about the base class of this API, which is the neuron class. For each neuron instance there can be selected a series of parameters as described below (it is recommended that neurons on the same layer have the same parameters): -the gFactor for the activation function. Controls the tension of the activation function; default value is 1. Set value synatx: $neuron->gFactor = $newValue; Here is a graphic representation of what gFactor is actually doing:  -the tetaFactor for the activation function. Controls the displacement of the activation function; Default value is 0. Set value syntax: $neuron->tetaFactor = $newValue; Below, a graphic about the tetaFactor:  -the input function type; possible values: 0-Sum, 1-Product, 2-Minimum, 3-Maximum; Default value is 0. This parameter controls how the array of products input*weight of the neuron become a single value. Set value syntax: $neuron->inputFType = $newValue -the activation function type; possible values: 0-Hyperbolic Tangent, 1-Sigmoidal, 2-Linear; Default value is 0. This parameter controls the type of the neuron's activation function. Set value syntax: $neuron->activationFType = $newValue -the output function type; possible values: 0-Binary, !0-Real; Default value is 1 (!0). This parameter controls the output type of the neuron, real output or binary(1/0) output. Set value syntax: $neuron->outputFType = $newValue -the output border; this parameter is used only if the output function type is binary and it determines the binary value to output like this: if the result of the activation function is less than border then the output is 0, if the result is equal or greater than border then 1 is outputted ; Default value is 0. This value should be changed to 0.5 if the activation function is set to sigmoidal. Set value syntax: $neuron->outputBorder = $newValue Class Reference neuron Class -Properties: float[] $_i - Inputs array of floats; float[] $_w - Synaptic weights array of floats; float $gFactor = 1 - gFactor value for the activation function; float $tetaFactor = 0 - tetaFactor value for the activation function; int $inputFType = 0 - input function type (0=SUM, 1=PRODUCT, 2=MINIMUM, 3=MAXIMUM); int $activationFType = 0 - activation function type (0=HYP.TANGENT, 1=SIGMOID, 2=LINEAR); int $outputFType = 1 - output function type (0=BINARY, !0=REAL); int $outputBorder = 0 - border for output function if set to 0(binary); Ex.: out<border?0:1; -Methods: float inputFunction() - Returns output of neuron's input function; float activationFunction() - Returns output of neuron's activation function; float outputFunction() - Returns output of neuron's output function; -Constructor: neuron() - Instanciates an object of type neuron nn Class -Properties: float[] $inputLayer - Input Layer array of floats; neuron[][] $nn - neural net array of neuron instances; -Methods: void nnInit(neuron[][] $nnModel) - Initializez the neural network; void nnRefresh() - Refreshes the neural network (recalculates all values); float[] nnOutput() - Returns the output of the neural network as an array of floats; void nnPrint() - Prints the entire network structure in the browser window; void nnSaveWeights(string $filePath) - Saves weight values to file; void nnLoadWeights(string $filePath) - Loads weight values from file; -Constructor: nn(float[] $inputLayer,neuron[][] $nnModel=0) - Instanciates an object of type nn nnBackpropagation Class -Properties: nn $nn - Reference to a neural network instance; float[][] $trainingSet - train set double array of floats; float[][] $desiredOutput - desired output double array of floats; float $learningRate = 0.2 - learning rate; float $acceptError = 0.001 - accepted error; int $numberOfEpochs = 100 - maximum number of epochs to perform; int $timeout = 30 - timeout for learning in seconds; float $currentError=0 - current average error of the net; int $performedEpochs=0 - number of epochs performed so far; int $timePassed=0 - time passed so far in seconds; -Methods: void performEpoch() - performs an epoch; void performLearning() - trains the network according to the training set arrays; -Constructor: nnBackpropagation(nn $neural_net,float[][] $train,float[][] $desired_out) - Instanciates a class object dataNormalization Class -Properties: float $inputMin - The real number lower limit; float $inputMax - The real number upper limit; float $outMin - The normalized number lower limit; float $outMax - The normalized number upper limit; -Methods: float normalizeValue(float $v) - Returns the normalized version of $v; float realValue(float $v) - Returns the real value of the normalized value $v; float[] normalizeValues(float[] $vals) - Normalizez an array of values and returns the normalized array; float[] realValues(float[] $vals) - De-normalizez an array of normalized values and returns the array; -Constructor: dataNormalization(float $iMin,float $iMax,float $oMin=0,float $oMax=1) - Instanciates a class object |
|
||||||||