Projects

This chapter provides a brief description of how a project is organized. This will familiarize you with how to create a project and check its internal details.

Creating your first project!

In order to create a new project just click on the File > New Project menu. NuPIC Studio creates a minimal project, with only one region, which is naturally named "Top". If you try to simulate a neural network at this point, NuPIC Studio will emit an error simply because your neural network has no child element (i.e. a region or sensor) to feed it. So we need to add a feeder to "Top".

We will create a very simple network with only a single region and one sensor feeding it. Simply click on "Top" region with the right mouse-button. In the context menu provided, just click on Add new sensor here menu and give a name for it ("Numbers", for example).

Once done, click on Code tab and note that the source code of the network was automatically updated with the recent change:

Now save your new project. Click on File > Save Project menu and specify a name and location for it. You project will be saved to a file with a .nuproj extension.

So.. What is the next step? Well, we need to set the parameters for each one of the two nodes.

Setting a Region

To configure the region just click on it with right mouse-button, then click on the Properties menu in the context menu that is provided. Now you can set the architecture and also spatial and temporal parameters of this region. Any detailed discussion of the parameters for a region would make this tutorial too big, thus we strongly advise you to check the "tool tip" for each text field; i.e. that yellow rectangle that is shown when you move the mouse over a control. Additionally you can peruse some examples provided with NuPIC Studio and the NuPIC wiki to get a better idea of the best parameter values for your region.

Setting a Sensor

To configure the sensor follow the same steps that you did to set the region. First specify if the inputs will come from a single file or from a database. For our case, click on File option and on the Browse File button and then pick the file "counting.csv" located on NuPIC Studio projects folder.

Setting a sensor is not difficult, but requires some previous knowledge of how the inputs are organized in the datasource as well as how the encoders are integrated into a sensor to read these inputs and concatenate them as a single input.

The logic for understanding the role of a sensor is to remember that any input fed into an HTM region should be a fixed array composed of 0's and 1's. So as the datasource of a sensor has several fields with different properties, the sensor has to use encoders to handle these different field values and concatenate their outputs as a single input.

In a CSV file, fields should be separated by colons and their parameters should be specified in the first three lines:

Numbers,Description
float,string
T,T
0,Zero
3,Three
6,Six
9,Nine
10,Ten
20,Twenty
30,Thirty
40,Forty
50,Fifty
60,Sixty
70,Seventy
80,Eighty
90,Ninety

Note that there are 2 ways to handle predictions/inferences using encoders:

• Reconstruction: the sensor receives the array of predicted columns and returns the predicted original values by passing the array portion corresponding for each field to their encoders and getting their decoded values.
• Classification: the encoders return predictions based on bit history of the current field value.

This said, let's add a single encoding to the sensor. In an encoding you should specify where the sensor should to get a value (i.e. the datasource field) and what will be used to handle this value and return a valid binary array (i.e. the encoder) to be concatenaded with other encodings outputs of the same sensor. To add a new encoding just click on Add button.

First all, set the target datasource field by specifying its name and its datatype. For our case, set "Numbers" as name and "Decimal" as datatype.

Now let's set an appropriate encoder for handle decimal values: the "Scalar" encoder, which is provided together with NuPIC.

To specify this encoder you should fill these essential information:

• Module: the module which the encoder class is located: nupic.encoders.scalar
• Class: the encoder class to be handled by NuPIC Studio: ScalarEncoder
• Parameters: the list of parameters to be passed to the class constructor:

parameter    value
==========   =====
w            3
minval       0
maxval       99
n            60
forced       True

• Field Name: the field name which this encoder use to return its outpus: Numbers
• Field Datatype: the field datatype of the field returned by the encoder: Decimal

Note: The last two encoder elements seem redundant but are not. Although "Scalar" encoder get a decimal value and pass it to a HTM region "as is", some encoders such like "Date" encoder get the properties of a field value and not its value itself. So the record information differs from information passed to the network. For example, you can use a "Date" encoder to read dates from a record and pass their properties like time of day, if is is holiday or not, etc, instead of the dates themselves. You can check an example of this on "HotGym" project provided with NuPIC Studio.

You also can create your own encoders. An encoder class should basically contains the following functions:

• encode(self, rawData): This function should basically receive a natural value and return an array of 0's and 1's.
• decode(self, arrayData): This function should basically receive an array and return the original natural value. Not required by Classification method.

During the simulation, NuPIC Studio will import the specified class for call these two functions. First, it will pass the natural value that it received from the file or database that you specified (to encode(rawData) function), and then feed the parent region with the array returned by this function. Then after the region computes this and other inputs, NuPIC Studio will pass the output array (i.e. the prediction) returned by the region and pass it to decode(arrayData) function.

If we try manually code all these actions we would have something like this:

# Import the encoder class
from nupic.encoders.scalar imports ScalarEncoder

# Create an instance of the encoder class
scalarEncoder = ScalarEncoder(w=3, minval=0, maxval=99, n=60, forced=True)

    ...

    # Read a natural value from file, convert it to array,
    # and pass it as input to region
    currentValue = file.readLine()
    inputArray = scalarEncoder.encode(currentValue)
    region.setInput(inputArray)

    ...

    # Get the output array (i.e. prediction) from region 
    # and convert it to its original natural value
    outputArray = region.getOutput()
    predictedValue = scalarEncoder.decode(outputArray)

To visualize the current and the predicted natural values during the simulation just click on a sensor, click on Encodings tab, and select an encoding to see its details. You will see something like this:

Prev: Simulation