%%% readme.txt for zbcatmodel %%%

This is Version 1.1 of the public distribution of the code for the cat auditory
periphery model of:

        Zilany, M. S. A. and Bruce, I. C. (2006). "Modeling auditory-nerve
        responses for high sound pressure levels in the normal and impaired
        auditory periphery," Journal of the Acoustical Society of
        America 120(3):14461466,

   and
 
        Zilany, M. S. A. and Bruce, I. C. (In Press). "Representation of the vowel
        /eh/ in normal and impaired auditory nerve fibers: Model predictions of
        responses in cats," to appear in Journal of the Acoustical Society of America
        July 2007.

Please cite these papers if you publish any research results obtained with this
code or any modified versions of this code.

Note:-

-  The only difference between the models presented in the two papers is
   the function for cochlear amplifier (CA) gain versus characteristic frequency (CF),
   given by Eq. (6) in Zilany and Bruce (2006) and by Eq. (1) in Zilany and Bruce (2007).
   In this version of the code (1.1), the new CA gain versus CF function of Zilany
   and Bruce (2007) is used by default.  If you wish to use the old function, then you
   will need to uncomment line 279 of zbcatmodel.c and comment out line 280, and then
   recompile the code.

-  This version of the code has an "unpublished feature" of being able to model
   AN fibers with different spontaneous rates (from 0 to 150 spikes/s) and the
   corresponding changes in the threshold and the rate-level function. A spontaneous
   rate of 50 spikes/s (before refractory effects) was used in the Zilany and Bruce
   papers.

The Matlab and C code included with this distribution is designed to be
compiled as a Matlab MEX file, i.e., the compiled model MEX function will run
as if it were a Matlab function.  The code can be compiled within Matlab using
the function:

    mexzbcatmodel_lcc.m     if you are using the lcc compiler supplied with
                            Matlab on a Win32 system; or

    mexzbcatmodel_unix.m    if you are using a compiler such as gcc on a Unix
                            system.

The reason for the difference is that Unix compilers typically include the
drand48() random number generator, which has the precision required for spike
generation in this model.  The lcc compiler does not include drand48(), so I
have made use of the Gnu Scientific Library (GSL; http://www.gnu.org/software/gsl/)
equivalent.  The required files from the GSL are included with this distribution,
as is a copy of the GNU General Public License (gpl.txt), under which the GSL
is released.

Note that in this version (1.1), Microsoft C compilers are no longer supported,
because there are issues with recent versions of the  Microsoft C compilers and
recent Matlab releases.  Please switch to using the lcc compiler that comes with
Matlab if you are using MS Windows.

Once you have compiled the MEX file in Matlab, type:

    help zbcatmodel

for instructions on how to call the MEX function.

I have also included:-

1. a sample Matlab script "testzbcatmodel.m" for setting up an acoustic stimulus
   and the model parameters and running the model, and

2. a function "fitaudiogram.m" for estimating the parameters for outer and
   inner hair cell impairment, Cohc and Cihc, respectively, for a given
   audiogram.


ACKNOWLEDGMENTS

Some of this code is based on code written by Xuedong (Frank) Zhang, Michael
Heinz, Ian Bruce and Laurel Carney for the model of:

    Zhang, X., Heinz, M. G., Bruce, I. C., and Carney, L. H. (2001). "A
    phenomenological model for the responses of auditory-nerve fibers: I.
    Nonlinear tuning with compression and suppression," J. Acoust. Soc. Am. 109,
    648670,

and by Qing Tan and Laurel Carney for the model of:

    Tan, Q. and Carney, L. H. (2003). A phenomenological model for the
    responses of auditory nerve fibers. II. Nonlinear tuning with a
    frequency glide, J. Acoust. Soc. Am. 114, 20072020.

%%%  Ian C. Bruce (ibruce@ieee.org) and M. S. Arefeen Zilany, June 2006 - April 2007 %%%
