RatLab provides the functionality to set up and perform simulations of place cell experiments. It is based on Slow Feature Analysis (SFA), an unsupervised learning algorithm able to extract place field information solely from the visual stream of a simulated rodent [1, 2]. For more information about the architecture and/or in case you wish to cite RatLab in an article, please refer to this paper.
RatLab is written in Python and uses several additional libraries. The following needs to be installed in order to run RatLab:
RatLab includes an additional patch for MDP that uses Nvidia CUDA to speedup the SFA training phase (the model at the core of RatLab). To make use of this confirm CUDA is installed and running on your machine and follow the instructions found in the 'RatLab CUDA integration' .zip file.
RatLab is primarily used from within a terminal. However, to get started an optional GUI can be used to set up basic experiments. Open the RatLab base folder in a terminal and run the GUI with
$ python RatLabGUI.py
This should open the RatLab GUI:
To decide on a shape of the environment for your experiment, use the row of buttons in the top left corner. Available options are a simple rectangular box, multiple arm maze, T-maze, circular, or custom arenas (file icon). Each selection presents you with a different set of parameters for the experiment; simply click on them to specify their values. Parameters on the right need to be set, while parameters on the left are optional at this stage. Once you are satsified with the parameters, click the SCRIPT button in the upper right corner. This will generate a file called RatLabScript that contains the commands to run your chosen experiment. It is a simple batch file that can be called via:
$ ./RatLabScript
Calling this script will execute a full simulation from the ground up: it will generate a sequence of images, collect them in a single data file, train a hierarchical SFA network, and sample the trained network over the specified arena. (Note that this might take some time.)
The GUI is a good way to test out simple scripts. You can open the generated batch file in an editor to take a look at the commands the script executes and already get a good idea about how more advanced experiments can be run. You may also call any of the main RatLab modules with a help argument, which will print some general usage information of the module, as well as a description of all the available command line arguments. The help usually also includes some examples of how the arguments should be used.
The main modules of RatLab are:
ratlab.py, convert.py, train.py, sample.py
Each of these correspond to one step of a full simulation and are called by a batch file generated by the RatLab GUI. All except convert.py can be modified by command line arguments in order to allow you to perform an experiment of your own design. Let's walk through all the steps of a more complicated setup in the following.
In this experiment we use an artificial rodent that is trained to explore all five arms of a multiple arm maze in a specific order and try to simulate its place cell activity. The first step of an experiment usually consists of generating the image sequence to train our model. In order to do this we need to define the desired environment otherwise there is nothing for the rat to see. Creation of image sequences is the job of the ratlab.py module, so this is what we need to call first. To set up a radial arm maze, we use the RatLab template star_maze. You can check out the required arguments for this type of maze, as well as the other available templates by calling:
$ python ratlab.py help
Here we learn that a radial arm maze requires several parameters that define the number of arms (five in our case), the width of each individual arm (let's say 12), the length of an arm (30), and finally the uniform height of all walls of the enclosure (8). We can use this to take a look at our setup immediately by calling:
$ python ratlab.py star_maze 5 12 30 8
Which displays something like this:
The simulation view of RatLab depicts a layout sketch of the environment as well as the current position of the rat (red arrow) and the rat's trajectory so far (white dots). Below you can see the visual field of the rat, spanning 320 degrees.
Right now the rat behaves very frantic. This if fine and even desired in an open field setting, but not in our case where we want the rat to follow a distinct path. In order to set up such a path you need to provide a set of coordinates that will serve as navigation points for the rat. Since we know the exact layout of our world, we can compute the points that we are looking for. In case of circular setups like this, you may want to enter the /tools subfolder which contains a handful of useful shortcuts. There you will find a file called radial_points.py which you can open in an editor. At the top of the script you will find two lines to enter a number of arms and a radius (you can use the length of one of the arms here). If you execute the Python script with our parameters you get the following output:
0.0 0.0
-0.00 -35.00
0.0 0.0
33.29 -10.82
0.0 0.0
20.57 28.32
0.0 0.0
-20.57 28.32
0.0 0.0
-33.29 -10.82
0.0 0.0
This data corresponds to the coordinates of the corners of the arms of our star maze. Every second coordinate is (0.0, 0.0) since we want the rat to return to the center before exploring another arm of the maze. You can copy this data into a file and save it .. where? This is important:
All data of an experiment is stored in the /current_experiment folder!
This folder was automatically generated when ratlab.py was called the first time. So far it does not include a lot, but it will always store everything connected to our experiment. Right now you can have a look at the exp_setup file which contains all parameters of the current experimental setup. In this folder we save the above coordinates in a file we name test_path.txt. Now all that remains is to tell RatLab to use this file via the path argument:
$ python ratlab.py star_maze 5 12 30 8 path path.txt
Now the rate explores each of the arms in succession:
Now that the experiment is set up, the actual simulation can be run. Let us run the simulation for 8000 time steps and record all frames along the way - this will be the training data. Since our setup is already established all that is needed are the arguments needed for recording:
$ python ratlab.py star_maze 5 12 30 8 path path.txt record limit 8000 color
This starts up RatLab, creates the world, and moves the rat just as before. The difference is that now the overview of the experiment is not shown any more in order to render a little bit more faster (you can switch it on and off via the F1 key if you want to make sure the correct experiment is running). RatLab now also displays a green progress bar to let you know the state of the simulation:
Once the data is generated you can look at the individual frames in the /current_experiment/sequence folder. You may also take a look at the automatically generated exp_finish.png image file which depicts the final state of the simulation and helps to judge the coverage of the rat's trajectory of the available area. Next, all image data will be collected in a single file:
$ python convert.py
Now we train our model. RatLab contains a hierarchical Slow Feature Analysis network that can be trained with the visual data that was just generated and converted:
$ python train.py ICA
An ICA argument is added to attach a final independent component analysis step to the network. We need this in order to generate place field plots later [1, 2], but you do not have to use it and can also look at the raw SFA output if you are interested. Once training is complete the trained SFA network can be found in the /current_experiment folder as a .tsn file.
In order to check for a successful training phase a trained network needs to be sampled. This can be done as follows:
$ python sample.py - 1 32 all
The RatLab sampler places the rat/camera at every (integer) position of the environment, renders the view of the rat at this position, and feeds it into the network which responds with a range of signals. These signals correspond to the cells measured during the experiment and in their response patterns we hope to see the place field activity. The first argument of the sampler tell the script to use the first available .tsn file it can find (instead of "-" you can also use a file name here in order to use a specific .tsn file). The second argument leads to the sampler placing the camera at every integer position (a value of 2 would sample the world at every second integer position and so on). The 32 specifies to sample all 32 signals provided by the SFA network (you will probably never use a different value here). The final argument is a shortcut: while sampling the environment, the camera is always pointed at the same direction (north by default). To sample different directions (as well as plotting the average over all sampled directions) a list of directions can be supplied. Using all tells the sampler to use the eight cardinal directions: N, S, E, W, NE, SE, SW, NW. By sampling in different directions and looking at the average, place fields can be checked for directional invariance.
The result of this experiment as provided by sample.py should look something like this:
And we can clearly see different signals be active (red) when the virtual rat is located within different arms of the maze.