######  PercLearn\PLModel1\README-2008-02-22.txt

README for the PLModel1 folder, release 1.1.1, 22 Feb 2008.

This folder contains the MATLAB implementation of the multi-channel Hebbian
reweighting model described in the following publications:
Petrov, A., Dosher, B, and Lu, Z.-L. (2005).
  The dynamics of perceptual learning: An incremental reweighting model.
  Psychological Review, 112 (4), 715-743.
  Reprint available at http://alexpetrov.com/pub/perclearn/
Petrov, A., Dosher, B, and Lu, Z.-L. (2006).
  Perceptual Learning Without Feedback in Non-Stationary Contexts:
  Data and model.  Vision Research, 46, 3177-3197.
  Reprint available at http://alexpetrov.com/pub/plfeedbk/
  

The PLModel1 folder contains the following subfolders(**) and files(--):
  -- PLM_demo.m -- A brief tutorial on how to use this software.
  ** demo -- The figures (in .jpg) format generated by PLM_demo.m
  -- PLM_params.m -- default parameters for the Hebbian learning model.
  -- PLM_Hebb2.m -- the entry point to the most recent version of the model.
       Introduces feedback on error only, as described in the Vision Research 
       article above.
  -- PLM_Hebb1.m -- the entry point to an earlier version of the model
       described in the Psych Review article. Feedback introduced on all trials.
  -- PLM_Zcongr2.m and PLM_Zcongr1.m -- variants of PLM_Hebb2 and PLM_Hebb1
       that return the probability to respond "congruent" rather than generating
       a binary response on each trial. This speeds up the parameter search.
  -- PLM_CACHE.mat -- MATLAB data file containing 5000 representations of each
       of the 12 stimulus kinds (2 Gabors X 2 contexts X 3 contrast levels).
       The cache is generated by frontend/cache_inputs.m, and is used for all
       simulations in the two papers cited above. PLM_Hebb1 and PLM_Hebb2
       depend on a global variable PLM_CACHE for their inputs. They do not
       work on the raw images themselves. See frontend/PLFrontend.m for that.
  -- Hebb_work.txt -- transcripts of MATLAB sessions taken during the development
       of the model and the simulations in the Psych Review paper. See the
       numerous *.TXT files in the NEWSIMUL folder for newer transcripts
       illustrating the use of the model, data fitting, etc.
  ** frontend -- folder with MATLAB files implementing the perceptual front
       end of the model. Some of the main files there are:
       -- PLM_input_params.m -- default bandwidths, etc
       -- make_PLFrontEnd.m -- process the input parameters and generate
            the global variable FRONTEND_MEMOIZATION required by PLFrontend.m
       -- PLFrontEnd.m -- takes in a grayscale image and produces a 35-element
            vector of activation values.
       -- cache_inputs.m -- generate images (using PLExp1\make_PLE_stim.m),
            process them with PLFrontend, and store them in a cache file.
  ** probab -- PLModel-specific software for automated parameter search. 
       Depends on the paramsearch toolbox in utils\paramsearch.
  ** sharpen -- simulations with modified bandwidth parameters -- see Figure 13
       in the Psych Review paper and the associated section in the Gen.Discussion.
  ** simul -- folder with software (note in particular PLM_STATS.M) and session
       transcripts from the main simulations with the model, March 2003.
  ** newsimul -- folder with transcripts and MATLAB data from the new data fits
       for the no-feedback Vision Research paper. See in particular the files
       HEBB2_FITS.TXT and HEBB2M_FITS.TXT -- they illustrate the most recent
       practice of running and experimenting with the model (as of July 2005).
  -- README-2008-02-22.txt -- this file


Brief advice on running the model:
The model was developed and run on Matlab ver 5.3.0.10183 (R11) for Windows.
It also ported flawlessly to Matlab 6 (R13) for Windows and later to Matlab 7.5
(R2007b) for Mac OS X Intel.  It depends on the STATS and OPTIM toolboxes,
although the STATS dependency is probably minimal.
To run it, the following folders must be on the MATLAB path:
  PLModel1
  PLModel1\frontend
  PLModel1\probab        % for PLM_paramsearch, Hebb_stats, etc
  PLModel1\simul         % for PLM_stats, etc
  PLExp1\programs        % for make_PLE_stim, etc
  utils
  utils\general
  utils\nomstats
  utils\paramsearch
  <maybe a few other utils too, but those should be the main ones...>
  toolbox\stats          % for norminv, etc.
  toolbox\optim          % mostly fmincon
..\PercLearn_install.m  takes care of all that (modes 4 or 5).

There are numerous transcripts (*.TXT files) of all sorts of MATLAB sessions
taken during the development and fitting the model. Use them as guidance.
Also, make sure to run PLM_demo. It shows how to generate images, pass them
through the representational subsystem of the model (PLFrontend), generate
a representation cache, generate a non-stationary presentation sequence,
run the learning task-specific subsystem of the model (PLM_Hebb2), and
finally analyze and plot the model performance. Check it out!

All this software (possibly in newer versions) is available for download from 
http://alexpetrov.com/proj/plearn/
In the (unlikely) event that the web site has moved, just Google search for "Alex Petrov".

See ..\PLReadme2008-02-22.txt and PercLearn_install for installation instructions.
See also:
work\PLPaper1 and work\PLPaper2 for the papers cited above,
work\PLExp1,2,3,4,5 for five perceptual learning experiments,
work\utils for files such as split.m, xtab.m, and paramsearch.m.

This summarizes some of what Alex Petrov has done during his post-doctoral
research at the University of California Irvine in collaboration with
Professors Barbara Dosher and Zhong-Lin Lu from Oct 2001 to July 2005.

## Version Log ##
Release 1.0.0, 2005-08-11 -- APetrov -- First public release
Release 1.1.0, 2005-10-22 -- APetrov -- Installer script added
Release 1.1.1, 2008-02-22 -- APetrov -- Minor compatibility issues resolved

##  Installation Instructions ##
0. You need to have Matlab (preferably version 6 or higher) with the
   Statistical Toolbox and Optimization Toolbox installed.
   PsychToolbox is recommended but not required (http://psychtoolbox.org/).
   The experiments were run under Mac OS 9; they don't run under Windows
   because PsychToolbox for Windows is too immature.
   The model was developed and tested under Windows but runs on
   Macintosh and Unix just as well. It does not depend on PsychToolbox.
   It was straightforward to port it to Matlab 7.5 (R2007b) for Mac OS X Intel, Feb 2008.
1. Unpack the archive into a directory of your choice, e.g, C:\PercLearn.
   WinZip will create the subdirectory tree outlined above, with subdirs, etc.
2. Enter MATLAB and chdir to the directory chosen in 1.
3. From the command line, execute the script PercLearn_install.
   It has several "modes" (from 0 to 5) which install various subsets of
   the full package. Mode 5 installs everything.
4. Everything should be functional at this point, though you probably would
   have no idea how to use the various functions scattered in multiple folders.
   A good place to start is to run PLM_demo at that point, provided you have
   installed the PLModel subset (modes 4 or 5 above).
5. Then you may wish to check the README files in each folder and subfolder,
   as well as the .txt notes.  PLModel1\newsim\*.txt are the most recent.

## License and Disclaimer ##
This software is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
See the GNU General Public License (reproduced in PercLearn_license.m) and
the Free Software Foundation website (http://www.fsf.org) for more details.

The software is freely available and freely redistributable, according
to the conditions of the GNU General Public License. You may not
distribute the software, in whole or in part, in conjunction with
proprietary code. That means you ONLY have my permission to distribute a
program that uses my code IF you also make freely available (under the
terms of the GNU GPL) the source code for your whole project. You may
not pass on the software to another party in its current form or any
altered, embellished or reduced form, without acknowledging the author,
citing the Petrov, Dosher, & Lu (2005) Psych Review paper, and including a 
copy of the GNU GPL.

Please notify the author of any bugs, notes, comments or suggested
changes, particularly of any useful changes you may have made to 
your own copy of the software.

Thank you for your interest in the Perceptual Learning Model. Happy modeling!

Alex Petrov, February 2008

-------------------------------------------------------------
Alexander A. Petrov:  apetrov [at] alexpetrov [dot] com

Assistant Professor, Department of Psychology
Ohio State University, Columbus, OH 43210
http://alexpetrov.com

It is better to light one candle than to curse the darkness.
-------------------------------------------------------------
