tomwalters@0: .TH EDFRAME 1 "1 September 1993"
tomwalters@0: 
tomwalters@0: .SH NAME
tomwalters@0:  edframe \-  Edit AIM output files.
tomwalters@0: 
tomwalters@0: .SH SYNTAX 
tomwalters@0: edframe  [[-]frame=a[-b]]  [[-]time=a[-b]]  [[-]freq=a[-b]]  [file]
tomwalters@0: 
tomwalters@0: .SH DESCRIPTION
tomwalters@0: Read an AIM output file which must include a header.
tomwalters@0: Edit the file using the prescription given in the optional arguments to the
tomwalters@0: edframe program, and write the result on the stdout as a new AIM output file
tomwalters@0: with an appropriately modified header.
tomwalters@0: 
tomwalters@0: AIM output consists of one or more frames. AIM programs such as genwav, genbmm,
tomwalters@0: gennap, gensgm, gencgm, and gensas all generate a single frame of output
tomwalters@0: which may be graphically displayed as a single image. AIM programs such as
tomwalters@0: genasa, genepn, gensep, gensai, and genspl all generate multiple frames of
tomwalters@0: output which may be graphically displayed as a sequence of images in a time-varying
tomwalters@0: cartoon.
tomwalters@0: 
tomwalters@0: AIM output may be generated by:
tomwalters@0: .nf
tomwalters@0:   genXXX  output=on  file1
tomwalters@0: .fi
tomwalters@0: which creates a file called file1.XXX. This can be edited to create a new
tomwalters@0: AIM output file by:
tomwalters@0: .nf
tomwalters@0:   edframe  [options]  file1.XXX  >  file2.XXX
tomwalters@0: .fi
tomwalters@0: Alternatively the AIM output can be edited in situ by:
tomwalters@0: .nf
tomwalters@0:   genXXX  output=stdout  file1  |  edframe  [options]  >  file2.XXX
tomwalters@0: .fi
tomwalters@0: Edited output may be displayed using the "useprevious" option, for example:
tomwalters@0: .nf
tomwalters@0:   genXXX  useprevious=on file2
tomwalters@0: .fi
tomwalters@0: Note that that file2.XXX must have a different base-name to the genXXX input
tomwalters@0: (file1) because genXXX will remove any file1.XXX as a side-effect.
tomwalters@0: 
tomwalters@0: Each frame is a matrix of numbers consisting of one or more rows and columns.
tomwalters@0: Rows and cols are numbered 0,1,2,..., with the origin (0,0) at the bottom-left
tomwalters@0: corner of the graphical image of each frame.
tomwalters@0: Editing functions select sub-sequences of frames (when the file consists of
tomwalters@0: multiple frames), and partition each of the selected frames using the
tomwalters@0: prescription given as program arguments.
tomwalters@0: The edited output consists of the selected sub-sequence of partitioned
tomwalters@0: sub-matrices. The format of the edited output file corresponds to that of the
tomwalters@0: respective input file, and the header is modified to describe the new frame
tomwalters@0: size.
tomwalters@0: 
tomwalters@0: .SH OPTIONS
tomwalters@0: 
tomwalters@0: 1. time, freq.
tomwalters@0: 
tomwalters@0: These options prescribe the partition of each frame.
tomwalters@0: The partition output for each frame is a sub-matrix with width, height, and
tomwalters@0: origin with respect to the frame origin described in terms of rows and columns.
tomwalters@0: The time and freq options are ranges in the respective dimensions which are
tomwalters@0: converted to rows and columns internally. The ranges are given as:
tomwalters@0: .nf
tomwalters@0:   time=a[-b]
tomwalters@0:   freq=a[-b]
tomwalters@0: .fi
tomwalters@0: The upper limit `b' is optional,
tomwalters@0: and when it is missing then the range is a single value,
tomwalters@0: otherwise `a' and `b' are inclusive range limits.
tomwalters@0: The strings "min" and "max" are recognised as extreme limits, otherwise
tomwalters@0: the values of `a' and `b' are numbers with optional units.
tomwalters@0: 
tomwalters@0: The units of the time selector are s or ms
tomwalters@0: (seconds and milliseconds respectively), or samples (numbered 0,1,2...)
tomwalters@0: if no units are given. Options with time units are converted to samples internally using
tomwalters@0: the `samplerate' option.
tomwalters@0: 
tomwalters@0: The units of the freq selector are Hz or kHz
tomwalters@0: or filterbank channel (numbered 0,1,2...) if no units are given.
tomwalters@0: Options with frequency units are converted to channel numbers internally using the
tomwalters@0: filterbank parameters `mincf_afb', `maxcf_afb', `dencf_afb', and `channels_afb'
tomwalters@0: given in the AIM header. The channel number which is "closest" in terms of
tomwalters@0: centre frequency to the given frequency is chosen.
tomwalters@0: 
tomwalters@0: For most gen programs the time option controls the width of the partition in terms of
tomwalters@0: cols (or samples along the horizontal axis of the frame image) and the freq option
tomwalters@0: controls the height of the partition in terms of rows
tomwalters@0: (or filterbank channels up the vertical axis of the frame image).
tomwalters@0: The exceptions to this are
tomwalters@0: genwav (where the vertical axis contains just one wave), and the excitation
tomwalters@0: patterns genasa, genepn, and gensep in which frequency is measured
tomwalters@0: along the horizontal axis of the image, so that it is more appropriate for the
tomwalters@0: freq option to control the width of the partition in terms of cols
tomwalters@0: (or filterbank channels along the horizontal axis of the frame image).
tomwalters@0: 
tomwalters@0: In the case of gensai (and genspl) the horizontal (or spiral) axis measures
tomwalters@0: lag rather than absolute time, but the time option is used to control this
tomwalters@0: axis. (Note that time is measured from the left end of the frame image, which
tomwalters@0: is actually the maximum lag).
tomwalters@0: 
tomwalters@0: 2. frame.
tomwalters@0: 
tomwalters@0: When the input consists of a cartoon of multiple frames
tomwalters@0: then single frames or a range of sequential frames may be selected from the
tomwalters@0: input using:
tomwalters@0: .nf
tomwalters@0:   frame=a[-b]
tomwalters@0: .fi
tomwalters@0: The upper limit `b' is optional,
tomwalters@0: and when it is missing then the range is a single frame,
tomwalters@0: otherwise `a' and `b' are inclusive range limits.
tomwalters@0: The strings "min" and "max" are recognised as extreme limits, otherwise
tomwalters@0: the values of `a' and `b' are frame numbers: 0,1,2,...
tomwalters@0: 
tomwalters@0: The frame selector may also take time units (s, or ms) to specify frames
tomwalters@0: "closest" to the given time, being the frame number which is the greatest
tomwalters@0: integer multiple of the framestep (`frstep_epn' or `frstep_aid') which does
tomwalters@0: not exceed the given time, measured from the start of the input file.
tomwalters@0: 
tomwalters@0: 3. info.
tomwalters@0: 
tomwalters@0: The option flag:
tomwalters@0: .nf
tomwalters@0:   -info
tomwalters@0: .fi
tomwalters@0: causes frame size information to be printed on the stdout.
tomwalters@0: The option flag:
tomwalters@0: .nf
tomwalters@0:   info=fbank
tomwalters@0: .fi
tomwalters@0: causes channel centre-frequency information to be printed on the stdout for
tomwalters@0: those channels selected by the `freq' option.
tomwalters@0: This may be used to discover the exact centre-frequency occupied by a given
tomwalters@0: channel number within a given filterbank, (as specified by
tomwalters@0: the filterbank parameters given in the input header).
tomwalters@0: 
tomwalters@0: 4. Header.
tomwalters@0: 
tomwalters@0: The option flag:
tomwalters@0: .nf
tomwalters@0:   Header=off
tomwalters@0: .fi
tomwalters@0: causes the modified header to be suppressed from the output.
tomwalters@0: 
tomwalters@0: 5. Transpose.
tomwalters@0: 
tomwalters@0: The option flag:
tomwalters@0: .nf
tomwalters@0:   Transpose=on
tomwalters@0: .fi
tomwalters@0: causes a matrix transpose (swap rows and columns) of the output
tomwalters@0: partition of each input frame.
tomwalters@0: When a frame partition has a height greater than it's width
tomwalters@0: (ie. cols < rows) then setting Transpose=on may provide a
tomwalters@0: preferable display orientation. For example, this enables
tomwalters@0: a very narrow (eg. single column) time-slice to be plotted
tomwalters@0: horizontally, so that a time-slice of filterbank output may
tomwalters@0: be plotted as a spectrum on a horizontal frequency axis.
tomwalters@0: In general the transpose option changes the file format of each frame
tomwalters@0: from column wise to row wise and vice versa.
tomwalters@0: A row wise format (ie. consecutive channels) may be a more useful form of
tomwalters@0: output from programs such as genbmm or gennap which normally use a column
tomwalters@0: wise output format.
tomwalters@0: 
tomwalters@0: .SH EXAMPLES
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0: Selecting particular frames from AIM output.
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 1. Plot gennap output and its transpose.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   gennap output=stdout ... | edframe         >  file1.sai
tomwalters@0:   gennap output=stdout ... | edframe Tran=on >  file2.sai
tomwalters@0:   gensai useprevious=on file1
tomwalters@0:   gensai useprevious=on file2
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 2. Select and plot frame 2 (ie. the 3rd frame) of gensai output.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   gensai output=stdout ... | edframe frame=2  >  file.sai
tomwalters@0:   gensai useprevious=on file
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 3. Select the frames of gensai output which start between 16ms and 47ms from
tomwalters@0: the start of it's input. (When the option frstep_aid=16ms then this would
tomwalters@0: select the 2nd and 3rd frames).
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   gensai output=stdout ... | edframe frame=16ms-47ms >  file.sai
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 4. Select the 5th to the last frame inclusively of gensai output.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   gensai output=stdout ... | edframe frame=4-max  >  file.sai
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 5. Select the first frame of genepn output and plot the spectrum.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   genepn output=stdout ... | edframe frame=min > file1.epn
tomwalters@0:   genepn useprevious=on file1
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0: Editing frames to select particular frequency ranges or channels (ie rows).
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 6. Select and plot the channel with centre-frequency closest to 1kHz from
tomwalters@0: gennap output.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   gennap output=stdout ... | edframe freq=1kHz  >  file.nap
tomwalters@0:   gennap useprevious=on file
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 7. Select and plot channel 40 then the channel with the lowest and then
tomwalters@0: the highest centre-frequency over all frames of gensai output.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   gensai output=stdout ... | edframe freq=40  >  file.sai
tomwalters@0:   gensai useprevious=on file
tomwalters@0: 
tomwalters@0:   gensai output=stdout ... | edframe freq=min  >  file.sai
tomwalters@0:   gensai useprevious=on file
tomwalters@0: 
tomwalters@0:   gensai output=stdout ... | edframe freq=max  >  file.sai
tomwalters@0:   gensai useprevious=on file
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 8. Select and plot all channels of genbmm output from channel 10 to
tomwalters@0: the channel with centre-frequency closest to 1kHz inclusively.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   genbmm output=stdout ... | edframe freq=10-1000Hz  >  file.bmm
tomwalters@0:   genbmm useprevious=on file
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 9. Select and plot a portion of the spectrum from the first frame of genepn
tomwalters@0: output between 1kHz and 2kHz.
tomwalters@0: Note: frequency controls the horizontal (ie cols) dimension for genepn.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   genepn output=stdout ... | edframe frame=min freq=1kHz-2kHz > file.epn
tomwalters@0:   genepn useprevious=on file
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0: Editing frames to select particular time slices (ie cols).
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 10. Plot column (ie sample) 100 of the 3rd frame of gensai output as a row.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   gensai output=stdout ... | edframe frame=2 time=100 Tran=on >  file.sai
tomwalters@0:   gensai useprevious=on file
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 11. Plot column of sample at 20ms from start of gennap output as a row
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   gennap output=stdout ... | edframe time=20ms Tran=on >  file.nap
tomwalters@0:   gennap useprevious=on file
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 12. Edit a wave to select the stretch between 4ms and 16ms, strip the
tomwalters@0: header and plot the resulting wave.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   genwav output=stdout ... | edframe time=4ms-16ms Header=off > file
tomwalters@0:   genwav file
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0: Editing frames to select partitions.
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 13. Plot a partition of channels 40 to 44 over the last 5ms (ie near the
tomwalters@0: trigger point on the right of the image) of all frames of gensai output.
tomwalters@0: Then plot a partition of frequency range 1kHz to 1.5kHz over the first
tomwalters@0: 20ms (on the left of the image) of all frames of gensai output.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   gensai pwidth=35ms nwidth=0 output=stdout ... | edframe time=30ms-max > file.sai
tomwalters@0:   gensai useprevious=on file
tomwalters@0:   gensai output=stdout ... | edframe freq=1kHz-1.5kHz time=min-20ms > file.sai
tomwalters@0:   gensai useprevious=on file
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 14. Plot the highest-frequency channel over the last 20ms of gennap output.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   gennap output=stdout ... | edframe freq=max time=20ms-max > file.sai
tomwalters@0:   gennap useprevious=on file
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0: Changing the aim output format.
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 15. Convert the genbmm output format (column wise) to row wise format, and
tomwalters@0: strip the aim header.
tomwalters@0: The resulting file will consist of consecutive blocks of N samples, where
tomwalters@0: N = length * samplerate.
tomwalters@0: The first block is the output from the lowest centre frequency channel,
tomwalters@0: the second is from the second channel, and so on.
tomwalters@0: By default the whole frame is transposed, but any partition of the frame
tomwalters@0: could be selected using the time and frequency options.
tomwalters@0: (Note: the transpose takes place after the partition has been made).
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:   genbmm output=stdout ... | edframe Tranpose=on Header=off > file
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 
tomwalters@0: .SH "SEE ALSO"
tomwalters@0: options hdr fbank
tomwalters@0: 
tomwalters@0: .SH COPYRIGHT
tomwalters@0: .LP
tomwalters@0: Copyright (c) Applied Psychology Unit, Medical Research Council, 1995
tomwalters@0: .LP
tomwalters@0: Permission to use, copy, modify, and distribute this software without fee 
tomwalters@0: is hereby granted for research purposes, provided that this copyright 
tomwalters@0: notice appears in all copies and in all supporting documentation, and that 
tomwalters@0: the software is not redistributed for any fee (except for a nominal 
tomwalters@0: shipping charge). Anyone wanting to incorporate all or part of this 
tomwalters@0: software in a commercial product must obtain a license from the Medical 
tomwalters@0: Research Council.
tomwalters@0: .LP
tomwalters@0: The MRC makes no representations about the suitability of this 
tomwalters@0: software for any purpose.  It is provided "as is" without express or 
tomwalters@0: implied warranty.
tomwalters@0: .LP
tomwalters@0: THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
tomwalters@0: ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL 
tomwalters@0: THE A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES 
tomwalters@0: OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 
tomwalters@0: WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, 
tomwalters@0: ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS 
tomwalters@0: SOFTWARE.