
==========================  E-I Net  ============================
                      (release 4/23/2013)

E-I Net is a spiking simulation of a neural network with excitatory
and inhibitory neurons that can learn Gabor-like receptive fields
as found in area V1 of the visual cortex of the brain.

The results of this simulation are presented in the following paper:
    King PD, Zylberberg J, DeWeese MR (2013). Inhibitory interneurons
        decorrelate excitatory cells to drive sparse code formation
        in a spiking model of V1. J Neuroscience.

Feel free to skip to "GETTING STARTED" below.

This MatLab library provides all source code needed to generate
the results of the paper. It is based on a spiking neural model simulator
written in MatLab which is found in the "neurosim" directory.

The "sample_data" directory contains pregenerated simulation results
saved as MatLab ".mat" files. This data can be regenerated by running
the scripts named "train1_..." through "train4_...".

Neurosim is a general model for simulating neural circuits composed
of populations of cells with identical properties ("cell groups").
E-I Net uses two cell groups -- an excitatory population named "V1e"
and an inhibitory population named "V1i". There is also an "external"
input cell group named "input" that represent the whitened input
to the simulation, but these are not actual neurons that are simulated.

Cell groups are connected to each other with connection descriptors
called "input blocks". The input block describes the characteristics
of the connections between the input and output cell groups, including
properties such as the learning rule and learning rate. The weight
matrices that are updated during learning are stored as part of the
input block.

All cell groups comprising the circuit to be simulated are collected
in at network model (NetModel) structure called "model".

The simulator allows arbitrary circuit structures to be specified
as a configuration input to the simulation using hierarchically
organized MatLab "struct" objects. Model template files with
sets of default structural properties are found in the files
with names like NetModel_InitXxxx.m.

The function RunVisionNetworkSimulation() takes as input a hierarchical
set of properties describing the network to be simulated, constructs
the network, and runs the simulation using whitened images as training data.

See the Neurosim Technical Overview PDF document on the website
for technical design documentation: http://pking.org/research/EINet


------------------------  GETTING STARTED  ------------------------

1. Install MatLab

2. Save the training image data "IMAGES.MAT" to the "sample_data"
   directory after downloading it from here:
      http://redwood.berkeley.edu/bruno/sparsenet/

3. From within Matlab, cd to the project directory:
      cd ei_net

4. Run "demo1_SmallNetwork" to see if everything is working:
      demo1_EINet

5. Plot all figures that appear in the paper from pregenerated data
      plot_figures

6. Run the master script to generate all plots that appear in the paper
   (see documentation in this script for details on the other scripts)
      run_everything

7. Consult the Neurosim Technical Overview PDF for technical details.
      http://pking.org/research/EINet


-----------------  OVERVIEW OF SIMULATION MODEL  ------------------

Layers of model (high to low):
   5) demo scripts: demo1, demo2, demo3, ...
   4) RunVisionNetworkSimulation, NetModel_Figure
   3) NetModel_InitV1eV1i
   2) NetModel_Init, NetModel_UpdateFast, NetModel_Stats
   1) CellGroup_Init, CellGroup_AddInput


LEARNING RATES

The learning rates that appear in the paper result from the combination
of several different learning rates used in the simulator. The weight-change
learning rate that appears in the paper is calculated as "lrateW" here:
    lrateW = (model.lrateScale / model.simTimeStep) * model.learningRate
              * model.cg_xxx.learningRate * model.cg_xxx.ib_yyy.learningRate
          = .1 * model.learningRate * model.cg_xxx.ib_yyy.learningRate
    lrate_in_E = .1 * .4 * .2  = .008
    lrate_E_I  = .1 * .4 * .7  = .028
    lrate_E_I  = .1 * .4 * 1.5 = .06


-----------------------  NATURAL IMAGE DATA  -----------------------

The image data used for training comes from the "sparsenet" work
of Olshausen & Field (1996, 1997).

The IMAGES.mat file required to run this network can be
downloaded from Bruno Olshausen's website here:
    http://redwood.berkeley.edu/bruno/sparsenet/

References:

Olshausen BA, Field DJ (1997). Sparse coding with an overcomplete
basis set: A strategy employed by V1?  Vision Research, 37, 3311-3325.
ftp://redwood.ucdavis.edu/pub/papers/VR.pdf

Olshausen BA, Field DJ (1996). Emergence of simple-cell receptive
field properties by learning a sparse code for natural images.
Nature, 381, 607-609.
ftp://redwood.ucdavis.edu/pub/papers/nature-paper.pdf


