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

Initial checkin for AIM92 aimR8.2 (last updated May 1997).
author tomwalters
date Fri, 20 May 2011 15:19:45 +0100
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:5242703e91d3
1 .TH EDFRAME 1 "1 September 1993"
2
3 .SH NAME
4 edframe \- Edit AIM output files.
5
6 .SH SYNTAX
7 edframe [[-]frame=a[-b]] [[-]time=a[-b]] [[-]freq=a[-b]] [file]
8
9 .SH DESCRIPTION
10 Read an AIM output file which must include a header.
11 Edit the file using the prescription given in the optional arguments to the
12 edframe program, and write the result on the stdout as a new AIM output file
13 with an appropriately modified header.
14
15 AIM output consists of one or more frames. AIM programs such as genwav, genbmm,
16 gennap, gensgm, gencgm, and gensas all generate a single frame of output
17 which may be graphically displayed as a single image. AIM programs such as
18 genasa, genepn, gensep, gensai, and genspl all generate multiple frames of
19 output which may be graphically displayed as a sequence of images in a time-varying
20 cartoon.
21
22 AIM output may be generated by:
23 .nf
24 genXXX output=on file1
25 .fi
26 which creates a file called file1.XXX. This can be edited to create a new
27 AIM output file by:
28 .nf
29 edframe [options] file1.XXX > file2.XXX
30 .fi
31 Alternatively the AIM output can be edited in situ by:
32 .nf
33 genXXX output=stdout file1 | edframe [options] > file2.XXX
34 .fi
35 Edited output may be displayed using the "useprevious" option, for example:
36 .nf
37 genXXX useprevious=on file2
38 .fi
39 Note that that file2.XXX must have a different base-name to the genXXX input
40 (file1) because genXXX will remove any file1.XXX as a side-effect.
41
42 Each frame is a matrix of numbers consisting of one or more rows and columns.
43 Rows and cols are numbered 0,1,2,..., with the origin (0,0) at the bottom-left
44 corner of the graphical image of each frame.
45 Editing functions select sub-sequences of frames (when the file consists of
46 multiple frames), and partition each of the selected frames using the
47 prescription given as program arguments.
48 The edited output consists of the selected sub-sequence of partitioned
49 sub-matrices. The format of the edited output file corresponds to that of the
50 respective input file, and the header is modified to describe the new frame
51 size.
52
53 .SH OPTIONS
54
55 1. time, freq.
56
57 These options prescribe the partition of each frame.
58 The partition output for each frame is a sub-matrix with width, height, and
59 origin with respect to the frame origin described in terms of rows and columns.
60 The time and freq options are ranges in the respective dimensions which are
61 converted to rows and columns internally. The ranges are given as:
62 .nf
63 time=a[-b]
64 freq=a[-b]
65 .fi
66 The upper limit `b' is optional,
67 and when it is missing then the range is a single value,
68 otherwise `a' and `b' are inclusive range limits.
69 The strings "min" and "max" are recognised as extreme limits, otherwise
70 the values of `a' and `b' are numbers with optional units.
71
72 The units of the time selector are s or ms
73 (seconds and milliseconds respectively), or samples (numbered 0,1,2...)
74 if no units are given. Options with time units are converted to samples internally using
75 the `samplerate' option.
76
77 The units of the freq selector are Hz or kHz
78 or filterbank channel (numbered 0,1,2...) if no units are given.
79 Options with frequency units are converted to channel numbers internally using the
80 filterbank parameters `mincf_afb', `maxcf_afb', `dencf_afb', and `channels_afb'
81 given in the AIM header. The channel number which is "closest" in terms of
82 centre frequency to the given frequency is chosen.
83
84 For most gen programs the time option controls the width of the partition in terms of
85 cols (or samples along the horizontal axis of the frame image) and the freq option
86 controls the height of the partition in terms of rows
87 (or filterbank channels up the vertical axis of the frame image).
88 The exceptions to this are
89 genwav (where the vertical axis contains just one wave), and the excitation
90 patterns genasa, genepn, and gensep in which frequency is measured
91 along the horizontal axis of the image, so that it is more appropriate for the
92 freq option to control the width of the partition in terms of cols
93 (or filterbank channels along the horizontal axis of the frame image).
94
95 In the case of gensai (and genspl) the horizontal (or spiral) axis measures
96 lag rather than absolute time, but the time option is used to control this
97 axis. (Note that time is measured from the left end of the frame image, which
98 is actually the maximum lag).
99
100 2. frame.
101
102 When the input consists of a cartoon of multiple frames
103 then single frames or a range of sequential frames may be selected from the
104 input using:
105 .nf
106 frame=a[-b]
107 .fi
108 The upper limit `b' is optional,
109 and when it is missing then the range is a single frame,
110 otherwise `a' and `b' are inclusive range limits.
111 The strings "min" and "max" are recognised as extreme limits, otherwise
112 the values of `a' and `b' are frame numbers: 0,1,2,...
113
114 The frame selector may also take time units (s, or ms) to specify frames
115 "closest" to the given time, being the frame number which is the greatest
116 integer multiple of the framestep (`frstep_epn' or `frstep_aid') which does
117 not exceed the given time, measured from the start of the input file.
118
119 3. info.
120
121 The option flag:
122 .nf
123 -info
124 .fi
125 causes frame size information to be printed on the stdout.
126 The option flag:
127 .nf
128 info=fbank
129 .fi
130 causes channel centre-frequency information to be printed on the stdout for
131 those channels selected by the `freq' option.
132 This may be used to discover the exact centre-frequency occupied by a given
133 channel number within a given filterbank, (as specified by
134 the filterbank parameters given in the input header).
135
136 4. Header.
137
138 The option flag:
139 .nf
140 Header=off
141 .fi
142 causes the modified header to be suppressed from the output.
143
144 5. Transpose.
145
146 The option flag:
147 .nf
148 Transpose=on
149 .fi
150 causes a matrix transpose (swap rows and columns) of the output
151 partition of each input frame.
152 When a frame partition has a height greater than it's width
153 (ie. cols < rows) then setting Transpose=on may provide a
154 preferable display orientation. For example, this enables
155 a very narrow (eg. single column) time-slice to be plotted
156 horizontally, so that a time-slice of filterbank output may
157 be plotted as a spectrum on a horizontal frequency axis.
158 In general the transpose option changes the file format of each frame
159 from column wise to row wise and vice versa.
160 A row wise format (ie. consecutive channels) may be a more useful form of
161 output from programs such as genbmm or gennap which normally use a column
162 wise output format.
163
164 .SH EXAMPLES
165
166 .nf
167 Selecting particular frames from AIM output.
168 .fi
169
170 1. Plot gennap output and its transpose.
171
172 .nf
173 gennap output=stdout ... | edframe > file1.sai
174 gennap output=stdout ... | edframe Tran=on > file2.sai
175 gensai useprevious=on file1
176 gensai useprevious=on file2
177 .fi
178
179 2. Select and plot frame 2 (ie. the 3rd frame) of gensai output.
180
181 .nf
182 gensai output=stdout ... | edframe frame=2 > file.sai
183 gensai useprevious=on file
184 .fi
185
186 3. Select the frames of gensai output which start between 16ms and 47ms from
187 the start of it's input. (When the option frstep_aid=16ms then this would
188 select the 2nd and 3rd frames).
189
190 .nf
191 gensai output=stdout ... | edframe frame=16ms-47ms > file.sai
192 .fi
193
194 4. Select the 5th to the last frame inclusively of gensai output.
195
196 .nf
197 gensai output=stdout ... | edframe frame=4-max > file.sai
198 .fi
199
200 5. Select the first frame of genepn output and plot the spectrum.
201
202 .nf
203 genepn output=stdout ... | edframe frame=min > file1.epn
204 genepn useprevious=on file1
205 .fi
206
207
208 .nf
209 Editing frames to select particular frequency ranges or channels (ie rows).
210 .fi
211
212 6. Select and plot the channel with centre-frequency closest to 1kHz from
213 gennap output.
214
215 .nf
216 gennap output=stdout ... | edframe freq=1kHz > file.nap
217 gennap useprevious=on file
218 .fi
219
220 7. Select and plot channel 40 then the channel with the lowest and then
221 the highest centre-frequency over all frames of gensai output.
222
223 .nf
224 gensai output=stdout ... | edframe freq=40 > file.sai
225 gensai useprevious=on file
226
227 gensai output=stdout ... | edframe freq=min > file.sai
228 gensai useprevious=on file
229
230 gensai output=stdout ... | edframe freq=max > file.sai
231 gensai useprevious=on file
232 .fi
233
234 8. Select and plot all channels of genbmm output from channel 10 to
235 the channel with centre-frequency closest to 1kHz inclusively.
236
237 .nf
238 genbmm output=stdout ... | edframe freq=10-1000Hz > file.bmm
239 genbmm useprevious=on file
240 .fi
241
242 9. Select and plot a portion of the spectrum from the first frame of genepn
243 output between 1kHz and 2kHz.
244 Note: frequency controls the horizontal (ie cols) dimension for genepn.
245
246 .nf
247 genepn output=stdout ... | edframe frame=min freq=1kHz-2kHz > file.epn
248 genepn useprevious=on file
249 .fi
250
251
252 .nf
253 Editing frames to select particular time slices (ie cols).
254 .fi
255
256 10. Plot column (ie sample) 100 of the 3rd frame of gensai output as a row.
257
258 .nf
259 gensai output=stdout ... | edframe frame=2 time=100 Tran=on > file.sai
260 gensai useprevious=on file
261 .fi
262
263 11. Plot column of sample at 20ms from start of gennap output as a row
264
265 .nf
266 gennap output=stdout ... | edframe time=20ms Tran=on > file.nap
267 gennap useprevious=on file
268 .fi
269
270 12. Edit a wave to select the stretch between 4ms and 16ms, strip the
271 header and plot the resulting wave.
272
273 .nf
274 genwav output=stdout ... | edframe time=4ms-16ms Header=off > file
275 genwav file
276 .fi
277
278
279 .nf
280 Editing frames to select partitions.
281 .fi
282
283 13. Plot a partition of channels 40 to 44 over the last 5ms (ie near the
284 trigger point on the right of the image) of all frames of gensai output.
285 Then plot a partition of frequency range 1kHz to 1.5kHz over the first
286 20ms (on the left of the image) of all frames of gensai output.
287
288 .nf
289 gensai pwidth=35ms nwidth=0 output=stdout ... | edframe time=30ms-max > file.sai
290 gensai useprevious=on file
291 gensai output=stdout ... | edframe freq=1kHz-1.5kHz time=min-20ms > file.sai
292 gensai useprevious=on file
293 .fi
294
295 14. Plot the highest-frequency channel over the last 20ms of gennap output.
296
297 .nf
298 gennap output=stdout ... | edframe freq=max time=20ms-max > file.sai
299 gennap useprevious=on file
300 .fi
301
302
303 .nf
304 Changing the aim output format.
305 .fi
306
307 15. Convert the genbmm output format (column wise) to row wise format, and
308 strip the aim header.
309 The resulting file will consist of consecutive blocks of N samples, where
310 N = length * samplerate.
311 The first block is the output from the lowest centre frequency channel,
312 the second is from the second channel, and so on.
313 By default the whole frame is transposed, but any partition of the frame
314 could be selected using the time and frequency options.
315 (Note: the transpose takes place after the partition has been made).
316
317 .nf
318 genbmm output=stdout ... | edframe Tranpose=on Header=off > file
319 .fi
320
321
322 .SH "SEE ALSO"
323 options hdr fbank
324
325 .SH COPYRIGHT
326 .LP
327 Copyright (c) Applied Psychology Unit, Medical Research Council, 1995
328 .LP
329 Permission to use, copy, modify, and distribute this software without fee
330 is hereby granted for research purposes, provided that this copyright
331 notice appears in all copies and in all supporting documentation, and that
332 the software is not redistributed for any fee (except for a nominal
333 shipping charge). Anyone wanting to incorporate all or part of this
334 software in a commercial product must obtain a license from the Medical
335 Research Council.
336 .LP
337 The MRC makes no representations about the suitability of this
338 software for any purpose. It is provided "as is" without express or
339 implied warranty.
340 .LP
341 THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
342 ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
343 THE A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES
344 OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
345 WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
346 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
347 SOFTWARE.