annotate 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.