-*- mode: rst -*-

Neocognitron with MATLAB interface
==================================

This package contains examples of MATLAB interface for Fukushima's Neocognitron in visiome(Fukushima_).
The original source of Fukushima's Neocognitron can be obtained from VisiomePlatform_:

.. _VisiomePlatform: http://platform.visiome.neuroinf.jp/
.. _Fukushima: http://platform.visiome.neuroinf.jp/modules/xoonips/detail.php?item_id=375

In this packages, several wrappers are included for the Fukushima's Neocognitron. 
If you have any interest or comments for the interfaces, please contact to shouno@ice.uec.ac.jp.


All Copyrights for this interface routines are reserved by H.Shouno @ UEC Japan.

File Contents
-----------------

    * InitParams.m:

      - Description for several parameters including paths for MEX routine.
        This script set not only default parameters but executable path for the MEX library.
	You should set these parameters appropriately. 


    * TestNeocog.m:

      - Recognition test for the 'PatTest.dat' data. The integer argument for this function 
        means pattern number for test.


    * TestSorg.m:

      - Self-organization test for 'PatLearn.dat' data.

    * TestSorgL.m:

      - Self-organization for the recognition layer test for 'PatLearn.dat' data.

    * display_coef.m:
    
      - To display leanable connection, that is called, connection A(excitatory) and B(inhibitory).
        At least, these connection specification arguments are required required. The 3rd argument is for
        figure window specification.

    * display_layer.m:

      - To display the Neocognitron layer appropriately. At least one argument is required for showing layer.
        The 2nd argument means the row number to show, and the 3rd means figure window number.

    * display_pat.m:

      - To display the loaded patterns.

    * connect.dat:

      - Connection data from the original Fukushima's package.

    * PatLearn.dat:

      - Modified ETL1 pattern for the learning from the original Fukushima's package.

    * PatTest.dat:

      - Modified ETL1 pattern for the recognition test from the original Fukushima's package.

    * srcs/:

      - Source directory for the MEX routines, and makefiles.

    * Linux/:

      - Mex binaries for the Linux. If you use Linux, please set path argument in InitParams.m appropriately

    * Macintosh/:

      - Mex binaries for the Macintosh. If you use Linux, please set path argument in InitParams.m appropriately

    * Windows/:

      - Mex binaries for the Windows. If you use Linux, please set path argument in InitParams.m appropriately


Recognition test
-----------------

    1. Modify the path for the MEX binaries described in 'InitParams.m'.
    2. If you'd like to try recognition test, type the command such like::

        >>  cat = TestNeocog

    3. Then, several Uc layers response are displayed, and category number is returned in the variable cat
    4. To examine another pattern, set pattern number to the argument of the TestNeocog(), such as::

        >>  cat = TestNeocog( 10 )

       then, the 10th pattern in the 'PatLearn.dat' is examined.
  
    5. If you'd like to see another cell response like Us{2} for 10th pattern, please use display_layer(), such as::

       >>  InitParams
       >>  P = PatLoad( 'PatLearn.dat' );
       >>  for l=1:LH, [A{l} B{l}] = ReadConnect( 'connect.dat', l-1 ), end
       >>  Ug = OnOff( P(:,:, 10 ) );
       >>  Us{1} = Sres( UsSize(1), Ug, A{1}, B{1}, C{1}, Thr(1) );
       >>  Uc{1} = Cres( UcSize(1), Us{1}, D{1} );
       >>  Us{2} = Sres( UsSize(2), Uc{1}, A{2}, B{2}, C{2}, Thr(2) );
       >>  display_layer( Us{2}, 8, 16 );

       then, the 2nd S-cell layer's respose are displayed.

Self-organization test
-----------------------

    1. Modify the path for the MEX binaries described in 'InitParams.m'.
    2. The default self organization layer is set to Us{2}, 
       that is, connection A{2} and B{2} are self-organized, which is described in the ''TestSorg.m'
    3. If you type the command such like::

       >> TestSorg

       then, 2nd layer's self-organization process is displayed in the 2nd window. The 1st window displays 
       a reference connections created by Fukushima's original program included in the 'connect.dat'

    4. The recognition layer is self-organized by 'TestSorgL.m', since category map is required.


Functions
-----------------------

This package provides following MEX functions. 
Macintosh, Linux, and Windows directory includes these shared library
file.

  1. Calclation for Responses.
      * OnOff

        - OnOff() calculate On/Off layer responses

      * Sres

        - Sres() calculate S-cell layer responses

      * Cres

        - Cres() calculate C-cell layer responses

      * CresL

        - CresL() calculate the highest C-cell layer responses for recognition

  2. Calculation for Learning.
      * Angle

        - Angle() projects several input for edge detector in Us{1}

      * Delta1stStage

        - Delta1stStage() is for self-organization the first edge detect layer Us{1}

      * Sorg

        - Sorg() is for self-organization of the higher feature extractor of S-cells.
          In this package, we use this function for Us{2}, and Us{3}.

      * SorgL

        - SorgL() is for self-organization of the highest stage feature extractor of S-cells.
          In this package, we use this function for Us{4}.

  3. Create fixed valued sharing weight.
      * MakeAC

        - MakeAC() creates lateral inhibited connection, called mexican-hat type connection.

      * MakeC

        - MakeC() creates gaussian type connection. This function create several connections.

      * MakeCG

        - MakeCG() creates On-center/Off-surround type connection for OnOff() routine.

  4. File I/O for the original Fukushima's Project.

      * PatLoad

        - PatLoad() obtains the modified ETL-1 patterns into the MATLAB matrix format.
          This function can read both 'PatLearn.dat', and 'PatTest.dat'.
          
      * ReadConnect

        - ReadConnect() reads learnable connection called A{}, and B{} from the original 
          Fukushima's file, included as 'connect.dat'

      * ReadCategory

        - ReadCategory() obtains the category map from the learned data 'connect.dat'



Acknowlegement
-----------------------

This package is supported from Visiome platform. 
To create this package, I have fruitful discussion and suggestion from following people: 

* Prof. Fukushima, 
* Prof. Okada (Univ. of Tokyo), 
* Prof. Morie (Kyushu Inst. Tech.), 
* Prof. Miyamoto (Kyushu Inst. Tech.), 
* Dr. Kimoto (Oita National College of Tech.)
* Dr. Sato (RIKEN)

I will appreciate these supported people.
Moreover Mr. Inagaki, Mr Yamamoto (University of Electro-Communication) support to create this package, I also thank them.
