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 encoders are integrated into a sensor as well as how the inputs are organized in the datasource.

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. This said, a sensor has several kinds of data that it can receive and re-send to a region:

• BinaryArray: a fixed array of 0's and 1's ready to be fed into a region. The sensor receives this array and re-sends it without any handling. This operation is performed by an "encoder" called PassThroughEncoder which despite the name is not a real encoder.
• Boolean, Integer, Decimal, Date, and String: natural values that need to be converted into an array of 0's and 1's. This conversion is performed by appropriate encoders.

In a CSV file, fields containing the kinds of data above 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 using encoders:

• Reconstruction: the encoders receives the array of predicted columns and returns the original value represented by such array.
• Classification: the encoders return predictions based on bit history of the current input.

This said, let's add a single encoding to the sensor. An encoding is simply a component that aims to get the current value from a specific datasource field, encode it using an appropriate encoder, and pass the encoded value (i.e. the binary array) to a HTM region in order to it is able to return predictions for this or other datasource fields from same database. To add a new encoding just click on Add button.

Bear in mind that each encoding is composed by the datasource field details (name, data type, etc) and the encoding details (encoder, encoded data type, etc).

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 components:

• Module: the python 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 components 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.

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 to see its details. You will see something like this:

Prev: Simulation