annotate man/man1/gennap.1 @ 0:5242703e91d3 tip

Initial checkin for AIM92 aimR8.2 (last updated May 1997).

.TH GENNAP 1 "8 April 1994"
.LP
.SH NAME
.LP
gennap \- generate neural activity pattern
.LP
.SH SYNOPSIS
.LP
gennap [ option=value | -option ] [ filename ]
.LP
.SH DESCRIPTION
.LP
The gennap module of the AIM software converts an input wave into a
simulated neural activity pattern (NAP), which is AIM's representation
of the pattern of information in the auditory nerve at about the level
of the cochlear nucleus.  Gennap begins by calculating the basilar
membrane motion (BMM) associated with the input wave using the genbmm
module, and then it applies several additional transforms that we know
occur in some form during the neural transduction process.  AIM
provides two alternative methods for generating the NAP, a
two-dimensional adaptive thresholding mechanism (Holdsworth and
Patterson, 1993), and an array of inner haircell simulators based
(Meddis et al., 1990; Giguere and Woodland, 1994).  The adaptive
thresholding mechanism applies rectification, log compression,
adaptation in time, and suppression across frequency; its purpose is
to stabilise the level of the membrane activity with compression and
then sharpen the features that appear in the compressed membrane
motion.  Together, the gammatone filterbank and adaptive thresholding
form a 'functional' cochlea simulation.  The Meddis module applies
level-dependant compression and adaptation that simulate the response
of inner haircells to membrane motion.  The cells are not coupled and
so there is no frequency sharpening in this module.  Together, the
transmission-line filterbank and the Meddis module form a
'physiological' cochlea simulation.
.LP
.SH OPTIONS
.LP
The options for gennap are grouped according to the functions they
control. The adaptive thresholding options are identified by the
common suffix _at; the Meddis module options are identified by the
common suffix _med.  These two groups of options are the subject of
this manual entry, together with two additional options that specify
whether rectification and compression operations are required before
the transduction stage.  There is also an option to specify the choice
of the transduction function.
.LP
.SH  RECTIFICATION AND COMPRESSION
.LP
The adaptive thresholding process begins with rectification and log
compression of the BMM.  It is occasionally useful to have these
functions available separately and so the options 'rectify' and
'compress' are presented separately in the options list before the
neural transduction options.
.RE
.LP
.TP 13
rectify
Rectification switch
.RS
Switch. Default value: off. 
.RE
.RS
.LP
If rectify is on, the BMM is half-wave rectified.
The compression operation also performs half-wave rectification (to
avoid taking logs of negative numbers).  So the rectify option is
really here just to provide for rectified BMM in the absence of
compression.  As a result, the default for option rectify is
off. (Note: Full wave rectification is produced if rectify is set to
2.  This is useful when calculating envelopes with genasa.)
.RE
.LP
.TP 13
compress
Compression switch
.RS
Switch. Default value: on. 
.RE
.RS
.LP
The compressor is strictly logarithmic and so to this point, the
functional cochlea simulation is level independent.  In the auditory
system, the compressor is logarithmic over the lower part of its range
and then it asymptotes to a soft limit. The default for option
compress is on (note that the compressor also performs half-wave
rectification).
.RE
.LP
Important: The default value for option compress is 'on' which assumes
that the transduction module is adaptive thresholding (the default for
the transduction option described below).  If the Meddis transduction
module is selected (transduction=med), compress should be set to 'off'
to obtain the operation described in Giguerre and Woodland
(1994). This can be done on the command line (see EXAMPLES) or in the
appropriate .gen???rc files.
.RE
.LP
.SH NEURAL TRANSDUCTION
.LP
The neural transduction is performed either by two-dimensional
adaptive thresholding or an array of Meddis haircells. The choice is
controlled by the option 'transduction'.
.LP
.TP 13
transduction
The transduction function
.RS
Switch. Default value: at. Choices: at, med, off.
.RE
.LP
If adaptive thresholding is specified (at), the options with suffix
_at below apply; if the Meddis module is specified (med), the options
with suffix _med below apply. If off is specified, no transduction
function is applied.  The default is at.
.RE
.LP
.SS "Two-dimensional adaptive thresholding: _at "
.PP
The adaptive thresholding mechanism is a functional model of neural
encoding. Its purpose is to enhance the contrast of the larger
features that appear in the surface of the BMM and reduce those
aspects of the representation which are just a direct consequence of
the filtering and compression processes (Holdsworth and Patterson,
1993).  The process begins with rectification and compression of the
BMM.  The tail of the envelope of the impulse response of the
gammatone filter is exponential. As a result, logarithmic compression
is used, since this makes the filter decay function linear in NAP
coordinates. Following compression, adaptation is applied in time and
suppression is applied across frequency.
.LP
Briefly, an adaptive threshold value is maintained for each channel
and updated at the sampling rate. The new value is the largest of a)
the previous value reduced by a fast-acting temporal decay factor
(t1recovery_at), b) the previous value reduced by a longer-term
temporal decay factor (t2recovery_at), c) the adapted level in the
channel immediately above, reduced by a frequency spread factor
(frecovery_at), d) the adapted level in the channel immediately below,
reduced by the same frequency spread factor, or e) a floor level that
precludes the mechanism listening to its own internal noise
(reclimit_at).  The mechanism produces output whenever the input
exceeds the adaptive threshold, and the output level is the difference
between the input and the adaptive threshold. The adaptation and
suppression are coupled, and they jointly sharpen features like vowel
formants which appear smeared in compressed BMM.
.LP
.TP 13
trise_at
Threshold rise rate 
.RS
Default value: 1000. 
.RE
.RS
.LP
Upward Adaptation: This option specifies the rate at which the
adaptive threshold will rise in response to a rise in signal
level. The default value, 1000, means that the adaptive threshold
responds very quickly to increases in the input wave; essentially, it
follows the envelope of any rise in signal amplitude.
.RE
.LP
Downward Adaptation: Following the cessation of sound, or a rapid drop
in input level, temporal adaptation occurs in two stages as determined
by t1recovery_at, t2recovery_at and propt2t1_at: If the default values
are used, the mechanism initially adapts at a rate slightly slower
than the decay rate of the gammatone filter in the given channel, and
this represses much of the ringing of the impulse response of the
filter.  Later the adaptation switches to a slower rate more in line
with data on auditory forward masking.  The option propt2t1_at
determines the point at which the initial fast rate of decay gives way
to the slower limiting decay rate.
.RE
.LP
.TP 13
t1recovery_at
The initial rate of threshold recovery relative to filter decay rate 
.RS
Default value: 0.6. 
.RE
.RS
.LP
This option determines the initial rate of decay of the adaptive
threshold relative to the rate of decay of the auditory filter,
provided propt2t1_at is less than unity.  Values of t1recovery_at less
than unity cause the adaptive threshold to decay more slowly than the
auditory filter and thereby to remove the filter response from the
representation when it is the sole reason for BMM activity.  The rate
of decay is linear with respect to the log-compressed BMM, so it is
like an exponential decay with respect to the BMM.
.RE
.LP
.TP 13
t2recovery_at
The secondary threshold recovery rate
.RS
Default value: 0.2. 
.RE
.RS
.LP
This option determines the limiting rate of decay of the adaptive
threshold when the sound ceases provided propt2t1_at is less than
unity.  The default value causes the adaptive threshold to decay more
slowly than the initial rate as observed in auditory forward masking.
Note, however, that the system to this point is level independent,
whereas auditory forward masking is level dependent.
.RE
.LP
.TP 13
propt2t1_at
The point at which t1recovery_at gives way to t2_recovery_at
.RS
Default value: 0.5. 
.RE
.RS
.LP
This option determines the point at which the initial fast rate of
decay (t1recovery_at) gives way to the slower limiting decay rate
(t2recovery_at).  The nomanclature assumes that propt2t1_at is a value
less than unity.  Otherwise the the roles of the initial and limiting
decays are reversed.
.RE
.LP
.TP 13
frecovery_at
Recovery rate across frequency 
.RS
Default value: 20. 
.RE
.RS
.LP
This parameter specifies the rate at which a threshold value in one channel 
propagates to influence threshold in neighbouring channels. 
.RE
.LP
.TP 13
reclimit_at
Limitation on recovery level 
.RS
Default units: mB. Default value: 500 mB. (mB=milliBells)
.RE
.RS
.LP
In order to prevent the mechanism from encountering system noise, 
or alternately, to reduce sensitivity to stimulus noise, there is a 
limit placed on the recovery that the adaptive threshold can achieve. 
The limit, reclimit_at, is the limit of the sensitivity of the system. 
.RE
.LP
.TP 13
gain_at
Output gain 
.RS
Default units: scalar. Default value: 1. 
.RE
.LP
.SS "Meddis haircell model: _med "
.PP
The purpose of the Meddis module is to simulate neural transduction of
BMM as performed by the inner haircells of the cochlea.  There is one
haircell simulation unit for each output channel of the filterbank.
The haircell equations (Meddis et al., 1990) are solved using the wave
digital filter algorithm described in Giguere and Woodland (1994). The
characteristics of the haircell are controlled by options: fiber_med,
thresh_med, and gain_med.
.LP
.TP 13
fiber_med
The spontaneous-rate of the simulated fiber
.RS
Default value: medium. Choices: medium, high.
.RE
.RS
.LP
If medium is specified, a medium spontaneous-rate haircell fiber is
simulated. If high is specified, a high spontaneous-rate 
fiber is simulated. The properties of these two types of fibers 
are listed in Table II in Meddis et al. (1990).
The default value is medium.
.RE
.LP
.TP 13
thresh_med
The threshold shift of the fiber
.RS
Default Units: dB. Default value: 0.   
.RE
.RS
.LP
This option shifts the entire rate-intensity function of the haircell
fiber horizontally to a higher or lower level, to accomodate changes
in the scaling of the input wave.  A positive (negative) value
increases (decreases) the rate- and saturation-thresholds of the fiber
by that amount.  This operation does not change the dynamic range, the
spontaneous and saturation rates, or the adaptation time constants or
synchronization index of the fiber.
.RE
.LP
.TP 13
gain_med
Output gain 
.RS
Default units: scalar. Default value: 1. 
.RE
.RS
.LP
Note: There is an internal gain of 20.0 within the software of
the Meddis haircell model itself. The total gain is therefore
20.0 times the value for gain_med.
.RE
.LP
.SH REFERENCES
.LP
.RE
.TP 4
Giguere, C. and Woodland, P.C. (1994).  A computational model of
the auditory periphery for speech and hearing research. I. Ascending
path. J.Acoust. Soc. Am. 95: 331-342.
.RE
.LP
.TP 4
Holdsworth, J. (1990). Two-Dimensional adaptive thresholding.
Annex 4 of AAM-HAP Report 1, APU contract Report.
.RE
.LP
.TP 4
Holdsworth, J. and Patterson, R.D. (1993). "Analysis of waveforms,"
UK Patent GB 2234078B.
.LP
.TP 4
Meddis, R., Hewitt, M. and Shackleton, T. (1990). Implementation
details of a computational model of the inner-haircell/auditory-nerve
synapse. J.Acoust. Soc. Am. 87: 1813-1816.
.RE
.LP
.SH EXAMPLES
.LP
The following command generates the neural activity pattern using the
gammatone auditory filterbank (the default) and the adaptive
thresholding (the default) for an input file named cegc:
.RE
.LP
example% gennap cegc
.RE
.LP
The following command generates the neural activity pattern using the
gammatone filterbank (the default) and Meddis haircell
transduction for input cegc:
.RE
.LP
example% gennap compress=off transduction=meddis cegc
.RE
.LP
The following command generates the neural activity pattern using the
transmission line filterbank and Meddis haircell transduction for cegc:
.RE
.LP
example% gennap filter=tlf compress=off transduction=meddis cegc
.LP
.SH FILES
.LP
.TP 13
 .gennaprc 
The options file for gennap.
.LP
.SH SEE ALSO
.LP
genepn, gencgm, genbmm
.LP
.SH COPYRIGHT
.LP
Copyright (c) Applied Psychology Unit, Medical Research Council, 1995
.LP
Permission to use, copy, modify, and distribute this software without fee 
is hereby granted for research purposes, provided that this copyright 
notice appears in all copies and in all supporting documentation, and that 
the software is not redistributed for any fee (except for a nominal 
shipping charge). Anyone wanting to incorporate all or part of this 
software in a commercial product must obtain a license from the Medical 
Research Council.
.LP
The MRC makes no representations about the suitability of this 
software for any purpose.  It is provided "as is" without express or 
implied warranty.
.LP
THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL 
THE A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES 
OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, 
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS 
SOFTWARE.
.LP
.SH ACKNOWLEDGEMENTS
.LP
The AIM software was developed for Unix workstations by John
Holdsworth and Mike Allerhand of the MRC APU, under the direction of
Roy Patterson. The physiological version of AIM was developed by
Christian Giguere. The options handler is by Paul Manson. The revised
SAI module is by Jay Datta. Michael Akeroyd extended the postscript
facilites and developed the xreview routine for auditory image
cartoons.
.LP
The project was supported by the MRC and grants from the U.K. Defense
Research Agency, Farnborough (Research Contract 2239); the EEC Esprit
BR Porgramme, Project ACTS (3207); and the U.K. Hearing Research Trust.