tomwalters@0: .TH SCALE 1 "1 September 1993"
tomwalters@0: 
tomwalters@0: .SH NAME
tomwalters@0: scale \-  Shift and scale a binary stream by given constants or to
tomwalters@0: fit a given range (top - bottom).
tomwalters@0: 
tomwalters@0: .SH SYNTAX 
tomwalters@0: scale [options] [file]
tomwalters@0: 
tomwalters@0: scale -h        -for help with options and their defaults.
tomwalters@0: 
tomwalters@0: .SH DESCRIPTION
tomwalters@0: Shifting and scaling is done for all input x using the formula:
tomwalters@0: .nf
tomwalters@0:       y = ( x - shift ) * scale
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: .SH OPTIONS
tomwalters@0: 
tomwalters@0: 1. top, bottom.
tomwalters@0: 
tomwalters@0: If neither shift nor scale factor are given (ie. both options are "off"),
tomwalters@0: then values are
tomwalters@0: chosen so that the output fits the range specified by `top' and `bottom'.
tomwalters@0: For an input file which ranges between extreme values of `max' and `min', the
tomwalters@0: shift and scale factors to give a required range between `top' and `bottom'
tomwalters@0: are found by simultaneously solving:
tomwalters@0: .nf
tomwalters@0:       top    = ( max - shift ) * scale
tomwalters@0:       bottom = ( min - shift ) * scale
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: If top < bottom then the input is inverted in the resulting range.
tomwalters@0: 
tomwalters@0: 2. normalize.
tomwalters@0: 
tomwalters@0: Values of shift and scale are chosen so that the data is normalized for
tomwalters@0: zero mean and unit standard deviation.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:       shift = mean
tomwalters@0:       scale = 1 / sqrt( variance )
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 3. shift, scale.
tomwalters@0: 
tomwalters@0: In either or both shift and scale are given (ie. are not "off") then
tomwalters@0: the formula is applied directly irrespective of any given top or bottom
tomwalters@0: parameters.
tomwalters@0: If only a shift term is given, then the default scale becomes 1.0.
tomwalters@0: If only a scale factor is given, then the default shift becomes 0.
tomwalters@0: 
tomwalters@0: 4. type.
tomwalters@0: 
tomwalters@0: The input and output data type are selected using "type=<type>", where
tomwalters@0: <type> = { char, short, int, float, double, ASCII }.
tomwalters@0: The ASCII type is interpreted as one number per line.
tomwalters@0: 
tomwalters@0: 5. output.
tomwalters@0: 
tomwalters@0: If no filename arguments are given to the program then one input file is
tomwalters@0: expected on the stdin, otherwise each given filename is input and scaled in
tomwalters@0: turn.
tomwalters@0: If "output=off" then program output overwrites each
tomwalters@0: respective input file. (The respective output for the stdin is the stdout).
tomwalters@0: If the `output' option is given a value (eg. output=filename) then this is
tomwalters@0: used as a filename and all scaled input files are written to this output file.
tomwalters@0: (The default output filename is the stdout).
tomwalters@0: Special value "output=print" suppresses output and prints the shift and
tomwalters@0: scale parameters on the stdout.
tomwalters@0: 
tomwalters@0: 6. range.
tomwalters@0: 
tomwalters@0: The range option specifies the stretch of the wave for scaling and output by:
tomwalters@0: 
tomwalters@0: 	range=a[-b]
tomwalters@0: 
tomwalters@0: The upper limit `b' is optional, and when it is missing then the range
tomwalters@0: is a single sample, otherwise `a' and `b' are inclusive range limits.
tomwalters@0: The strings "min" and "max" are recognised as extreme limits ("min" =
tomwalters@0: start of file, "max" = end of file), otherwise the values of `a' and `b'
tomwalters@0: are sample numbers: 0,1,2,...  Values given with time units (ms or s)
tomwalters@0: are converted to samples using the given samplerate option.
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0: 	range=min-10ms    -the first 10ms of each input file.
tomwalters@0: 	range=128-max     -from the 128'th sample to the end of each file.
tomwalters@0: 	range=8ms-16ms    -between 8ms and 16ms inclusive for each file.
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: .SH "SEE ALSO"
tomwalters@0: options op merge
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: