tomwalters@0: .TH MERGE 1 "15 September 1993" tomwalters@0: tomwalters@0: .SH NAME tomwalters@0: merge \- Merge N streams onto stdout using a given operator. tomwalters@0: tomwalters@0: .SH SYNTAX tomwalters@0: merge [options] file1 file2 ... fileN tomwalters@0: tomwalters@0: .SH DESCRIPTION tomwalters@0: tomwalters@0: Extract items of given data type from file1 to fileN, merge them tomwalters@0: N-wise using the given operation, and write the result on the stdout as tomwalters@0: items of the same type as that selected for input. tomwalters@0: tomwalters@0: .SH OPTIONS tomwalters@0: tomwalters@0: 1. type tomwalters@0: tomwalters@0: The input/output data type. Allowable types are: char, short, int, float, tomwalters@0: double, ASCII (one number per line). tomwalters@0: tomwalters@0: 2. operator tomwalters@0: tomwalters@0: For each vector of items (p1,p2,...,pN) read from file1, file2,...,fileN tomwalters@0: respectively write the result of a merging operation on the stdout. tomwalters@0: The operation is selected using the tomwalters@0: option "operator=". The may be one of the following strings tomwalters@0: (which may be abbreviated provided this is unambiguous): tomwalters@0: tomwalters@0: .nf tomwalters@0: comment tomwalters@0: tomwalters@0: cat concatenate p1,p2,p3,...,pN tomwalters@0: add p1+p2+p3+...+pN tomwalters@0: subtract p1-p2-p3-...-pN tomwalters@0: abs |...||p1-p2|-p3|-...-pN| tomwalters@0: multiply p1*p2*p3*...*pN tomwalters@0: divide p1/p2/p3/.../pN tomwalters@0: max max(p1,p2,p3,...,pN) tomwalters@0: min min(p1,p2,p3,...,pN) tomwalters@0: mean ( p1+p2+p3+...+pN ) / N tomwalters@0: norm sqrt( p1*p1 + p2*p2 + p3*p3 + ... + pN*pN ) tomwalters@0: .fi tomwalters@0: tomwalters@0: tomwalters@0: 3. range tomwalters@0: tomwalters@0: The `range' option sets the start and duration of the merge process. tomwalters@0: Samples in a file are numbered 0,1,2,...,max, and the range option delimits tomwalters@0: input from all input files inclusively. Its arguments are of the form: tomwalters@0: tomwalters@0: .nf tomwalters@0: range=a-b setting start=a and duration=b-a+1 tomwalters@0: range=a setting start=a and duration=1 tomwalters@0: .fi tomwalters@0: tomwalters@0: The arguments can be in time units (ms, s) or samples (no units), and both tomwalters@0: "min" (start of file) and "max" (end of file) are recognised. tomwalters@0: Arguments with time units are converted to samples using the given tomwalters@0: `samplerate' option. tomwalters@0: tomwalters@0: 4. phase tomwalters@0: tomwalters@0: The `phase' option shifts the origin to introduce a phase difference between tomwalters@0: files. The `phase' option takes a comma-separated list of tomwalters@0: arguments which must be the same length as the number of file arguments. tomwalters@0: Each argument can be in time units (ms, s) or samples (no units). tomwalters@0: Arguments with time units are converted to samples using the given tomwalters@0: `samplerate' option. tomwalters@0: tomwalters@0: All files are interpreted as functions sampled with origin at the point in tomwalters@0: the file given by the first argument of the `range' option. tomwalters@0: The functions are assumed to be zero for all samples beyond those specified tomwalters@0: in the files. tomwalters@0: A positive phase advances the origin into the file, tomwalters@0: and this initial lead is skipped before the merging process begins. tomwalters@0: A negative phase retards the origin, and this lag is included at the tomwalters@0: beginning of the merging process. tomwalters@0: If a negative phase in combination with tomwalters@0: the start of the file as set by the `range' option shifts the origin tomwalters@0: outside the specified file, then the difference is padded with zeroes. tomwalters@0: tomwalters@0: 5. weights tomwalters@0: tomwalters@0: The weights option takes as argument a comma-separated list of real numbers tomwalters@0: which must be the same length as the number of file arguments. tomwalters@0: These number are applied as weighting factors to each item prior to the tomwalters@0: merging operation. tomwalters@0: tomwalters@0: 6. scale tomwalters@0: tomwalters@0: Internal processing is in floating point. A scale factor is included to tomwalters@0: avoid overflow when casting output data. tomwalters@0: If 16-bit over or under-flow occurs a warning is printed on the stderr. tomwalters@0: tomwalters@0: tomwalters@0: .SH EXAMPLES tomwalters@0: tomwalters@0: 1. Pairwise concatenation to form coordinate (x,y) pairs from two files. tomwalters@0: tomwalters@0: .nf tomwalters@0: merge op=cat file.x file.y > file.xy tomwalters@0: .fi tomwalters@0: tomwalters@0: 2. Pooling data to form an average. tomwalters@0: tomwalters@0: .nf tomwalters@0: merge op=mean file1 file2 ... fileN > Pool tomwalters@0: .fi tomwalters@0: tomwalters@0: 3. Weighted linear combination of three files using weight vector (1.0,-2.4,0.05). tomwalters@0: tomwalters@0: .nf tomwalters@0: merge op=add weights=1.0,-2.4,0.05 file1 file2 file3 tomwalters@0: .fi tomwalters@0: tomwalters@0: 4. Modulation of one signal file by another. In this example the second file tomwalters@0: is given a 20ms lag with respect to the first, and this lag will be padded tomwalters@0: with zeroes. tomwalters@0: tomwalters@0: .nf tomwalters@0: merge op=mult phase=0,-20ms file1 file2 tomwalters@0: .fi tomwalters@0: tomwalters@0: tomwalters@0: tomwalters@0: .SH "SEE ALSO" tomwalters@0: tomwalters@0: options op 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. tomwalters@0: