tomwalters@0: bin/ReadMe:  
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 	    AN INTRODUCTION TO THE AUDITORY IMAGE MODEL
tomwalters@0: 
tomwalters@0: This is the introduction for those wanting to use AIM to process waves
tomwalters@0: once the software package has been compiled, installed and tested.
tomwalters@0: The instructions for compiling and installing AIM are in the text file
tomwalters@0: ReadMe.First in the top directory of the software package.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: CONTENTS
tomwalters@0: 
tomwalters@0: I. Overview of Aim:   A description based on Patterson, Allerhand and
tomwalters@0: Giguere (1995). It illustrates the instructions used to display waves
tomwalters@0: and produce the auditory representations shown in Figures 2 and 3 of
tomwalters@0: the paper.
tomwalters@0: 
tomwalters@0: II. aimdemo_* Scripts:   A selection of demonstrations that illustrate
tomwalters@0: the range of auditory representations produced by AIM. A complete list
tomwalters@0: of demonstrations is contained in docs/aimDemonstrations.
tomwalters@0: 
tomwalters@0: III. Overview of Documentation:   A brief description of the 
tomwalters@0: documentation available and how to access it. This information is also
tomwalters@0: available in docs/aimDocumentation.
tomwalters@0: 
tomwalters@0: IV. Setting Up Paths for AIM and manaim: The modifications to pathnames
tomwalters@0: required to make the AIM instructions and on-line help facilites
tomwalters@0: available from all the user's directories.  This information is also
tomwalters@0: available in docs/aimPaths.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: ______________________________________________________________________
tomwalters@0: 
tomwalters@0: I. OVERVIEW OF AIM (THE AUDITORY IMAGE MODEL)
tomwalters@0: 
tomwalters@0: The Section presents a brief tour of the facilities in AIM based on a
tomwalters@0: Letter to the Editor announcing the release of AIM in the Journal of
tomwalters@0: the Acoustical Society of America (1995). It introduces the three
tomwalters@0: auditory representations that AIM was originally developed to simulate
tomwalters@0: -- basilar membrane motion (BMM), neural activty patterns (NAPs), and
tomwalters@0: stabilised auditory images (SAIs).  It also introduces the main
tomwalters@0: features of the software platform by example; they are the
tomwalters@0: instructions and options that control the simulations and the displays
tomwalters@0: that present the results.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: A. Time-Domain Modelling Of Peripheral Auditory Processing:
tomwalters@0: 	A Modular architecture and a Software Platform
tomwalters@0: 
tomwalters@0: The text of the Letter is in PAG95.doc in aim/docs.  Figure 1 of the
tomwalters@0: paper is a schematic of the architecture of the auditory image
tomwalters@0: model. It was produced with a drawing package entirely separate from
tomwalters@0: the AIM software package.  A postscript version of Figure 1 is
tomwalters@0: contained in PAG95_F1.ps. It can be viewed with a postscript previewer
tomwalters@0: like ghostview.
tomwalters@0: 
tomwalters@0: The demonstrations are based on the wave for the word 'hat' which is
tomwalters@0: stored in the file 'hat' with 'little-endian' byte order. (This is the
tomwalters@0: order used in DEC, IBM, and SGI machines.)  A byte reversed version
tomwalters@0: with 'big-endian' order is provided in 'hat_br'. (This is the order
tomwalters@0: used in SUN, and HP machines.)
tomwalters@0: 
tomwalters@0: For an automated tour type
tomwalters@0: 
tomwalters@0: > aimdemo_hat	or
tomwalters@0: > aimdemo_hat_br 
tomwalters@0: 
tomwalters@0: depending on the byte order of your machine.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: Alternately, you can Execute the instructions individually on the
tomwalters@0: command line.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: B. Displaying Waves Prior to Auditory Analysis:
tomwalters@0: 
tomwalters@0: Waves can be displayed using the initial module of AIM, genwav.
tomwalters@0: 
tomwalters@0: For a display of the complete hat file, use
tomwalters@0: 
tomwalters@0: > genwav samplerate=22.05kHz top=2500 bottom=-2500 input=hat
tomwalters@0: 
tomwalters@0: To restrict the display to the portion of the file with the 'hat'
tomwalters@0: sound wave, use
tomwalters@0: 
tomwalters@0: > genwav samplerate=22.05kHz start=110 leng=230 top=2500 bottom=-2500 input=hat
tomwalters@0: 
tomwalters@0: For the BMMs in Figures 2a and 3a, and the NAPs in Figures 2b and 3b,
tomwalters@0: we want to restrict the analysis AIM performs to a stationary segment
tomwalters@0: of the vowel which is 32 ms in duration and which starts just before a
tomwalters@0: glottal pulse. Such a segment can be displayed with 
tomwalters@0: 
tomwalters@0: > genwav samplerate=22.05kHz start=182 leng=32 top=2500 bottom=-2500 input=hat
tomwalters@0: 
tomwalters@0: 
tomwalters@0: C. The Three Main Auditory Representations Produced by AIM
tomwalters@0:  
tomwalters@0: The remainder of this Section presents the AIM instructions used to
tomwalters@0: convert the wave for the word 'hat' into the auditory representations
tomwalters@0: of the sound presented in the individual panels of Figures 2 and 3 of
tomwalters@0: the paper (BMMs, NAPs and auditory images).
tomwalters@0: 
tomwalters@0: Figure 2: The functional version of AIM (panels a, b and c):
tomwalters@0: 
tomwalters@0: a> genbmm samplerate=22.05kHz start=182 leng=32 top=600 bot=-600 input=hat
tomwalters@0: 
tomwalters@0: b> gennap samplerate=22.05kHz start=182 leng=32 top=5000 input=hat
tomwalters@0: 
tomwalters@0: c> gensai samplerate=22.05kHz start=112 leng=100 top=2000 napdecay=3 input=hat
tomwalters@0: 
tomwalters@0: 
tomwalters@0: Figure 3: The physiological version of AIM (panels a, b and c):
tomwalters@0: 
tomwalters@0: a> genbmm filter=tlf start=182 leng=32 samplerate=22.05kHz top=600 bot=-600 input=hat
tomwalters@0: 
tomwalters@0: b> gennap compress=off transduction=med start=182 leng=32 samplerate=22.05kHz top=5000 input=hat
tomwalters@0: 
tomwalters@0: c> The correlogram version of the auditory image is produced by
tomwalters@0: generating a NAP of the sound, converting it into a correlogram with
tomwalters@0: acgram, and then displaying it with the facilites in the auditory
tomwalters@0: image module, gensai. The instruction sequence is as follows:
tomwalters@0: 
tomwalters@0: > genasi filter=tlf compress=off transduction=med leng=100 samplerate=22.05kHz  output=on
tomwalters@0: > acgram start=36ms wid=64ms lag=32ms norm=off frames=1 scale=.000002 hat.nap > hat_acg.sai
tomwalters@0: > gensai -useprevious start=0 top=3000 input=hat_acg
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: ________________________________________________________________________
tomwalters@0: 
tomwalters@0: II. AIMDEMO_* SCRIPTS
tomwalters@0: 
tomwalters@0: The following is a list of demonstration scripts available to
tomwalters@0: illustrate the operation of AIM and the different auditory
tomwalters@0: representations that it produces. The scripts are stored in
tomwalters@0: [aimdirectory]/scripts.
tomwalters@0: 
tomwalters@0: The syntax for the demos can be obtained by typing 
tomwalters@0: 
tomwalters@0: > aimdemo_???_??? help 
tomwalters@0: 
tomwalters@0: where '???_???' is one of the extensions listed below.  The simplest
tomwalters@0: way to begin is to copy the wave file "cegc" from the waves directory
tomwalters@0: to the current working directory, and type 
tomwalters@0: 
tomwalters@0: > aimdemo_tlf_all cegc
tomwalters@0: 
tomwalters@0: NOTE: The byte order for cegc is "little endian" (used by DEC,
tomwalters@0: IBM and SGI machines).  A byte reversed version with "big-endian"
tomwalters@0: order is the wave "cegc_br". (This is the order used in SUN and HP
tomwalters@0: machines.)
tomwalters@0: 
tomwalters@0: The sound in cegc is a set of stationary and gliding click trains that
tomwalters@0: play a lazy major triad (C-E-G) and its octave (C) over 2.1 sec.  The
tomwalters@0: click train at the start (C) is a particularly useful test and demo
tomwalters@0: stimulus. 
tomwalters@0: 
tomwalters@0: Once one or two of the aimdemos have been shown to work with cegc, you
tomwalters@0: should be in a position to try them on your own waves.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: I. The Funcional Version of AIM:
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 1. aimdemo_gtf_all   <wave_file>
tomwalters@0:    
tomwalters@0:    This script illustrates all stages of the functional version of AIM
tomwalters@0:    using the "auditory route". It focuses on landscape displays and
tomwalters@0:    the instructions involved are:
tomwalters@0: 
tomwalters@0: 	       genwav (display input waveform), 
tomwalters@0:                genstp (generate stapes velocity),
tomwalters@0:                genbmm (generate basilar membrane motion),
tomwalters@0:                gennap (generate neural activity pattern),
tomwalters@0:                gensai (generate stabilized auditory image) and
tomwalters@0:                genspl (generate spiral version of auditory image).  
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 2. aimdemo_gtf_sai  <wave_file>
tomwalters@0: 
tomwalters@0:    This script presents the wave in <wave_file> using genwav, and
tomwalters@0:    then produces its rectangular auditory image using gensai. It is
tomwalters@0:    the simplest auditory image demo.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 3. aimdemo_gtf_spectra   <wave_file>
tomwalters@0:    
tomwalters@0:    This script illustrates the functional version of AIM using the
tomwalters@0:    "spectral route".  It focuses on spactral displays and the
tomwalters@0:    instructions involved are:
tomwalters@0: 
tomwalters@0: 	       genwav (display input waveform), 
tomwalters@0:                genasa (generate auditory spectral analysis), and
tomwalters@0:                genepn (generate excitation pattern)
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 4. aimdemo_gtf_2dat  <wave_file>
tomwalters@0: 
tomwalters@0:    The script illustrates 2-dimensional adaptive-thresholding
tomwalters@0:    (2D-AT) using genwav, genstp, genbmm and finally gennap. 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: II. The Physiological Version of AIM:
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 1. aimdemo_tlf_all    <wave_file>
tomwalters@0:  
tomwalters@0:    This demo script illustrates the entire physiological
tomwalters@0:    version of AIM using the "auditory route".  It uses the
tomwalters@0:    transmission-line filterbank (option filter=tlf) and the Meddis
tomwalters@0:    neural transduction module (option transduction=Meddis).  The
tomwalters@0:    instructions involved are:
tomwalters@0: 
tomwalters@0:                genwav (display input waveform), 
tomwalters@0:                genstp (generate stapes velocity),
tomwalters@0:                genbmm (generate basilar membrane motion),
tomwalters@0:                gennap (generate neural activity pattern),
tomwalters@0:                acgram (generate autocorrelogram).
tomwalters@0: 
tomwalters@0:    
tomwalters@0: 2. aimdemo_tlf_med  <wave_file>
tomwalters@0: 
tomwalters@0:    The script illustrates the Meddis Haircell module.  The AIM
tomwalters@0:    functions involved are genwav, genbmm and gennap.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 3. aimdemo_tlf_spectra   <wave_file>
tomwalters@0: 
tomwalters@0:    This script illustrates the "spectral route" through the
tomwalters@0:    physiological version of AIM.  It focuses on spectral displays and
tomwalters@0:    the instructions involved are genwav, genasa and genepn.
tomwalters@0:    
tomwalters@0: 
tomwalters@0: 4. aimdemo_tlf_lowhigh <wave_file>
tomwalters@0: 
tomwalters@0:    This script illustrates the level dependancies in the physiological
tomwalters@0:    version of AIM, and its ability to simulate cochlear damage. The
tomwalters@0:    instructions involved are:
tomwalters@0: 
tomwalters@0:    genwav [display input wave], 
tomwalters@0:    genbmm [cochlea level = 30dB], 
tomwalters@0:    genbmm [cochlea level = 90dB],
tomwalters@0:    gennap [Normal cochlea + Meddis high spont-rate fibre] and
tomwalters@0:    genasa [total OHC destruction, with no feedback]
tomwalters@0:           Note: - very poor frequency resolution.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: ________________________________________________________________________
tomwalters@0: 
tomwalters@0: III. OVERVIEW OF DOCUMENTATION
tomwalters@0: 
tomwalters@0: 
tomwalters@0: An introduction to the Documentation for the Auditory Image Model of
tomwalters@0: Peripheral Auditory Processing
tomwalters@0: 
tomwalters@0: 
tomwalters@0: A. Initial Contact Points and Aquisition of the Software Package
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 1. WWW Page. 
tomwalters@0: 
tomwalters@0:    Address:   http://www.mrc-apu.cam.ac.uk/aim/
tomwalters@0: 
tomwalters@0:    An overview of AIM on the internet with facilities for acquiring
tomwalters@0:    the software package. 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 2. Journal reference. 
tomwalters@0: 
tomwalters@0:    The software package is described in a recent article entitled
tomwalters@0: 
tomwalters@0:    "Time-domain modelling of peripheral auditory processing:
tomwalters@0: 	A modular architecture and a software platform"
tomwalters@0: 
tomwalters@0:    by Roy D. Patterson and Mike H. Allerhand and Christian Giguere,
tomwalters@0:    Journal of the Acoustical Society of America, 1995 (in press).
tomwalters@0: 
tomwalters@0:    The text of the article is stored in  [aim]/docs/PAG95.doc
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 3. ftp instructions:
tomwalters@0: 
tomwalters@0:    The instructions for obtaining AIM by ftp are stored in
tomwalters@0:    [aim]/docs/ftp.doc
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: B. Installation and Test
tomwalters@0: 
tomwalters@0: 1. ReadMe.First
tomwalters@0: 
tomwalters@0:    This document appears in top directory of aim when the aim.tar file is
tomwalters@0:    unpacked.  It is the same file as that in the ftp directory
tomwalters@0:    /pub/aim. It contains the instructions for compiling AIM, testing
tomwalters@0:    the installation, and setting up paths to the instructions, the
tomwalters@0:    aimtools, and the online documentation (manual pages accessed
tomwalters@0:    through 'manaim').
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: C. Introduction to the Operation of AIM
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 1. bin/ReadMe
tomwalters@0: 
tomwalters@0:    This is the initial ReadMe file for those wanting to use AIM once it
tomwalters@0:    has been installed and tested. It begins with a guided tour of AIM and
tomwalters@0:    then describes the user documentation and where to find it. 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 2. Introduction to AIM instructions:   docs/aimInstructions
tomwalters@0: 
tomwalters@0:    An introduction to the instructions and command-line options used to
tomwalters@0:    control the auditory model is stored in  docs/aimInstructions.
tomwalters@0:    The instructions have the form gen???. The command 'gen -help | more'
tomwalters@0:    lists the three letter combinations that may replace ??? and
tomwalters@0:    briefly describes the operations they invoke.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 3. AIM on-line help:	gen??? -help
tomwalters@0: 
tomwalters@0:    The instruction 'gen -help | more' lists the AIM instructions.
tomwalters@0: 
tomwalters@0:    The instructions have the form 'gen??? -options <file_name>'.
tomwalters@0: 
tomwalters@0:    The final three letters of the AIM instruction specify the point
tomwalters@0:    in the system where the user chooses to observe the output.
tomwalters@0:    Instructions of the form 'gen??? -help' cause AIM to list the
tomwalters@0:    options that control AIM up to that output point along with a brief
tomwalters@0:    description of the option and its current and default value.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 4. Manual pages for AIM instructions:	manaim gen???
tomwalters@0: 
tomwalters@0:    The documentation for each instruction and its options is
tomwalters@0:    provided in standard manual pages accessed by instructions of the
tomwalters@0:    form 'manaim gen???'.  Begin with 'manaim genwav' which describes
tomwalters@0:    non-auditory options such as those for the AIM display and for
tomwalters@0:    the input and output files.
tomwalters@0: 
tomwalters@0:    A complete listing of the AIM instructions is included in the listing
tomwalters@0:    produced by the instruction 'manaim -k all | more'.
tomwalters@0: 
tomwalters@0:    Manual pages can be printed with commands of the form
tomwalters@0:    'manaim gen??? | lpr'.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 5. Manual pages for AIM tools:	 manaim <aimtool_name>
tomwalters@0: 
tomwalters@0:    The software package includes a set of 'aimtools' for generating
tomwalters@0:    and manipulating input waves, and for processing the multi-channel,
tomwalters@0:    multi-frame output of AIM.
tomwalters@0: 
tomwalters@0:    There are manual pages for the aimtools accessed by instructions of
tomwalters@0:    the form 'manaim <aimtool_name>'.
tomwalters@0: 
tomwalters@0:    A complete listing of the aimtools is included in the listing
tomwalters@0:    produced by the instruction 'manaim -k all | more'.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: D. Additional Facilities
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 1. Silent Options: 	docs/aimSilentOptions
tomwalters@0: 
tomwalters@0:    AIM includes a number of 'silent options' that are occassionally
tomwalters@0:    useful but not sufficiently important to warrant positions on the
tomwalters@0:    options lists produced by the on-line help (gen??? -help).
tomwalters@0: 
tomwalters@0:    A list of the silent options is provided in docs/aimSilentOptions
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 2. File Formats: 	docs/aimFileFormats
tomwalters@0: 
tomwalters@0:    A description of the layout of information in the output files
tomwalters@0:    produced by AIM is presented in docs/aimFileFormats
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 3. AIM list: 	mail aim@mrc-apu.cam.ac.uk
tomwalters@0: 
tomwalters@0:    An email list for AIM users has been set up. The instructions for
tomwalters@0:    joining and retiring from the mail list are presented in
tomwalters@0:    docs/aimMailList. 
tomwalters@0: 
tomwalters@0:    Note that the list is not moderated. It is a facility whereby users
tomwalters@0:    can communicate for their mutual benefit rather than a question
tomwalters@0:    answering facility provided by the software developers.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: ______________________________________________________________________
tomwalters@0: 
tomwalters@0: IV. SETTING UP PATHS FOR AIM AND MANAIM:
tomwalters@0: 
tomwalters@0: 
tomwalters@0: As with all applications, the use of AIM is greatly assisted by the
tomwalters@0: setting up of appropriate pathnames for the executables and on-line
tomwalters@0: help.
tomwalters@0: 
tomwalters@0: In the following ${DIR} is the pathname of the directory in which AIM is
tomwalters@0: installed in your file system. For example this might be: /usr/local/aim
tomwalters@0: 
tomwalters@0: 
tomwalters@0: A. Executables
tomwalters@0: 
tomwalters@0: The executable files of the model, AIM tools and the script files are located
tomwalters@0: in the ${DIR}/bin directory.
tomwalters@0: 
tomwalters@0: If the path name is set to this directory, these programs can be executed 
tomwalters@0: from anywhere in the system.  The best thing to do is to set the PATH 
tomwalters@0: variable of the environment to: 
tomwalters@0: 
tomwalters@0: 	   setenv PATH ${DIR}/bin:$PATH
tomwalters@0: 
tomwalters@0: This can be done in the .login, .profile or any other appropriate start-up
tomwalters@0: script.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: B. Manual Pages:
tomwalters@0: 
tomwalters@0: The `manaim' script prints AIM manual pages with appropriate name in the
tomwalters@0: Unix man page format.
tomwalters@0: 
tomwalters@0: If the user wishes to view the man pages through "xman", the
tomwalters@0: environment variable MANPATH needs to be setup to search the
tomwalters@0: [aim]/release/man directory along with the other default man
tomwalters@0: directories.
tomwalters@0: 
tomwalters@0: Add the directory which contains the AIM manual pages to the MANPATH
tomwalters@0: in your environment, for example by including the following in your
tomwalters@0: start-up script:
tomwalters@0: 
tomwalters@0: 	  setenv MANPATH ${DIR}/man:${MANPATH}
tomwalters@0: 
tomwalters@0: or, if MANPATH is an undefined variable:
tomwalters@0: 
tomwalters@0: 	  setenv MANPATH ${DIR}/man
tomwalters@0: 
tomwalters@0: 
tomwalters@0: For compatibility with systems which do not conventionally use a
tomwalters@0: MANPATH, the pathname of the AIM pages directory must be the first
tomwalters@0: pathname in the list.
tomwalters@0: 
tomwalters@0: The AIM man pages will be appear in the "User Commands" section and
tomwalters@0: the "Local" section of xman.