NAME

edframe - Edit AIM output files.

CONTENTS

Syntax
Description
Options
Examples
Copyright

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

Read an AIM output file which must include a header.Edit the file using the prescription given in the optional arguments to theedframe program, and write the result on the stdout as a new AIM output filewith 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 outputwhich may be graphically displayed as a single image. AIM programs such asgenasa, genepn, gensep, gensai, and genspl all generate multiple frames ofoutput which may be graphically displayed as a sequence of images in a time-varyingcartoon.

AIM output may be generated by:

  genXXX  output=on  file1

which creates a file called file1.XXX. This can be edited to create a newAIM 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-leftcorner of the graphical image of each frame.Editing functions select sub-sequences of frames (when the file consists ofmultiple frames), and partition each of the selected frames using theprescription given as program arguments.The edited output consists of the selected sub-sequence of partitionedsub-matrices. The format of the edited output file corresponds to that of therespective input file, and the header is modified to describe the new framesize.

1. time, freq.

These options prescribe the partition of each frame.The partition output for each frame is a sub-matrix with width, height, andorigin 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 areconverted 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, otherwisethe 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 usingthe ‘samplerate’ option.

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

For most gen programs the time option controls the width of the partition in terms ofcols (or samples along the horizontal axis of the frame image) and the freq optioncontrols the height of the partition in terms of rows(or filterbank channels up the vertical axis of the frame image).The exceptions to this aregenwav (where the vertical axis contains just one wave), and the excitationpatterns genasa, genepn, and gensep in which frequency is measuredalong the horizontal axis of the image, so that it is more appropriate for thefreq 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 measureslag rather than absolute time, but the time option is used to control thisaxis. (Note that time is measured from the left end of the frame image, whichis actually the maximum lag).

2. frame.

When the input consists of a cartoon of multiple framesthen single frames or a range of sequential frames may be selected from theinput 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, otherwisethe 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 greatestinteger multiple of the framestep (‘frstep_epn’ or ‘frstep_aid’) which doesnot 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 forthose channels selected by the ‘freq’ option.This may be used to discover the exact centre-frequency occupied by a givenchannel number within a given filterbank, (as specified bythe 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 outputpartition 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 apreferable display orientation. For example, this enablesa very narrow (eg. single column) time-slice to be plottedhorizontally, so that a time-slice of filterbank output maybe plotted as a spectrum on a horizontal frequency axis.In general the transpose option changes the file format of each framefrom column wise to row wise and vice versa.A row wise format (ie. consecutive channels) may be a more useful form ofoutput from programs such as genbmm or gennap which normally use a columnwise output format.

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 fromthe start of it’s input. (When the option frstep_aid=16ms then this wouldselect 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 fromgennap 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 thenthe 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 tothe 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 genepnoutput 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 theheader 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 thetrigger 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 first20ms (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, andstrip the aim header.The resulting file will consist of consecutive blocks of N samples, whereN = 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 framecould 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

options hdr fbank

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

Permission to use, copy, modify, and distribute this software without feeis hereby granted for research purposes, provided that this copyrightnotice appears in all copies and in all supporting documentation, and thatthe software is not redistributed for any fee (except for a nominalshipping charge). Anyone wanting to incorporate all or part of thissoftware in a commercial product must obtain a license from the MedicalResearch Council.

The MRC makes no representations about the suitability of thissoftware for any purpose. It is provided "as is" without express orimplied warranty.

THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDINGALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALLTHE A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGESOR 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 THISSOFTWARE.