---------------------------------------------------------------------------
README file for CTA matlab package
---------------------------------------------------------------------------

Hiroaki Sasaki
4 Jan, 2013
version 1.0

This package includes codes to perform CTA estimation, and for comparison, 
ICA and TICA estimations are possible. By this package, one can partially 
reproduce several results published in 

[1] H. Sasaki, M.U. Gutmann, H. Shouno, and A. Hyvärinen. 
Topographic analysis of correlated components. 
In Proc. Asian Conference on Machine Learning (ACML), 
volume 25, pages 368–378, 2012.

or in the submitted paper,

[2] H. Sasaki, M. U. Gutmann, H. Shouno and A. Hyvärinen.
Correlated topographic analysis: Estimating an ordering of correlated 
components, submitted.

If this package is used in your publications, please cite the above paper.

---------------------------------------------------------------------------
Acknowledgments
---------------------------------------------------------------------------

I would like to thank Patrik O. Hoyer for distributing many of his useful
codes on the web. The following codes are adopted from his MATLAB packages 
[4,5]:

From [4]
 code/natural_image/data.m. 
 (This code is divided into two codes in the package, data.m and whiteing.m.)
 code/natural_image/visual.m.

From [5]
 code/complex_cell/makeCCoutputs/ccvisual.m
 code/complex_cell/makeCCoutputs/getdata.m
 code/complex_cell/makeCCoutputs/gabor.m
 code/complex_cell/makeCCoutputs/handmadebasis.m
 code/complex_cell/makeCCoutputs/visual.m

---------------------------------------------------------------------------
List of contents of the package
---------------------------------------------------------------------------
data/
 1-13.tiff                  - whole natural images. (adopted from [4].)

code/ 
 add_lastterm.m		    - adds the last term to the last table. 
 add_terms.m		    - adds the term to the previous table. 
 artificialsources.m	    - generates four cases of artificial sources.
 centering.m		    - makes the mean value of the input zero.
 compute_comb.m		    - computes a combination, 
                            \sum_t \log(\cosh(s_i-s_{i+1}))
 costgrad_ICA.m		    - returns the value and gradient of the ICA 
                            objective function.
 costgrad_TICA.m            - returns the value and gradient of the TICA 
                            objective function.
 costgrad_CTA.m		    - returns the value and gradient of the CTA 
                            objective function.
 estimation.m	            - performs estimation (three-step optimization).
 extract_neigboring.m       - extracts the neighboring components on the 
                            lattice.
 find_usedindice.m          - finds indices already used in the former steps. 
 logarithm.m	            - takes the logarithm to the input.
 make_adjacentS.m           - makes the adjacent components. 
 minimize.m	            - minimizes an objective function by the 
                            conjugate gradient method [3].
 narginerror.m	            - returns a error message.
 normalizebymax.m           - normalizes the input by its maximum absolute  
                            value.
 normalizevar.m             - normalizes the variance of the input to be 1.
 optonecomponent.m          - optimizes the last one component. 
 orthogonalizerows.m        - orthogonalizes rows in W.
 parametererror.m           - detects errors for parameter setting.
 removeDC.m                 - removes the DC component.
 ReorderingResignning.m	    - optimizes the order and signs of the components. 
 set_numberofcombinations.m - sets the number of combinations which we should 
                            take into account at a phase.
 set_numberofcomponents.m   - sets the number of components which we should 
                            take into account at a phase.
 set_startindex.m           - sets the start index.
 topographyMatrix.m         - creates topography matrix.
 unitnormrows.m             - normalizes rows in W to be 1.
 whitening.m                - performs whitening.

code/artdata
 boxplotsfor3methods.m - makes box plots for three methods to four cases of 
                       sources. 
 compute_Amariindex.m  - computes Amari index.
 compute_Tindex.m      - computes topography index.
 estimate.m            - performs CTA estimation to a case 4 source.
 estimateAll.m	       - performs ICA, TICA and CTA estimations to four 
                       cases of sources.
 normalizationP.m      - Normalizes performance matrix by dividing its 
                       absolute maximum value in each row or each column.
 Pforallcases.m        - displays performance matrices for ICA, TICA 
                       and CTA to four cases of sources.
 saveindResult.m       - computes Amari index and topography index and saves them. 

code/natural_image
 data.m	            - gathers natural image patches from whole images. (adopted from [4].)
 dispbasis.m        - displays estimated basis vectors.
 estimate.m         - performs estimation to natural image patches.
 visual.m           - visualizes basis vectors. (adopted from [4].)

code/complex_cells
 CCestimation.m - includes estimation (optimization) and preprocessing.
 dispHbasis.m   - displays estimated higher order basis vectors.
 estimate.m     - performs estimation to outputs of simulated complex cells.
 makeCCoutputs/ - is the directory includes codes to make outputs of 
                simulated complex cells and visualize higher order basis vectors.
                (the codes except for makeCCoutputs.m are adopted from [5].)
     
---------------------------------------------------------------------------
Usage of this package
---------------------------------------------------------------------------

Depending on the task which you would perform, go to the directory and run

>> estimate

estimate.m runs like a demo file. Then, analyze or visualize the results. For example, 
if you want to visualize basis vectors estimated from natural images, after setting
parameters in dispbasis.m, run

>> dispbasis

----------------------------------------------------------------------------
Questions and problems
----------------------------------------------------------------------------

If you had questions or found problems, please contact to me by email to 
hsasaki@cc.uec.ac.jp. 

----------------------------------------------------------------------------
Notes
----------------------------------------------------------------------------

We do not guarantee that this package well-fits your purposes and there are no bugs. 
Therefore, please use it at your own risk and we do not take any responsibility to 
your usage.

---------------------------------------------------------------------------
References
---------------------------------------------------------------------------
[3] C.E. Rasmussen. Conjugate Gradient Algorithm, version 2006-09-08. 2006.

[4] P.O. Hoyer. imageica Matlab Package. 
available at http://www.cs.helsinki.fi/u/phoyer/software.html

[5] P.O. Hoyer. contournet Matlab Package. 
available at http://www.cs.helsinki.fi/u/phoyer/software.html
