>> clear all ; clc ; PLM_demo

Hello!

Release 21 Oct 2005.

This script is intended to get you started with the Hebbian
perceptual learning model. It assumes you have already run
PercLearn_install, which has updated the MATLAB path.

The model and experiments are described in the following articles:
Petrov, A., Dosher, B. & Lu, Z.-L. (2005).
  The dynamics of perceptual learning: An incremental reweighting model.
  Psychological Review, 102 (4), ???-???.
Petrov, A., Dosher, B., & Lu, Z.-L. (resubmitted)
  Perceptual learning without feedback in non-stationary contexts: Data and model.
  Vision Research.
Abstract and reprints available on-line:
  http://www.socsci.uci.edu/~apetrov/pub/perclearn/
New information may be available on the PLM project web site:
  http://www.socsci.uci.edu/~apetrov/proj/plearn/
  (If the web site has moved, just Google search for 'Alex Petrov'.)

Changing current dir to C:\PercLearn\PLModel1
It is recommended that you open the file PLM_DEMO.M in the MATLAB Editor
and inspect the code as you follow along.
Type 'return' and press Enter to continue.
K>> return

*******  Let us make two sample stimuli first.
The stimuli are created by the function MAKE_PLE_STIM, which is
part of the software that administered the experiment dubbed PLExp1
and reported in the Psych Review article cited above.

As a general rule, the parameters needed to do something are bundled in some
parameter structure, which is then passed to the functions that do the real job.
There are functions with names ending in '_params' that generate default params
from scratch. It is conventional to store the PLExp1 in the variable P:

P = 

            size: [64 64]
        duration: 75
    Gabor_orient: [-0.1745 0.1745]
    noise_orient: [-0.2618 0.2618]
     noise_Cpeak: 0.6667
     Gabor_Cpeak: [0.2300 0.1500 0.1000 0.5000]
    Gabor_params: [1x1 struct]
    noise_params: [1x1 struct]
      LUT_params: [1x1 struct]
        position: {[0 -111]  [0 111]}
           times: [1x1 struct]
        mask_idx: [889x1 double]
           Gabor: [4-D double]
          Filter: [64x64x2 double]
          colors: [1x1 struct]
    viewing_dist: 720
          mm_pix: 0.5655
         deg_pix: 0.0450
      msec_frame: 8.3333
        N_frames: 9
               x: [1x64 double]

Let us make a left Gabor target in Context L, easiest difficulty level (target contrast):
  Name           Size                   Bytes  Class

  P              1x1                   340976  struct array
  PLM_path       1x21                      42  char array
  context        1x1                        8  double array
  cstr           1x44                      88  char array
  diff           1x1                        8  double array
  orient         1x1                        8  double array
  stimL         64x64                   32768  double array

Grand total is 46164 elements using 373898 bytes

Type 'return' and press Enter to continue.
K>> return

Contrast that with a right target in the same Context L:
Type 'return' and press Enter to continue.
K>> return

*******  Representational subsystem...
The parameters of the representational subsystem of the model are:

Idef = 

     img_size: [64 64]
     FFT_size: [128 128]
     LUT_gray: 128
     LUT_span: 127
      deg_pix: 0.0450
       flipud: 1
     bkgr_idx: 1
     D_orient: [-45 -30 -15 0 15 30 45]
     N_orient: 7
     D_spfreq: [1 1.4142 2 2.8284 4]
     N_spfreq: 5
    HW_orient: 15
      octaves: 1
      W2sigma: 0.4247
    CGC_const: 0
    CGC_Fpool: [5x5 double]
     CGC_mode: 'E1/N1'
    rep_scale: 1
    FW_integr: 2
      centers: [0 0]
     rep_size: [7 5 1]

Before we can run PLFRONTEND, we must call MAKE_PLFRONTEND on the Idef structure.

Front end: 7 orientations by 5 spatial frequencies.
Orientation HWHH: 15 deg.
Sp.freq. FWHH: 1 octaves.
Contrast gain control via divisive normalization: E1/N1.
Radial Gaussian integration weights: FW=2.0 deg.vis.ang.
Integration centers:  (0.0,0.0) deg.vis.ang.

Global variable FRONTEND_MEMOIZATION updated.

PLFRONTEND can now be used to transform any 64x64 image into a 35-element representation:
Type 'return' and press Enter to continue.
K>> return

*******  PLM_CACHE
The perceptual subsystem involves computer-intensive convolutions.
It is therefore convenient to generate a large cache of representations,
store them in the global variable PLM_CACHE, and reuse them over and over again.
The function CACHE_INPUTS is the tool to do that. It would take several hours
to generate a sufficient number of samples, however, so let us just load it
from the file PLM_CACHE.mat instead:
PLM_CACHE is a structure array with 12 elements, one for each stimulus type.
There are 5000 samples of each kind. For example:

ans = 

    arg: [1 1 1]
      N: 5000
    rep: [5000x35 double]

Note that these 'representations' do not yet contain internal noise and have not been
passed through the saturating nonlinearity of the activation function of the representaiton units.
The functions AGGREG_CACHE and HEBB_STATS facilitate the statistical analysis of these caches.
Type 'return' and press Enter to continue.
K>> return

*******  Non-stationary stimulus presentation sequences
Experiments PLExp1 and PLExp2 involve presentation schedules that alternate the
predominant background orientation in an alternating non-stationary manner.
The functions EXPAND_BLOCK_SPEC and BLOCK_FROM_CACHE are the tools to generate such schedules.
See the documentation section of these files for details, particularly Example 3 in BLOCK_FROM_CACHE.M
For our present purposes, let us just load the schedule descriptors from the file SCHED.MAT:
The variable sched1 defines Schedule 1, and the variable sched2 defines Schedule 2, as described
in Petrov, Dosher, & Lu (2005). There are 32 blocks of 300 trials each. Each block contains 50
replications of 6 stimulus kinds: 2 Gabor orientations X 3 Gabor contrasts. The context is fixed
within each block but changes in 8-block-long epochs depending on the schedule. For example, block 1in Schedule 1 has the following specification. The first 3 columns correspond to the arguments of
MAKE_PLE_STIM and the .arg field in PLM_CACHE. Note that everything is in context L=1 in this case.

ans =

     1     1     1    50
     2     1     1    50
     1     2     1    50
     2     2     1    50
     1     3     1    50
     2     3     1    50

Type 'return' and press Enter to continue.
K>> return

We are now in a position to generate some stimulus sequences (or 'descriptors').
The first ten trials in the sequence are as follows:

ans =

           1           3           1           5        1498
           1           3           1           5        1534
           1           3           1           5        1113
           2           2           1           4         467
           1           1           1           1        2393
           1           3           1           5         691
           2           3           1           6         792
           1           3           1           5        3682
           1           1           1           1         487
           2           1           1           2        4063

The variable DESCR has 9600 trials (rows) and 5 columns, as documented in BLOCK_FROM_CACHE.
The last two columns specify the cache index (1-12) and the replication index (1-5000) in the
global variable PLM_CACHE, respectively.  PLModel2 pulls the corresponding representation from
representation on each simulated trial, avoiding any calls to PLFRONTEND.
Type 'return' and press Enter to continue.
K>> return

*******  Running the perceptual learning model...
With all this infrastructure at hand, we're finally ready to run the learning component of the model.
The function PLM_PARAMS generates a default parameter structure, with parameter values reported in the
Vision Research article cited above. (Use PLM_PARAMS1 for the values in the Psych Review article.)

Mparams = 

      rep_size: [7 5 1]
       max_act: 0.5000
      rep_gain: 0.8000
      out_gain: 5
     rep_noise: 0.1000
     out_noise: 0.1700
      W_minmax: [-1 1]
        W_init: 0.1700
       W0_seed: [35x1 double]
    learn_rate: 0.0016
    runav_rate: 0.0200
     criterion: 2.2000
      fdbk_wgt: 1.8000
    fdbk_fract: 1
     fdbk_mode: 1
      blk_size: 300

Type 'return' and press Enter to continue.
K>> return

PLM_HEBB2 implements the most recent version of the model (as of July 2005).
It uses soft clamping to introduce feedback, and introduces it only on error.
See the Vision Research article for discussion.  PLM_HEBB1 implements a slightly
different version used in the Psych Review article (Petrov, Dosher, & Lu, 2005).
(PLM_HEBB1 is a special case of PLM_HEBB2 when Mparams.fdbk_wgt=Inf and .fdbk_mode=1.

The model can be invoked in several different ways, as documented in PLM_HEBB2.M
The simplest syntax is [o,Wh] = PLM_Hebb2(descr,Mparams):

ans =

    1.0000   -0.4195   -0.4016         0         0   -0.4195
    1.0000   -0.4584   -0.4270   -0.0440         0   -0.4584
    1.0000   -0.2633   -0.4049   -0.0871         0   -0.2633
    1.0000   -0.1576   -0.2842   -0.1294    1.0000    0.4998
    1.0000   -0.2732   -0.3319   -0.1708         0   -0.2732
    1.0000   -0.4094   -0.4737   -0.2114         0   -0.4094
    2.0000    0.3478   -0.2746   -0.2511         0    0.3478
    1.0000   -0.3288   -0.4172   -0.2021         0   -0.3288
    2.0000    0.1133   -0.3767   -0.2421   -1.0000   -0.4998
    2.0000    0.0188   -0.0970   -0.1932         0    0.0188


The leftmost column in the matrix O is the behavioral response of the model (1="Left", 2="Right").
The other columns keep track of various internal quantities. The printout above lists the first 10 trials of a 9600-trial run.
Type 'return' and press Enter to continue.
K>> return

The variable Wh keeps the weight history of the run. See PLM_HEBB2.M for details.
Type 'return' and press Enter to continue.
K>> return

*******  Calculate d' learning curves
The function PLM_STATS converts the long sequence of binary responses into z-transformed
probabilities of correct response for congruent and incongruent stimuli in each block.
This is analogous to the analysis of the behavioral data (see PLEDATA_BY_SBJ and PLE2_STATS).
PLM_STATS can analyze a whole batch of runs at once, which are then averaged by PLM_SUMMARY.
In our case we have just a single run to analyze:

sumstats = 

       N_runs: 1
     zP_congr: [32x3 double]
     zP_incon: [32x3 double]
       dprime: [32x3 double]
        accZP: [0.8406 0.8842 0.9823 1.2286 0.4504 -0.1447]
    mnA_congr: [32x3 double]
    mnA_incon: [32x3 double]
       Aprime: [32x3 double]
         accA: [0.1621 0.1802 0.1908 0.2306 0.0892 -0.0325]
    mnI_congr: [32x3 double]
    mnI_incon: [32x3 double]
       Iprime: [32x3 double]
         accI: [0.4717 0.4866 0.4941 -0.0515 -0.2102 -0.3334]
     contextc: [1x20 double]
     contexti: [1x20 double]
       otherc: [1x20 double]
       otheri: [1x20 double]

Type 'return' and press Enter to continue.
K>> return

*******  Plot the model performance against PLExp1 data.
The file HUMAN_ZCONGR.MAT contains the group averages of the z-probability profiles of
the first perceptual learning experiment (PLExp1, with feedback). See PLEDATA_BY_SBJ for details.
PLOT_PLM_FIT can then be used to plot the model data against the human data from PLExp1.
(Use PLOT_PLM_FIT2 with ..Type 'return' and press Enter to continue.
K>> return

*******  Where to go from here.
This illustrates the main functions involved in running the multichannel perceptual learning model
with default parameters.  There are specialized utilities for parameter search -- see in particular
the functions PLM_ZCONGR2, MAKE_CHEV, PLM_SEARCH_PARAMS, and the Paramsearch Toolbox.
The README files and the numerous .txt notes in various directories under PLModel1 contain transcripts
of most simulations and data fits reported in the two journal articles listed in the beginning of this tutorial.
The notes in PLModel1\newsimul\*.txt are the most recent ones.
There is also quite a bit of documentation in the preambles of the .m functions that implement the model.

Thank you for your interest in this work.
If you have any questions, please contact Alex Petrov at apetrov@grey.colorado.edu.
Check the PLM project web site for recent updates:  http://www.socsci.uci.edu/~apetrov/proj/plearn/ 
End of PLM_DEMO.  Last updated 21 Oct, 2005.

