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

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

.TH EDFRAME 1 "1 September 1993"

.SH NAME
 edframe \-  Edit AIM output files.

.SH SYNTAX 
edframe  [[-]frame=a[-b]]  [[-]time=a[-b]]  [[-]freq=a[-b]]  [file]

.SH DESCRIPTION
Read an AIM output file which must include a header.
Edit the file using the prescription given in the optional arguments to the
edframe program, and write the result on the stdout as a new AIM output file
with an appropriately modified header.

AIM output consists of one or more frames. AIM programs such as genwav, genbmm,
gennap, gensgm, gencgm, and gensas all generate a single frame of output
which may be graphically displayed as a single image. AIM programs such as
genasa, genepn, gensep, gensai, and genspl all generate multiple frames of
output which may be graphically displayed as a sequence of images in a time-varying
cartoon.

AIM output may be generated by:
.nf
  genXXX  output=on  file1
.fi
which creates a file called file1.XXX. This can be edited to create a new
AIM output file by:
.nf
  edframe  [options]  file1.XXX  >  file2.XXX
.fi
Alternatively the AIM output can be edited in situ by:
.nf
  genXXX  output=stdout  file1  |  edframe  [options]  >  file2.XXX
.fi
Edited output may be displayed using the "useprevious" option, for example:
.nf
  genXXX  useprevious=on file2
.fi
Note that that file2.XXX must have a different base-name to the genXXX input
(file1) because genXXX will remove any file1.XXX as a side-effect.

Each frame is a matrix of numbers consisting of one or more rows and columns.
Rows and cols are numbered 0,1,2,..., with the origin (0,0) at the bottom-left
corner of the graphical image of each frame.
Editing functions select sub-sequences of frames (when the file consists of
multiple frames), and partition each of the selected frames using the
prescription given as program arguments.
The edited output consists of the selected sub-sequence of partitioned
sub-matrices. The format of the edited output file corresponds to that of the
respective input file, and the header is modified to describe the new frame
size.

.SH OPTIONS

1. time, freq.

These options prescribe the partition of each frame.
The partition output for each frame is a sub-matrix with width, height, and
origin with respect to the frame origin described in terms of rows and columns.
The time and freq options are ranges in the respective dimensions which are
converted to rows and columns internally. The ranges are given as:
.nf
  time=a[-b]
  freq=a[-b]
.fi
The upper limit `b' is optional,
and when it is missing then the range is a single value,
otherwise `a' and `b' are inclusive range limits.
The strings "min" and "max" are recognised as extreme limits, otherwise
the values of `a' and `b' are numbers with optional units.

The units of the time selector are s or ms
(seconds and milliseconds respectively), or samples (numbered 0,1,2...)
if no units are given. Options with time units are converted to samples internally using
the `samplerate' option.

The units of the freq selector are Hz or kHz
or filterbank channel (numbered 0,1,2...) if no units are given.
Options with frequency units are converted to channel numbers internally using the
filterbank parameters `mincf_afb', `maxcf_afb', `dencf_afb', and `channels_afb'
given in the AIM header. The channel number which is "closest" in terms of
centre frequency to the given frequency is chosen.

For most gen programs the time option controls the width of the partition in terms of
cols (or samples along the horizontal axis of the frame image) and the freq option
controls the height of the partition in terms of rows
(or filterbank channels up the vertical axis of the frame image).
The exceptions to this are
genwav (where the vertical axis contains just one wave), and the excitation
patterns genasa, genepn, and gensep in which frequency is measured
along the horizontal axis of the image, so that it is more appropriate for the
freq option to control the width of the partition in terms of cols
(or filterbank channels along the horizontal axis of the frame image).

In the case of gensai (and genspl) the horizontal (or spiral) axis measures
lag rather than absolute time, but the time option is used to control this
axis. (Note that time is measured from the left end of the frame image, which
is actually the maximum lag).

2. frame.

When the input consists of a cartoon of multiple frames
then single frames or a range of sequential frames may be selected from the
input using:
.nf
  frame=a[-b]
.fi
The upper limit `b' is optional,
and when it is missing then the range is a single frame,
otherwise `a' and `b' are inclusive range limits.
The strings "min" and "max" are recognised as extreme limits, otherwise
the values of `a' and `b' are frame numbers: 0,1,2,...

The frame selector may also take time units (s, or ms) to specify frames
"closest" to the given time, being the frame number which is the greatest
integer multiple of the framestep (`frstep_epn' or `frstep_aid') which does
not exceed the given time, measured from the start of the input file.

3. info.

The option flag:
.nf
  -info
.fi
causes frame size information to be printed on the stdout.
The option flag:
.nf
  info=fbank
.fi
causes channel centre-frequency information to be printed on the stdout for
those channels selected by the `freq' option.
This may be used to discover the exact centre-frequency occupied by a given
channel number within a given filterbank, (as specified by
the filterbank parameters given in the input header).

4. Header.

The option flag:
.nf
  Header=off
.fi
causes the modified header to be suppressed from the output.

5. Transpose.

The option flag:
.nf
  Transpose=on
.fi
causes a matrix transpose (swap rows and columns) of the output
partition of each input frame.
When a frame partition has a height greater than it's width
(ie. cols < rows) then setting Transpose=on may provide a
preferable display orientation. For example, this enables
a very narrow (eg. single column) time-slice to be plotted
horizontally, so that a time-slice of filterbank output may
be plotted as a spectrum on a horizontal frequency axis.
In general the transpose option changes the file format of each frame
from column wise to row wise and vice versa.
A row wise format (ie. consecutive channels) may be a more useful form of
output from programs such as genbmm or gennap which normally use a column
wise output format.

.SH EXAMPLES

.nf
Selecting particular frames from AIM output.
.fi

1. Plot gennap output and its transpose.

.nf
  gennap output=stdout ... | edframe         >  file1.sai
  gennap output=stdout ... | edframe Tran=on >  file2.sai
  gensai useprevious=on file1
  gensai useprevious=on file2
.fi

2. Select and plot frame 2 (ie. the 3rd frame) of gensai output.

.nf
  gensai output=stdout ... | edframe frame=2  >  file.sai
  gensai useprevious=on file
.fi

3. Select the frames of gensai output which start between 16ms and 47ms from
the start of it's input. (When the option frstep_aid=16ms then this would
select the 2nd and 3rd frames).

.nf
  gensai output=stdout ... | edframe frame=16ms-47ms >  file.sai
.fi

4. Select the 5th to the last frame inclusively of gensai output.

.nf
  gensai output=stdout ... | edframe frame=4-max  >  file.sai
.fi

5. Select the first frame of genepn output and plot the spectrum.

.nf
  genepn output=stdout ... | edframe frame=min > file1.epn
  genepn useprevious=on file1
.fi


.nf
Editing frames to select particular frequency ranges or channels (ie rows).
.fi

6. Select and plot the channel with centre-frequency closest to 1kHz from
gennap output.

.nf
  gennap output=stdout ... | edframe freq=1kHz  >  file.nap
  gennap useprevious=on file
.fi

7. Select and plot channel 40 then the channel with the lowest and then
the highest centre-frequency over all frames of gensai output.

.nf
  gensai output=stdout ... | edframe freq=40  >  file.sai
  gensai useprevious=on file

  gensai output=stdout ... | edframe freq=min  >  file.sai
  gensai useprevious=on file

  gensai output=stdout ... | edframe freq=max  >  file.sai
  gensai useprevious=on file
.fi

8. Select and plot all channels of genbmm output from channel 10 to
the channel with centre-frequency closest to 1kHz inclusively.

.nf
  genbmm output=stdout ... | edframe freq=10-1000Hz  >  file.bmm
  genbmm useprevious=on file
.fi

9. Select and plot a portion of the spectrum from the first frame of genepn
output between 1kHz and 2kHz.
Note: frequency controls the horizontal (ie cols) dimension for genepn.

.nf
  genepn output=stdout ... | edframe frame=min freq=1kHz-2kHz > file.epn
  genepn useprevious=on file
.fi


.nf
Editing frames to select particular time slices (ie cols).
.fi

10. Plot column (ie sample) 100 of the 3rd frame of gensai output as a row.

.nf
  gensai output=stdout ... | edframe frame=2 time=100 Tran=on >  file.sai
  gensai useprevious=on file
.fi

11. Plot column of sample at 20ms from start of gennap output as a row

.nf
  gennap output=stdout ... | edframe time=20ms Tran=on >  file.nap
  gennap useprevious=on file
.fi

12. Edit a wave to select the stretch between 4ms and 16ms, strip the
header and plot the resulting wave.

.nf
  genwav output=stdout ... | edframe time=4ms-16ms Header=off > file
  genwav file
.fi


.nf
Editing frames to select partitions.
.fi

13. Plot a partition of channels 40 to 44 over the last 5ms (ie near the
trigger point on the right of the image) of all frames of gensai output.
Then plot a partition of frequency range 1kHz to 1.5kHz over the first
20ms (on the left of the image) of all frames of gensai output.

.nf
  gensai pwidth=35ms nwidth=0 output=stdout ... | edframe time=30ms-max > file.sai
  gensai useprevious=on file
  gensai output=stdout ... | edframe freq=1kHz-1.5kHz time=min-20ms > file.sai
  gensai useprevious=on file
.fi

14. Plot the highest-frequency channel over the last 20ms of gennap output.

.nf
  gennap output=stdout ... | edframe freq=max time=20ms-max > file.sai
  gennap useprevious=on file
.fi


.nf
Changing the aim output format.
.fi

15. Convert the genbmm output format (column wise) to row wise format, and
strip the aim header.
The resulting file will consist of consecutive blocks of N samples, where
N = length * samplerate.
The first block is the output from the lowest centre frequency channel,
the second is from the second channel, and so on.
By default the whole frame is transposed, but any partition of the frame
could be selected using the time and frequency options.
(Note: the transpose takes place after the partition has been made).

.nf
  genbmm output=stdout ... | edframe Tranpose=on Header=off > file
.fi


.SH "SEE ALSO"
options hdr fbank

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