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

Initial checkin for AIM92 aimR8.2 (last updated May 1997).

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