9/10/99  M. G. Heinz  Anmodheinz00 (version 1.0)

This file contains directions for getting AN model responses from the
LINEAR, HUMAN filterbank used in Heinz, Colburn, and Carney 
(2001, Neural Computation).

Note: these files are also available at
EarLab, a digital warehouse of auditory models and data.

/*********** To Obtain the Files and Compile the Program ***********/
First: copy all of the files from the ftp site -
>ftp engc.bu.edu
>login: anonymous
>cd pub/andata/anmod2			???
>mget *

You should end up with several files, including: "readme.text" [this
file], "anmodheinz00.c" (the source code), two sample stimulus
waveforms "click" and "tone", two corresponding input-parameter files
"inclick" and "intone", a script to compile and run the program
"domodel", a MATLAB M-file to plot the outputs generated by the model
"viewoutputs.m", and a pdf file "model_descript.pdf" that
contains a description of the model.

The model description (model_descript.ps) is an excerpt from the Heinz
et al (2000) manuscript that has been submitted to JASA.

Create an executable by typing: gcc anmodheinz00.c -lm -o anmodheinz00
   (I can't leave an executable on the ftp site...)

The resulting executable program is: anmodheinz00 

/*********** To Run the Program ***********/

Here is a sample of the questions the program will ask and valid

> anmodheinz00  (type this to start it...)  

 Heinz, Colburn, and Carney (2000) Auditory-Nerve Model (Linear, Human) - 
        Version 1.0 (9/10/99)
This version reads in files with <= 30,000 pts. 
Filterbank parameters: Set Center-filter freq [0], or Range of freqs [1]?: 1
Lowest frequency filter(Hz): 500
Highest frequency filter(Hz): 2000
# of Filters in Bank: 5
Resulting delx = 2.173366 [Distance between filters (mm along BM)]
Stimulus Waveform Filename: tone
Time Step Size in input file (secs): 20e-6
Input Duration of Simulation (in msec): 50
  [Zeroes will be added to end of input waveform out to this duration.]
Ready to read in from the waveform file: tone
  First ten values are:
i = 0  stim[i] = 0.000000
i = 1  stim[i] = 0.000000
i = 2  stim[i] = 0.000002
i = 3  stim[i] = 0.000006
i = 4  stim[i] = 0.000013
i = 5  stim[i] = 0.000026
i = 6  stim[i] = 0.000043
i = 7  stim[i] = 0.000066
i = 8  stim[i] = 0.000094
i = 9  stim[i] = 0.000128

Health [-1=LIN(sharp,Low Thresh); 1=NL; 0=LIN(broad,HT); -2:LIN(broad,LT)]:  -1
chan = 1 out of 5  Cf= 500.000000
chan = 2 out of 5  Cf= 726.000000
chan = 3 out of 5  Cf= 1031.000000
chan = 4 out of 5  Cf= 1443.000000
chan = 5 out of 5  Cf= 2000.000000

 AN filter bank simulation is complete. 

/************** Shortcut *******/

You can also pipe the input parameters into the program from an
"input" file, e.g.:

anmodheinz00 < intone

{The parameter values for the example above are currently in this
input file, which can be modified as you desire.)

Or, you can type:

domodel < intone

which is a batch job that compiles and runs the model with the input
file.  (If you get the error "permission denied', make this batch job
executable with: chmod +x domodel.)

/********** To use model outputs -***********/

The following files will be sitting in your directory after running
the program:

** The key output is the Probability of firing as a function of time -
we refer to this waveform as the "instantaneous firing rate" and its
filename is "ifr.dat".  It is an ascii file, so you can look at it
with: more ifr.dat, or read it into MATLAB (see below), etc.  It is
organized such that the first row contains the time values at the
sampling time you specified, while the remaining rows contain the
ifr's from each channel (see C-code header for more detail).  Note
that the baseline value of ifr is 50.0, which is the 'spontaneous
rate' of the synapse (e.g. the units of the waveform ifr are sp/sec).

Other ascii output files:
 stim.dat (stimulus waveform)
 bm.dat (linear-filter output)
 ihc.dat (ihc voltage plot)

There are 4 flags that can be set in the C code (savestim, savebm,
saveihc, saveifr) that specify which outputs from the model get saved
(0: don't save; 1: save).

These files are WRITTEN OVER every time you run the program, so copy
them to other filenames if you want to save them.

/*********** To plot the model responses at different stages ********/

The file "viewoutputs.m" is a MATLAB M-file that will plot the
filterbank responses from the different stages of the model, or you
can use the ascii output files in whatever way you prefer.  Note:
viewoutputs.m is currently setup assuming that all 4 of outputfiles
have been saved.


(Note: A click stimulus is hard to see on the timescale of the plot,
but the first 10 values of the stimulus are printed out when you run
the program to allow a quick check of your click.)

(Note: the two-sample click in the sample file 'click' results in a 40
usec click, since the step size is 20 usec.  ALso, the sample click
file has peak amplitude of 1.0 Pascals - this value can be scaled as
desired, but note that it is in Pascals, not dB, etc....)



Michael G. Heinz