*******************************************************************************
Sample codes of the multiple timescale recurrent neural network (MTRNN) 
(Last updated on Sep 27, 2011)
*******************************************************************************
The codes were developed based on the following paper.
[1] Yamashita Y, Tani J (2008) Emergence of Functional Hierarchy in a Multiple Timescale Neural Network Model: A Humanoid Robot Experiment. PLoS Comput Biol 4(11): e1000220. doi:10.1371/journal.pcbi.1000220
http://www.ploscompbiol.org/article/info%3Adoi%2F10.1371%2Fjournal.pcbi.1000220


*******************************************************************************
Important Notes
*******************************************************************************
1. You can train and test the MTRNN using an attached sample training data. However, if you want to train a network by using your original data, you have to develop another codes to train a Kohonen map/self-organizing map which is used for sparse encoding of MTRNN inputs (see [1] for details).

2. In this sample code, "EGGX/ProCALL", an X11 graphics library, is used for plotting data. Please install EGGX/ProCALL at the following link.
http://www.ir.isas.jaxa.jp/~cyamauch/eggx_procall/
However, since plotting processes can be easily separated from the codes, you can easily develop your own environment for plotting.


*******************************************************************************
How to Compile
*******************************************************************************
1. WITH plotting (default)
After installing EGGX/ProCALL, please adjust the passes for each file to be included during compilation (described in "Makefile_with_plot" file) based on your environment. See also instructions for EGGX/ProCALL installation.

Then, use Makefile_with_plot as Makefile.
#cp Makefile_with_plot Makefile
#make

2. WITHOUT plotting
Please comment out the definition for plotting as follows.
At the top of "main.c" file
#define PLOT_REALTIME =>
//#difine PLOT_REALTIME (comment out)

Then use Makefile_NO_plot when you compile.
#cp Makefile_NO_plot Makefile
#make

3. Run the program
When you run the program (a generated executive file "MTRNN_Sim"), you will be asked as follows,
#Parameter file directory? tmp0, 1, 2, 3, 4,,,=>
Please input a number which you put the files for training (see below "Training" section). Next, the program will ask,
#Save results directory? =>
Then, input name of a directory you select. Finally, input a command to train, test or generate an initial states file, according to the instruction of the program.


*******************************************************************************
Training
*******************************************************************************
The following files are necessary for training, and should be located in the directory "tmpX" (you can make any "tmpX" directories for several different training data and parameters).
1. train.ft: parameters
Explanations of each parameter are described in train.ft file.
2. tmp.train.pat: training sequences
The first column corresponds to time step, next several columns correspond each dimension of data. For example, in the sample training data, first 8 dimensions correspond to arm joint angles and the remaining 2 dimensions correspond to X and Y axes of vision. One training sequence should be separated by minus number (e.g. "-1"). Dimensions of the training data should match with the values of "inKN" in train.ft and "DataDim_ARM" and "DataDim_VISION" in Kohonen.h.
3. L.G.intA: initial states
When you train a network with your original data for the first time, you have to generate L.G.initA file by using the "g" command in the program. You also have to edit the function "Generate_InitFile( )" in RNN.c according to your design of experiments.
If you want initial states values to be self-organized, please activate "#define INITIALSTATE_SELFORGANIZATION" in "main.c" (commented out as default).
4. tmp.koh.wt: Kohonen map weights
In the sample data, a number in the first line (numbers of rows) corresponds to the size of Kohonen map of the arm joint angle data. Values of 8 columns correspond to weights values of 8 dimensional arm joint angles. Following weights values for arm, weights values for vision are described using the same format.


*******************************************************************************
Test
*******************************************************************************
When you test the trained network, the following files are necessary. All files should be located in the same directory (tmpX).
1. train.ft: parameters (used for training)
2. tmp.train.pat: training sequences (used for training)
3. L.G.intA: initial states (used in training or self-organized through training)
4. tmp.koh.wt: Kohonen map weights (used for training)
5. tmpL.wtA (MTRNN weights file self-organized through training)


*******************************************************************************
List of files
*******************************************************************************
MTRNN_Sample
MTRNN_Sample/main.c: main
MTRNN_Sample/RNN.h: header for RNN.c
MTRNN_Sample/RNN.c: MTRNN functions
MTRNN_Sample/Kohonen.h: header for Kohonen.c
MTRNN_Sample/Kohonen.c: functions related to Kohonen map
MTRNN_Sample/PlotRealtime.h: header for PlotRealtime.c
MTRNN_Sample/PlotRealtime.c: functions for plotting
MTRNN_Sample/Makefile
MTRNN_Sample/Makefile_with_plot: Makefile with plotting functions
MTRNN_Sample/Makefile_NO_plot: Makefile without plotting dunctions
MTRNN_Sample/README: this file
MTRNN_Sample/data: directory for saving training results
MTRNN_Sample/tmp0
MTRNN_Sample/tmp0/L.G.intA: initial states
MTRNN_Sample/tmp0/tmpL.wtA: MTRNN weights
MTRNN_Sample/tmp0/train.ft: parameters
MTRNN_Sample/tmp0/tmp.train.pat: training sequences
MTRNN_Sample/tmp0/tmp.koh.wt: kohonen-net weights
MTRNN_Sample/tmp0/sample.intA: initial states (used in sample training)
MTRNN_Sample/tmp0/sample.tmpL.wtA: MTRNN weights (trained by using sample data)
MTRNN_Sample/tmp0/sample.train.ft: parameters (used in sample training)
MTRNN_Sample/tmp0/sample.train.pat: training sequences (used in sample training)
MTRNN_Sample/tmp0/sample.koh.wt: kohonen-net weights (used in sample training)


************************************************************************
Technical Explanation
************************************************************************
-- The activation process with Kohonen + MTRNN
inK = (1-closeR)*(*inReal)+closeR*(*inPred) /* orig sensory-motor dim */
=>
Kohonen()
=>
*act  /* MTRNN dimension */
=>
invKohonen()
=>
inPred /* original sensory-motor dim */







