AIM92

h1. An Introduction to AIM92

This is the introduction for those wanting to use AIM to process waves

once the software package has been compiled, installed and tested.

The instructions for compiling and installing AIM are in the text file

ReadMe.First in the top directory of the software package.

CONTENTS

I. Overview of Aim:   A description based on Patterson, Allerhand and

Giguere (1995). It illustrates the instructions used to display waves

and produce the auditory representations shown in Figures 2 and 3 of

the paper.

II. aimdemo_* Scripts:   A selection of demonstrations that illustrate

the range of auditory representations produced by AIM. A complete list

of demonstrations is contained in docs/aimDemonstrations.

III. Overview of Documentation:   A brief description of the 

documentation available and how to access it. This information is also

available in docs/aimDocumentation.

IV. Setting Up Paths for AIM and manaim: The modifications to pathnames

required to make the AIM instructions and on-line help facilites

available from all the user's directories.  This information is also

available in docs/aimPaths.

______________________________________________________________________

I. OVERVIEW OF AIM (THE AUDITORY IMAGE MODEL)

The Section presents a brief tour of the facilities in AIM based on a

Letter to the Editor announcing the release of AIM in the Journal of

the Acoustical Society of America (1995). It introduces the three

auditory representations that AIM was originally developed to simulate

-- basilar membrane motion (BMM), neural activty patterns (NAPs), and

stabilised auditory images (SAIs).  It also introduces the main

features of the software platform by example; they are the

instructions and options that control the simulations and the displays

that present the results.

A. Time-Domain Modelling Of Peripheral Auditory Processing:

	A Modular architecture and a Software Platform

The text of the Letter is in PAG95.doc in aim/docs.  Figure 1 of the

paper is a schematic of the architecture of the auditory image

model. It was produced with a drawing package entirely separate from

the AIM software package.  A postscript version of Figure 1 is

contained in PAG95_F1.ps. It can be viewed with a postscript previewer

like ghostview.

The demonstrations are based on the wave for the word 'hat' which is

stored in the file 'hat' with 'little-endian' byte order. (This is the

order used in DEC, IBM, and SGI machines.)  A byte reversed version

with 'big-endian' order is provided in 'hat_br'. (This is the order

used in SUN, and HP machines.)

For an automated tour type

> aimdemo_hat	or

> aimdemo_hat_br 

depending on the byte order of your machine.

Alternately, you can Execute the instructions individually on the

command line.

B. Displaying Waves Prior to Auditory Analysis:

Waves can be displayed using the initial module of AIM, genwav.

For a display of the complete hat file, use

> genwav samplerate=22.05kHz top=2500 bottom=-2500 input=hat

To restrict the display to the portion of the file with the 'hat'

sound wave, use

> genwav samplerate=22.05kHz start=110 leng=230 top=2500 bottom=-2500 input=hat

For the BMMs in Figures 2a and 3a, and the NAPs in Figures 2b and 3b,

we want to restrict the analysis AIM performs to a stationary segment

of the vowel which is 32 ms in duration and which starts just before a

glottal pulse. Such a segment can be displayed with 

> genwav samplerate=22.05kHz start=182 leng=32 top=2500 bottom=-2500 input=hat

C. The Three Main Auditory Representations Produced by AIM

The remainder of this Section presents the AIM instructions used to

convert the wave for the word 'hat' into the auditory representations

of the sound presented in the individual panels of Figures 2 and 3 of

the paper (BMMs, NAPs and auditory images).

Figure 2: The functional version of AIM (panels a, b and c):

a> genbmm samplerate=22.05kHz start=182 leng=32 top=600 bot=-600 input=hat

b> gennap samplerate=22.05kHz start=182 leng=32 top=5000 input=hat

c> gensai samplerate=22.05kHz start=112 leng=100 top=2000 napdecay=3 input=hat

Figure 3: The physiological version of AIM (panels a, b and c):

a> genbmm filter=tlf start=182 leng=32 samplerate=22.05kHz top=600 bot=-600 input=hat

b> gennap compress=off transduction=med start=182 leng=32 samplerate=22.05kHz top=5000 input=hat

c> The correlogram version of the auditory image is produced by

generating a NAP of the sound, converting it into a correlogram with

acgram, and then displaying it with the facilites in the auditory

image module, gensai. The instruction sequence is as follows:

> genasi filter=tlf compress=off transduction=med leng=100 samplerate=22.05kHz  output=on

> acgram start=36ms wid=64ms lag=32ms norm=off frames=1 scale=.000002 hat.nap > hat_acg.sai

> gensai -useprevious start=0 top=3000 input=hat_acg

________________________________________________________________________

II. AIMDEMO_* SCRIPTS

The following is a list of demonstration scripts available to

illustrate the operation of AIM and the different auditory

representations that it produces. The scripts are stored in

[aimdirectory]/scripts.

The syntax for the demos can be obtained by typing 

> aimdemo_???_??? help 

where '???_???' is one of the extensions listed below.  The simplest

way to begin is to copy the wave file "cegc" from the waves directory

to the current working directory, and type 

> aimdemo_tlf_all cegc

NOTE: The byte order for cegc is "little endian" (used by DEC,

IBM and SGI machines).  A byte reversed version with "big-endian"

order is the wave "cegc_br". (This is the order used in SUN and HP

machines.)

The sound in cegc is a set of stationary and gliding click trains that

play a lazy major triad (C-E-G) and its octave (C) over 2.1 sec.  The

click train at the start (C) is a particularly useful test and demo

stimulus. 

Once one or two of the aimdemos have been shown to work with cegc, you

should be in a position to try them on your own waves.

I. The Funcional Version of AIM:

1. aimdemo_gtf_all   <wave_file>

   This script illustrates all stages of the functional version of AIM

   using the "auditory route". It focuses on landscape displays and

   the instructions involved are:

	       genwav (display input waveform), 

               genstp (generate stapes velocity),

               genbmm (generate basilar membrane motion),

               gennap (generate neural activity pattern),

               gensai (generate stabilized auditory image) and

               genspl (generate spiral version of auditory image).  

2. aimdemo_gtf_sai  <wave_file>

   This script presents the wave in <wave_file> using genwav, and

   then produces its rectangular auditory image using gensai. It is

   the simplest auditory image demo.

3. aimdemo_gtf_spectra   <wave_file>

   This script illustrates the functional version of AIM using the

   "spectral route".  It focuses on spactral displays and the

   instructions involved are:

	       genwav (display input waveform), 

               genasa (generate auditory spectral analysis), and

               genepn (generate excitation pattern)

4. aimdemo_gtf_2dat  <wave_file>

   The script illustrates 2-dimensional adaptive-thresholding

   (2D-AT) using genwav, genstp, genbmm and finally gennap. 

II. The Physiological Version of AIM:

1. aimdemo_tlf_all    <wave_file>

   This demo script illustrates the entire physiological

   version of AIM using the "auditory route".  It uses the

   transmission-line filterbank (option filter=tlf) and the Meddis

   neural transduction module (option transduction=Meddis).  The

   instructions involved are:

               genwav (display input waveform), 

               genstp (generate stapes velocity),

               genbmm (generate basilar membrane motion),

               gennap (generate neural activity pattern),

               acgram (generate autocorrelogram).

2. aimdemo_tlf_med  <wave_file>

   The script illustrates the Meddis Haircell module.  The AIM

   functions involved are genwav, genbmm and gennap.

3. aimdemo_tlf_spectra   <wave_file>

   This script illustrates the "spectral route" through the

   physiological version of AIM.  It focuses on spectral displays and

   the instructions involved are genwav, genasa and genepn.

4. aimdemo_tlf_lowhigh <wave_file>

   This script illustrates the level dependancies in the physiological

   version of AIM, and its ability to simulate cochlear damage. The

   instructions involved are:

   genwav [display input wave], 

   genbmm [cochlea level = 30dB], 

   genbmm [cochlea level = 90dB],

   gennap [Normal cochlea + Meddis high spont-rate fibre] and

   genasa [total OHC destruction, with no feedback]

          Note: - very poor frequency resolution.

________________________________________________________________________

III. OVERVIEW OF DOCUMENTATION

An introduction to the Documentation for the Auditory Image Model of

Peripheral Auditory Processing

A. Initial Contact Points and Aquisition of the Software Package

1. WWW Page. 

   Address:   http://www.mrc-apu.cam.ac.uk/aim/

   An overview of AIM on the internet with facilities for acquiring

   the software package. 

2. Journal reference. 

   The software package is described in a recent article entitled

   "Time-domain modelling of peripheral auditory processing:

	A modular architecture and a software platform"

   by Roy D. Patterson and Mike H. Allerhand and Christian Giguere,

   Journal of the Acoustical Society of America, 1995 (in press).

   The text of the article is stored in  [aim]/docs/PAG95.doc

3. ftp instructions:

   The instructions for obtaining AIM by ftp are stored in

   [aim]/docs/ftp.doc

B. Installation and Test

1. ReadMe.First

   This document appears in top directory of aim when the aim.tar file is

   unpacked.  It is the same file as that in the ftp directory

   /pub/aim. It contains the instructions for compiling AIM, testing

   the installation, and setting up paths to the instructions, the

   aimtools, and the online documentation (manual pages accessed

   through 'manaim').

C. Introduction to the Operation of AIM

1. bin/ReadMe

   This is the initial ReadMe file for those wanting to use AIM once it

   has been installed and tested. It begins with a guided tour of AIM and

   then describes the user documentation and where to find it. 

2. Introduction to AIM instructions:   docs/aimInstructions

   An introduction to the instructions and command-line options used to

   control the auditory model is stored in  docs/aimInstructions.

   The instructions have the form gen???. The command 'gen -help | more'

   lists the three letter combinations that may replace ??? and

   briefly describes the operations they invoke.

3. AIM on-line help:	gen??? -help

   The instruction 'gen -help | more' lists the AIM instructions.

   The instructions have the form 'gen??? -options <file_name>'.

   The final three letters of the AIM instruction specify the point

   in the system where the user chooses to observe the output.

   Instructions of the form 'gen??? -help' cause AIM to list the

   options that control AIM up to that output point along with a brief

   description of the option and its current and default value.

4. Manual pages for AIM instructions:	manaim gen???

   The documentation for each instruction and its options is

   provided in standard manual pages accessed by instructions of the

   form 'manaim gen???'.  Begin with 'manaim genwav' which describes

   non-auditory options such as those for the AIM display and for

   the input and output files.

   A complete listing of the AIM instructions is included in the listing

   produced by the instruction 'manaim -k all | more'.

   Manual pages can be printed with commands of the form

   'manaim gen??? | lpr'.

5. Manual pages for AIM tools:	 manaim <aimtool_name>

   The software package includes a set of 'aimtools' for generating

   and manipulating input waves, and for processing the multi-channel,

   multi-frame output of AIM.

   There are manual pages for the aimtools accessed by instructions of

   the form 'manaim <aimtool_name>'.

   A complete listing of the aimtools is included in the listing

   produced by the instruction 'manaim -k all | more'.

D. Additional Facilities

1. Silent Options: 	docs/aimSilentOptions

   AIM includes a number of 'silent options' that are occassionally

   useful but not sufficiently important to warrant positions on the

   options lists produced by the on-line help (gen??? -help).

   A list of the silent options is provided in docs/aimSilentOptions

2. File Formats: 	docs/aimFileFormats

   A description of the layout of information in the output files

   produced by AIM is presented in docs/aimFileFormats

3. AIM list: 	mail aim@mrc-apu.cam.ac.uk

   An email list for AIM users has been set up. The instructions for

   joining and retiring from the mail list are presented in

   docs/aimMailList. 

   Note that the list is not moderated. It is a facility whereby users

   can communicate for their mutual benefit rather than a question

   answering facility provided by the software developers.

______________________________________________________________________

IV. SETTING UP PATHS FOR AIM AND MANAIM:

As with all applications, the use of AIM is greatly assisted by the

setting up of appropriate pathnames for the executables and on-line

help.

In the following ${DIR} is the pathname of the directory in which AIM is

installed in your file system. For example this might be: /usr/local/aim

A. Executables

The executable files of the model, AIM tools and the script files are located

in the ${DIR}/bin directory.

If the path name is set to this directory, these programs can be executed 

from anywhere in the system.  The best thing to do is to set the PATH 

variable of the environment to: 

	   setenv PATH ${DIR}/bin:$PATH

This can be done in the .login, .profile or any other appropriate start-up

script.

B. Manual Pages:

The `manaim' script prints AIM manual pages with appropriate name in the

Unix man page format.

If the user wishes to view the man pages through "xman", the

environment variable MANPATH needs to be setup to search the

[aim]/release/man directory along with the other default man

directories.

Add the directory which contains the AIM manual pages to the MANPATH

in your environment, for example by including the following in your

start-up script:

	  setenv MANPATH ${DIR}/man:${MANPATH}

or, if MANPATH is an undefined variable:

	  setenv MANPATH ${DIR}/man

For compatibility with systems which do not conventionally use a

MANPATH, the pathname of the AIM pages directory must be the first

pathname in the list.

The AIM man pages will be appear in the "User Commands" section and

the "Local" section of xman.