skip to primary navigationskip to content
 

edframe


Manual Reference Pages  - EDFRAME (1)

NAME

edframe - Edit AIM output files.

CONTENTS

Syntax
Description
Options
Examples
Copyright

SYNTAX

edframe [[-]frame=a[-b]] [[-]time=a[-b]] [[-]freq=a[-b]] [file]

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:

  genXXX  output=on  file1

which creates a file called file1.XXX. This can be edited to create a new AIM output file by:
  edframe  [options]  file1.XXX  >  file2.XXX

Alternatively the AIM output can be edited in situ by:
  genXXX  output=stdout  file1  |  edframe  [options]  >  file2.XXX

Edited output may be displayed using the "useprevious" option, for example:
  genXXX  useprevious=on file2

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.

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:

  time=a[-b]
  freq=a[-b]

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:

  frame=a[-b]

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:

  -info

causes frame size information to be printed on the stdout. The option flag:
  info=fbank

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:

  Header=off

causes the modified header to be suppressed from the output.

5. Transpose.

The option flag:

  Transpose=on

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.

EXAMPLES

Selecting particular frames from AIM output.

1. Plot gennap output and its transpose.

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

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

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

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

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

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

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

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

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

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

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

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

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

  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

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

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

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.

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

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

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

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

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

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

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

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

Editing frames to select partitions.

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.

  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

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

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

Changing the aim output format.

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

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

SEE ALSO

options hdr fbank

COPYRIGHT

Copyright (c) Applied Psychology Unit, Medical Research Council, 1995

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.

The MRC makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

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.


SunOS 5.6 EDFRAME (1) 1 September 1993
Generated by manServer 1.07 from /cbu/cnbh/aim/release/man/man1/edframe.1 using man macros.