skip to content

Department of Physiology, Development and Neuroscience

 

Manual Page - edframe(1)


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.