Tutorial1
From NeuroJetWiki
Contents |
Levy Lab Tutorial #1
By Matt Archer and Sean Polyn
Revised by Dave Sullivan (April 2003), Aprotim Sanyal (August – October 2004), Andrew Howe (August 2005)
Wikified: August 2005
1.Purpose of this Tutorial
This tutorial is intended to familiarize users with NeuroJet scripting language and the format of a NeuroJet script file. Additionally, this tutorial demonstrates how to execute NeuroJet, run a training and testing paradigm, save data to a file and gives an example of how to analyze this data in MATLAB®.
2.Necessary Knowledge
Some familiarity and comfort with the UNIX/LINUX environment is recommended. Familiarity with MATLAB® is also recommended but not at all necessary.
3.Getting Started
The program we use to execute our networks is called NeuroJet. NeuroJet will take script files from pico or any text editor and execute the commands within. To execute a network, simply type
NeuroJet [filename]
at the Unix prompt.
NeuroJet’s scripting language includes many built-in functions that set parameters, run the neural network, and analyze data. NeuroJet has an extensive built-in help system that illustrates the purpose and use of these functions. To access help files, type
NeuroJet -help
The two major function types are @ and ^. The @ function type runs a procedure without returning a value (similar to the void function type in C/C++). The ^ function type will return a value (similar to the float or int function type in C/C++). Typing NeuroJet -help will return a list of all functions. As far as writing the code for your program, executable functions in the program should begin with the function type followed by the function name and any parameters in parentheses.
EXAMPLE:
@CreateVar(NumberOfTrials 100)
4.Writing and running a basic script for sequence learning
The structure of a basic script is fairly straightforward. We will first set parameters for our network and then train and test it to see to what degree it has learned the sequence. For the tutorial lab, we will be training the network on a simple pattern. A pattern is just a group of neurons which fire together during a single time step. A series of patterns occurring over several time steps is called a sequence. If we have the same pattern fire several times in a row, we are stuttering that pattern.
Create a text file called simple_sequence.nj using pico or your editor of choice so that we can begin to write the code.
Setting the parameters: We use the function @SetVar to define the parameters for the network. There are 13 parameters for this simple network which are explained in the code below. Enter this code into your script file:
@SetVar( title testnet1 ni 1024 Activity 0.1 Con 0.1 mu 0.05 theta 0.5 ResetAct 0.1 seed 1001 KFB 0.048 KFF 0.048 K0 0 wStart 0.4 )
Here is what the parameters mean:
title - This is the name of this execution. It is useful if you are saving the output of the network to a file and want to be able to distinguish which file came from which network.
ni - The number of neurons in the network.
Activity - This is the desired activity level (fraction of neurons active per time step) of the network. When we run a "free-running" network, the activity level of the network is actually determined by the inhibition constants (or, in LevyLab jargon, K values) below, and Activity has no effect on the network. When we run a competitive network, Activity sets the exact level of activity. In this script, we will be using a "free-running" network.
Con - This is the connectivity setting of our network. The connectivity structure of our network is random, and connections between neurons are one-way. Con sets the probability that a connection exists from any neuron in the network to any other neuron in the network. We typically use values for Con that are at or under 0.1 (indicating 10% connectivity), thus our network is sparsely connected.
mu – This is the synaptic modification rate constant. This rate constant is also referred to as epsilon in some older LevyLab publications. Although the term "learning rate" is also sometimes used within the lab, that term should be avoided as it is imprecise.
theta - The threshold for firing. Each neuron receives activation from the firing neurons that are connected to it, when this activation exceeds a threshold (theta), the neuron will fire.
ResetAct - This controls the random pattern of activation that is presented to the network on time-step zero. The number refers to the percent of neurons that will be turned on.
seed - This is the number that is used to seed NeuroJet’s random number generator. Thus, for every seed, there is a different configuration of the connections between neurons. In many experiments, we run networks with many different seeds to ensure that our results are not dependent on any specific connectivity configuration. The seed is a 32-bit 'int' type and therefore cannot exceed 2147483647. NeuroJet checks the seed value to safeguard against such an error.
KFB, KFF, K0 - The three inhibitory terms in the excitation equation. These terms control activity fluctuations. We sometimes use a Mathematica script (Anne's program) to set them.
wStart - This is the value that all of the weights (the synaptic connections) are set to before the network starts to run.
Those are all of the parameters you'll need right now. The next few lines of your script file should be as follows:
@PrintVar(title seed ni mu Activity theta wStart KFB KFF K0) @MakeSequence(-name seq1 -len 10 -non 32 -ol 24) @CreateNetwork()
Going through this step by step...
@PrintVar() is a function that prints to screen (or file) all the values of the variables that you list as its arguments.
@MakeSequence() creates a set of patterns that can be presented to the network during training. The arguments work as follows: -name is the name of the sequence you create, so you can refer to it later. -len is the length of the sequence, how many patterns it will consist of. -non is the number of neurons which will be on in each pattern. -ol refers to the amount of overlap between successive patterns. Here, each pattern will have 24 neurons in common with the previous pattern. This is also known as shift rate.
@CreateNetwork() instructs NeuroJet to set up the connections between the neurons.
Now that we have all of that out of the way, we can get to making the network learn something. More code:
@Train(-name seq1 -trials 500 -nocomp) @Test(-time 10 -name seq1 -Pstart 1 -Pend 10 -nocomp) @CopyData(-from TestingBuffer -to TestSeq1)
@Train() runs the network over and over on a sequence, with synaptic modification turned on, so the weights between the neurons change and the network learns. -name refers to the sequence that the network will be trained on, in this case, it is seq1, which we just created above. -trials is how many times we are going to present this sequence to the network. -nocomp means that the network is non-competitive, that is, activity will fluctuate.
@Test() tests the network after we have trained it. It turns off synaptic modification, and presents the sequence again. We are interested in saving the firing patterns that the network produces. Here, -time refers to the number of time-steps we want to run the sequence for. Since ours is 10 time-steps long, 10 seems like a reasonable number to enter. -Pstart and -Pend are the starting and ending patterns for the sequence, in case you didn't want to present the whole thing. The other flags work the same way as in Train.
@CopyData() copies data from one data structure to another. TestingBuffer is a matrix with all of the activity of all of the elements of the network represented as 1's and 0's across time. Whenever @Test() is called, the resulting firing matrix is put into TestingBuffer. Similarly, whenever @Train() is called, the resulting firing matrix is put into TrainingBuffer.
Okay, more code:
@Test(-time 20 -name seq1 -Pstart 1 -Pend 3 -nocomp) @Sim(-x TestingBuffer -y TestSeq1) @SaveData(-from SimBuffer -to Sim.dat) @SaveData(-from TestingBuffer -to PartialInput.fire) @SaveData(-from TestSeq1 -to FullInput.fire)
We want to test again, but this time we want to only present the first three patterns of the learned sequence. Then we want to see what network states evolve over time, and compare them to the driven condition, the first call to Test, where we presented the sequence in its entirety.
@Sim() uses a cosine comparison to see how similar the firing patterns are for two sets of numbers. -x and -y specify which firing patterns are going to be used on which axis of the graph. Calling @Sim puts the resulting similarity matrix into SimBuffer.
@SaveData() saves a data structure into a file so we can analyze it at our leisure or on a different machine. Here, we use @SaveData to save the results of our similarity comparison to a file called Sim.dat, and also to save the firing diagrams from both of the test trials.
5.Using NeuroJet to run the simulation
To run your simple_sequence.nj file, type the following command into your favorite shell:
NeuroJet simple_sequence.nj
If you want to determine how long it takes to run the script you can also use:
time NeuroJet simple_sequence.nj
If you're running on someone else's computer you should use this form of the command:
nohup nice NeuroJet simple_sequence.nj &
nohup means don't end this program if I close the shell. nice means to give precedence to other processes when the cpu load is high. & means to put the process in the background. In this example, the output of NeuroJet will be sent to nohup.out.
6.Using MATLAB® to look at the similarity data
At the linux prompt, type
matlab &
to start a MATLAB® session. Wait a few seconds for MATLAB® to load. Now, we want to look at the similarity matrix to see whether the network learned the sequence.
First, load Sim.dat into MATLAB® by typing:
load Sim.dat;
Now, we want to examine the matrix. Type the following line into MATLAB®:
figure; pcolor(Sim);colorbar;
This brings up a 2-D view of the similarity matrix, with the values plotted with colors.
The diagram you just plotted shows how similar firing was during the fully-driven test trial to firing during the test trial where only partial input was given. If sequence completion is successful, firing during the latter time steps of the partially driven trial should be similar to firing during the same time steps of the fully-driven trial.
Each square of the diagram represents the normalized dot product of the two respective firing vectors. The x-axis of the matrix refers to the time step during the test trial in which we only gave the first 3 patterns (partially driven); the y axis refers to the time step during the test trial in which we gave the entire input sequence (fully driven). The colorbar on the right-hand side of the diagram shows the correspondence between color and similarity value.
What do you see? If the test was successful, there should be a diagonal line going across the plot.
Now, we will take a look at the actual neural firing during the two test trials. Type the following commands in MATLAB®:
PartialInput=full(spconvert(load('PartialInput.fire')));
FullInput=full(spconvert(load('FullInput.fire')));
figure;spy(PartialInput(:,1:120)');
figure;spy(FullInput(:,1:120)');
In the two figures you just plotted, each column represents a single time step, and each row represents a single neuron. If the neuron i fired on time step t, a dot appears on the diagram in row i and column t.
Importantly, because our neurons are randomly connected, the row assigned to any one neuron is mostly meaningless. That is, the spatial juxtaposition of any two neurons in these firing diagrams does not convey any information about one neuron’s influence on another. There is one key exception to this – neurons that fire as part of an input sequence are grouped together. Thus, the input sequence appears as a diagonal stripe in the diagram of the fully driven trial (Figure 3 on your screen). In the partially driven trial, the network attempts to reproduce the sequential firing of the input sequence. Did it work? How do you know?
Now, you know the basics of sequence learning using NeuroJet. If you have any questions, ask whoever is around...
On to Tutorial2
