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.


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.


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 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

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


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

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

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

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 &lt;wave_file&gt; 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.


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.

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

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 &lt;file_name&gt;'.
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 &lt;aimtool_name&gt;'.
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

An email list for AIM users has been set up. The instructions for
joining and retiring from the mail list are presented in
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.


As with all applications, the use of AIM is greatly assisted by the
setting up of appropriate pathnames for the executables and on-line

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

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

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.