###### 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 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. -------------------------------------------------------------