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

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

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/man1/gennap.1	Fri May 20 15:19:45 2011 +0100
@@ -0,0 +1,405 @@
+.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.
+