annotate man/man1/scale.1 @ 0:5242703e91d3 tip

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

.TH SCALE 1 "1 September 1993"

.SH NAME
scale \-  Shift and scale a binary stream by given constants or to
fit a given range (top - bottom).

.SH SYNTAX 
scale [options] [file]

scale -h        -for help with options and their defaults.

.SH DESCRIPTION
Shifting and scaling is done for all input x using the formula:
.nf
      y = ( x - shift ) * scale
.fi

.SH OPTIONS

1. top, bottom.

If neither shift nor scale factor are given (ie. both options are "off"),
then values are
chosen so that the output fits the range specified by `top' and `bottom'.
For an input file which ranges between extreme values of `max' and `min', the
shift and scale factors to give a required range between `top' and `bottom'
are found by simultaneously solving:
.nf
      top    = ( max - shift ) * scale
      bottom = ( min - shift ) * scale
.fi

If top < bottom then the input is inverted in the resulting range.

2. normalize.

Values of shift and scale are chosen so that the data is normalized for
zero mean and unit standard deviation.

.nf
      shift = mean
      scale = 1 / sqrt( variance )
.fi

3. shift, scale.

In either or both shift and scale are given (ie. are not "off") then
the formula is applied directly irrespective of any given top or bottom
parameters.
If only a shift term is given, then the default scale becomes 1.0.
If only a scale factor is given, then the default shift becomes 0.

4. type.

The input and output data type are selected using "type=<type>", where
<type> = { char, short, int, float, double, ASCII }.
The ASCII type is interpreted as one number per line.

5. output.

If no filename arguments are given to the program then one input file is
expected on the stdin, otherwise each given filename is input and scaled in
turn.
If "output=off" then program output overwrites each
respective input file. (The respective output for the stdin is the stdout).
If the `output' option is given a value (eg. output=filename) then this is
used as a filename and all scaled input files are written to this output file.
(The default output filename is the stdout).
Special value "output=print" suppresses output and prints the shift and
scale parameters on the stdout.

6. range.

The range option specifies the stretch of the wave for scaling and output by:

	range=a[-b]

The upper limit `b' is optional, and when it is missing then the range
is a single sample, otherwise `a' and `b' are inclusive range limits.
The strings "min" and "max" are recognised as extreme limits ("min" =
start of file, "max" = end of file), otherwise the values of `a' and `b'
are sample numbers: 0,1,2,...  Values given with time units (ms or s)
are converted to samples using the given samplerate option.

.nf
	range=min-10ms    -the first 10ms of each input file.
	range=128-max     -from the 128'th sample to the end of each file.
	range=8ms-16ms    -between 8ms and 16ms inclusive for each file.
.fi

.SH "SEE ALSO"
options op merge

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