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

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

.TH GENEPN 1 "11 May 1995" 
.LP 
.SH NAME 
.LP 
genepn \- generate excitation pattern 
.LP 
.SH SYNOPSIS 
.LP 
genepn [ option=value | -option ] [ filename ] 
.LP 
.SH DESCRIPTION 
.LP
Genepn converts the input wave into a simulated neural activity
pattern (NAP) and summarises the NAP as a sequence of excitation
patterns (EPNs). The operation takes place in three stages: spectral
analysis, neural encoding, and temporal integration. In the spectral
analysis stage, the input wave is converted into an array of filtered
waves, one for each channel of a gammatone auditory filterbank. The
surface of the array of filtered waves is AIM's representation of
basilar membrane motion (BMM) as a function of time (see genbmm). In
the neural encoding stage, compression, adaptation and, optionally,
suppression, are used to convert each wave from the filterbank into a
simulation of the aggregate neural response to that wave. The array of
responses is AIM's simulation of the neural activity pattern (NAP) in
the auditory nerve at about the level of the cochlear nucleus (see
gennap). Finally, the NAP is converted into a sequence of excitation
patterns (EPNs) by calculating the envelope of the NAP and extracting
spectral slices from the envelope every 'frstep_epn' ms. The envelope
is calculated continuously, by lowpass filtering the individual
channels of the NAP as they flow from the cochlea simulation.
.LP 
The excitation pattern produced by genepn is intended to simulate the
spectral representation of a sound as it occurs in the peripheral
auditory system after neural transduction at about the level of the
cochlea nucleus.  As a result, the frequency resolution of the
analysis varies with the center frequency of the channel, and the
distribution of channels across frequency is chosen to match that in
the auditory system. (For details, see the manual entry for genbmm.)
The excitaion pattern is a plot of the activity in each channel as a
function of the centre frequency of the auditory filter that defines
the channel. In AIM, the suffix 'epn' is used to distinguish this
spectral representation from the other spectral representations
provided by the software ('asa' auditory spectral analysis, 'sgm'
auditory spectrogram, and 'cgm' cochleogram).
.LP 
The NAP generated by genepn is the same as that produced by gennap.
The primary differences are in the display defaults and the inclusion
of the Leaky Integration used to construct the excitation patterns
from the NAP.  As a result, this manual entry is restricted to
describing the option values that differ from those in gennap and the
additional options required to control the Leaky Integration.
.LP
.SH DISPLAY DEFAULTS
.LP
The default values for three of the display options are reset to
produce a spectral format rather than a landscape.  Specifically,
display=excitation, bottom=0 and top=2500. The number of channels is
increased to 128 to ensure reasonable frequency resolution in the
excitation pattern display. 
.LP
.SH LEAKY INTEGRATION
.LP
.TP 13
stages_idt
Number of stages of lowpass filtering
.RS
Default unit: scalar. Default value: 2
.RE
.TP 13
tup_idt
The time constant for each filter stage
.RS
Default unit: ms. Default value: 8 ms.
.RE
.LP
The Equivalent Rectandular Duration (ERD) of a two stage lowpass
filter is about 1.6 times the time constant of each stage, or
12.8 ms in the current case.
.TP 13
frstep_epn
The time between successive spectral frames
.RS
Default unit: ms. Default value: 10 ms.
.RE
.LP
With a frstep_epn of 10 ms, genepn will produce
spectral frames at a rate of 100 per second. 
.LP
.TP 13
downsample
The time between successive spectral frames. 
.RS
Default unit: ms. Default value: 10 ms.
.RE
.LP
Downsample is simply another name for frstep_epn, provided to
facilitate a different mode of thinking about time-series data.
.RE
.LP
.LP
.SH FILES
.LP
.TP 13
.genepnrc 
The options file for genepn.
.LP
.SH SEE ALSO
.LP
genasa, gennap, genbmm, gensgm, gencgm
.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.