comparison docs/ReadMe @ 0:5242703e91d3 tip

Initial checkin for AIM92 aimR8.2 (last updated May 1997).
author tomwalters
date Fri, 20 May 2011 15:19:45 +0100
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:5242703e91d3
1 bin/ReadMe:
2
3
4 AN INTRODUCTION TO THE AUDITORY IMAGE MODEL
5
6 This is the introduction for those wanting to use AIM to process waves
7 once the software package has been compiled, installed and tested.
8 The instructions for compiling and installing AIM are in the text file
9 ReadMe.First in the top directory of the software package.
10
11
12 CONTENTS
13
14 I. Overview of Aim: A description based on Patterson, Allerhand and
15 Giguere (1995). It illustrates the instructions used to display waves
16 and produce the auditory representations shown in Figures 2 and 3 of
17 the paper.
18
19 II. aimdemo_* Scripts: A selection of demonstrations that illustrate
20 the range of auditory representations produced by AIM. A complete list
21 of demonstrations is contained in docs/aimDemonstrations.
22
23 III. Overview of Documentation: A brief description of the
24 documentation available and how to access it. This information is also
25 available in docs/aimDocumentation.
26
27 IV. Setting Up Paths for AIM and manaim: The modifications to pathnames
28 required to make the AIM instructions and on-line help facilites
29 available from all the user's directories. This information is also
30 available in docs/aimPaths.
31
32
33
34 ______________________________________________________________________
35
36 I. OVERVIEW OF AIM (THE AUDITORY IMAGE MODEL)
37
38 The Section presents a brief tour of the facilities in AIM based on a
39 Letter to the Editor announcing the release of AIM in the Journal of
40 the Acoustical Society of America (1995). It introduces the three
41 auditory representations that AIM was originally developed to simulate
42 -- basilar membrane motion (BMM), neural activty patterns (NAPs), and
43 stabilised auditory images (SAIs). It also introduces the main
44 features of the software platform by example; they are the
45 instructions and options that control the simulations and the displays
46 that present the results.
47
48
49 A. Time-Domain Modelling Of Peripheral Auditory Processing:
50 A Modular architecture and a Software Platform
51
52 The text of the Letter is in PAG95.doc in aim/docs. Figure 1 of the
53 paper is a schematic of the architecture of the auditory image
54 model. It was produced with a drawing package entirely separate from
55 the AIM software package. A postscript version of Figure 1 is
56 contained in PAG95_F1.ps. It can be viewed with a postscript previewer
57 like ghostview.
58
59 The demonstrations are based on the wave for the word 'hat' which is
60 stored in the file 'hat' with 'little-endian' byte order. (This is the
61 order used in DEC, IBM, and SGI machines.) A byte reversed version
62 with 'big-endian' order is provided in 'hat_br'. (This is the order
63 used in SUN, and HP machines.)
64
65 For an automated tour type
66
67 > aimdemo_hat or
68 > aimdemo_hat_br
69
70 depending on the byte order of your machine.
71
72
73 Alternately, you can Execute the instructions individually on the
74 command line.
75
76
77 B. Displaying Waves Prior to Auditory Analysis:
78
79 Waves can be displayed using the initial module of AIM, genwav.
80
81 For a display of the complete hat file, use
82
83 > genwav samplerate=22.05kHz top=2500 bottom=-2500 input=hat
84
85 To restrict the display to the portion of the file with the 'hat'
86 sound wave, use
87
88 > genwav samplerate=22.05kHz start=110 leng=230 top=2500 bottom=-2500 input=hat
89
90 For the BMMs in Figures 2a and 3a, and the NAPs in Figures 2b and 3b,
91 we want to restrict the analysis AIM performs to a stationary segment
92 of the vowel which is 32 ms in duration and which starts just before a
93 glottal pulse. Such a segment can be displayed with
94
95 > genwav samplerate=22.05kHz start=182 leng=32 top=2500 bottom=-2500 input=hat
96
97
98 C. The Three Main Auditory Representations Produced by AIM
99
100 The remainder of this Section presents the AIM instructions used to
101 convert the wave for the word 'hat' into the auditory representations
102 of the sound presented in the individual panels of Figures 2 and 3 of
103 the paper (BMMs, NAPs and auditory images).
104
105 Figure 2: The functional version of AIM (panels a, b and c):
106
107 a> genbmm samplerate=22.05kHz start=182 leng=32 top=600 bot=-600 input=hat
108
109 b> gennap samplerate=22.05kHz start=182 leng=32 top=5000 input=hat
110
111 c> gensai samplerate=22.05kHz start=112 leng=100 top=2000 napdecay=3 input=hat
112
113
114 Figure 3: The physiological version of AIM (panels a, b and c):
115
116 a> genbmm filter=tlf start=182 leng=32 samplerate=22.05kHz top=600 bot=-600 input=hat
117
118 b> gennap compress=off transduction=med start=182 leng=32 samplerate=22.05kHz top=5000 input=hat
119
120 c> The correlogram version of the auditory image is produced by
121 generating a NAP of the sound, converting it into a correlogram with
122 acgram, and then displaying it with the facilites in the auditory
123 image module, gensai. The instruction sequence is as follows:
124
125 > genasi filter=tlf compress=off transduction=med leng=100 samplerate=22.05kHz output=on
126 > acgram start=36ms wid=64ms lag=32ms norm=off frames=1 scale=.000002 hat.nap > hat_acg.sai
127 > gensai -useprevious start=0 top=3000 input=hat_acg
128
129
130
131 ________________________________________________________________________
132
133 II. AIMDEMO_* SCRIPTS
134
135 The following is a list of demonstration scripts available to
136 illustrate the operation of AIM and the different auditory
137 representations that it produces. The scripts are stored in
138 [aimdirectory]/scripts.
139
140 The syntax for the demos can be obtained by typing
141
142 > aimdemo_???_??? help
143
144 where '???_???' is one of the extensions listed below. The simplest
145 way to begin is to copy the wave file "cegc" from the waves directory
146 to the current working directory, and type
147
148 > aimdemo_tlf_all cegc
149
150 NOTE: The byte order for cegc is "little endian" (used by DEC,
151 IBM and SGI machines). A byte reversed version with "big-endian"
152 order is the wave "cegc_br". (This is the order used in SUN and HP
153 machines.)
154
155 The sound in cegc is a set of stationary and gliding click trains that
156 play a lazy major triad (C-E-G) and its octave (C) over 2.1 sec. The
157 click train at the start (C) is a particularly useful test and demo
158 stimulus.
159
160 Once one or two of the aimdemos have been shown to work with cegc, you
161 should be in a position to try them on your own waves.
162
163
164
165 I. The Funcional Version of AIM:
166
167
168 1. aimdemo_gtf_all <wave_file>
169
170 This script illustrates all stages of the functional version of AIM
171 using the "auditory route". It focuses on landscape displays and
172 the instructions involved are:
173
174 genwav (display input waveform),
175 genstp (generate stapes velocity),
176 genbmm (generate basilar membrane motion),
177 gennap (generate neural activity pattern),
178 gensai (generate stabilized auditory image) and
179 genspl (generate spiral version of auditory image).
180
181
182 2. aimdemo_gtf_sai <wave_file>
183
184 This script presents the wave in <wave_file> using genwav, and
185 then produces its rectangular auditory image using gensai. It is
186 the simplest auditory image demo.
187
188
189 3. aimdemo_gtf_spectra <wave_file>
190
191 This script illustrates the functional version of AIM using the
192 "spectral route". It focuses on spactral displays and the
193 instructions involved are:
194
195 genwav (display input waveform),
196 genasa (generate auditory spectral analysis), and
197 genepn (generate excitation pattern)
198
199
200 4. aimdemo_gtf_2dat <wave_file>
201
202 The script illustrates 2-dimensional adaptive-thresholding
203 (2D-AT) using genwav, genstp, genbmm and finally gennap.
204
205
206
207 II. The Physiological Version of AIM:
208
209
210 1. aimdemo_tlf_all <wave_file>
211
212 This demo script illustrates the entire physiological
213 version of AIM using the "auditory route". It uses the
214 transmission-line filterbank (option filter=tlf) and the Meddis
215 neural transduction module (option transduction=Meddis). The
216 instructions involved are:
217
218 genwav (display input waveform),
219 genstp (generate stapes velocity),
220 genbmm (generate basilar membrane motion),
221 gennap (generate neural activity pattern),
222 acgram (generate autocorrelogram).
223
224
225 2. aimdemo_tlf_med <wave_file>
226
227 The script illustrates the Meddis Haircell module. The AIM
228 functions involved are genwav, genbmm and gennap.
229
230
231 3. aimdemo_tlf_spectra <wave_file>
232
233 This script illustrates the "spectral route" through the
234 physiological version of AIM. It focuses on spectral displays and
235 the instructions involved are genwav, genasa and genepn.
236
237
238 4. aimdemo_tlf_lowhigh <wave_file>
239
240 This script illustrates the level dependancies in the physiological
241 version of AIM, and its ability to simulate cochlear damage. The
242 instructions involved are:
243
244 genwav [display input wave],
245 genbmm [cochlea level = 30dB],
246 genbmm [cochlea level = 90dB],
247 gennap [Normal cochlea + Meddis high spont-rate fibre] and
248 genasa [total OHC destruction, with no feedback]
249 Note: - very poor frequency resolution.
250
251
252
253 ________________________________________________________________________
254
255 III. OVERVIEW OF DOCUMENTATION
256
257
258 An introduction to the Documentation for the Auditory Image Model of
259 Peripheral Auditory Processing
260
261
262 A. Initial Contact Points and Aquisition of the Software Package
263
264
265 1. WWW Page.
266
267 Address: http://www.mrc-apu.cam.ac.uk/aim/
268
269 An overview of AIM on the internet with facilities for acquiring
270 the software package.
271
272
273 2. Journal reference.
274
275 The software package is described in a recent article entitled
276
277 "Time-domain modelling of peripheral auditory processing:
278 A modular architecture and a software platform"
279
280 by Roy D. Patterson and Mike H. Allerhand and Christian Giguere,
281 Journal of the Acoustical Society of America, 1995 (in press).
282
283 The text of the article is stored in [aim]/docs/PAG95.doc
284
285
286 3. ftp instructions:
287
288 The instructions for obtaining AIM by ftp are stored in
289 [aim]/docs/ftp.doc
290
291
292
293 B. Installation and Test
294
295 1. ReadMe.First
296
297 This document appears in top directory of aim when the aim.tar file is
298 unpacked. It is the same file as that in the ftp directory
299 /pub/aim. It contains the instructions for compiling AIM, testing
300 the installation, and setting up paths to the instructions, the
301 aimtools, and the online documentation (manual pages accessed
302 through 'manaim').
303
304
305
306 C. Introduction to the Operation of AIM
307
308
309 1. bin/ReadMe
310
311 This is the initial ReadMe file for those wanting to use AIM once it
312 has been installed and tested. It begins with a guided tour of AIM and
313 then describes the user documentation and where to find it.
314
315
316 2. Introduction to AIM instructions: docs/aimInstructions
317
318 An introduction to the instructions and command-line options used to
319 control the auditory model is stored in docs/aimInstructions.
320 The instructions have the form gen???. The command 'gen -help | more'
321 lists the three letter combinations that may replace ??? and
322 briefly describes the operations they invoke.
323
324
325 3. AIM on-line help: gen??? -help
326
327 The instruction 'gen -help | more' lists the AIM instructions.
328
329 The instructions have the form 'gen??? -options <file_name>'.
330
331 The final three letters of the AIM instruction specify the point
332 in the system where the user chooses to observe the output.
333 Instructions of the form 'gen??? -help' cause AIM to list the
334 options that control AIM up to that output point along with a brief
335 description of the option and its current and default value.
336
337
338 4. Manual pages for AIM instructions: manaim gen???
339
340 The documentation for each instruction and its options is
341 provided in standard manual pages accessed by instructions of the
342 form 'manaim gen???'. Begin with 'manaim genwav' which describes
343 non-auditory options such as those for the AIM display and for
344 the input and output files.
345
346 A complete listing of the AIM instructions is included in the listing
347 produced by the instruction 'manaim -k all | more'.
348
349 Manual pages can be printed with commands of the form
350 'manaim gen??? | lpr'.
351
352
353 5. Manual pages for AIM tools: manaim <aimtool_name>
354
355 The software package includes a set of 'aimtools' for generating
356 and manipulating input waves, and for processing the multi-channel,
357 multi-frame output of AIM.
358
359 There are manual pages for the aimtools accessed by instructions of
360 the form 'manaim <aimtool_name>'.
361
362 A complete listing of the aimtools is included in the listing
363 produced by the instruction 'manaim -k all | more'.
364
365
366
367 D. Additional Facilities
368
369
370 1. Silent Options: docs/aimSilentOptions
371
372 AIM includes a number of 'silent options' that are occassionally
373 useful but not sufficiently important to warrant positions on the
374 options lists produced by the on-line help (gen??? -help).
375
376 A list of the silent options is provided in docs/aimSilentOptions
377
378
379 2. File Formats: docs/aimFileFormats
380
381 A description of the layout of information in the output files
382 produced by AIM is presented in docs/aimFileFormats
383
384
385
386 3. AIM list: mail aim@mrc-apu.cam.ac.uk
387
388 An email list for AIM users has been set up. The instructions for
389 joining and retiring from the mail list are presented in
390 docs/aimMailList.
391
392 Note that the list is not moderated. It is a facility whereby users
393 can communicate for their mutual benefit rather than a question
394 answering facility provided by the software developers.
395
396
397
398 ______________________________________________________________________
399
400 IV. SETTING UP PATHS FOR AIM AND MANAIM:
401
402
403 As with all applications, the use of AIM is greatly assisted by the
404 setting up of appropriate pathnames for the executables and on-line
405 help.
406
407 In the following ${DIR} is the pathname of the directory in which AIM is
408 installed in your file system. For example this might be: /usr/local/aim
409
410
411 A. Executables
412
413 The executable files of the model, AIM tools and the script files are located
414 in the ${DIR}/bin directory.
415
416 If the path name is set to this directory, these programs can be executed
417 from anywhere in the system. The best thing to do is to set the PATH
418 variable of the environment to:
419
420 setenv PATH ${DIR}/bin:$PATH
421
422 This can be done in the .login, .profile or any other appropriate start-up
423 script.
424
425
426 B. Manual Pages:
427
428 The `manaim' script prints AIM manual pages with appropriate name in the
429 Unix man page format.
430
431 If the user wishes to view the man pages through "xman", the
432 environment variable MANPATH needs to be setup to search the
433 [aim]/release/man directory along with the other default man
434 directories.
435
436 Add the directory which contains the AIM manual pages to the MANPATH
437 in your environment, for example by including the following in your
438 start-up script:
439
440 setenv MANPATH ${DIR}/man:${MANPATH}
441
442 or, if MANPATH is an undefined variable:
443
444 setenv MANPATH ${DIR}/man
445
446
447 For compatibility with systems which do not conventionally use a
448 MANPATH, the pathname of the AIM pages directory must be the first
449 pathname in the list.
450
451 The AIM man pages will be appear in the "User Commands" section and
452 the "Local" section of xman.