######  PercLearn\PLReadme2008-02-22.txt

README for the Perceptual Learning project files, release 1.1.1, 22 Feb 2008.

This archive contains MATLAB software for administering two perceptual 
learning experiments (PLExp1-2), the data collected from over two dozen
participants over a period of three years, the MATLAB implementation of
the multi-channel Hebbian reweighting model, and two long papers decribing
the model and the first two experiments in detail. 

References:
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 archive contains the following folders (**) and files (--):
  ** PLExp1 -- perceptual learning experiment with feedback in non-stationary
       contexts. This experiment is reported in the Psych Review paper above.
  ** PLExp2 -- follow-up without feedback. Reported in the Vision Res. paper.
  ** PLModel1 -- MATLAB implementation of the model
  ** utils -- various toolboxes, see PLModel1\readme.txt for details
 -- PercLearn_license.m -- GNU GP License of the perceptual learning software.
  -- PercLearn_install.m -- A script putting the relevant folders on the
       MATLAB path and pre-processing some raw ASCII data files.
  -- PercLearn_install_transcript.txt -- A log of a PercLearn_install session.
  -- PLReadme2008-02-22.txt -- This file
Each folder has its own README file. Go there for further details.
See also PLModel1\PLM_demo.m and the numerous notes (*.txt) throughout.
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".

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