FFT

performs FFTs with overlap, windowing, and optional power spectral density

<in1>   Input 1 file name
<out1>  File to receive FFT|PSD of input 1
<nfft>  Desired transform size.  Any factor supported [DEF=1k]
<win>   Name of time window to be computed and applied to the data [DEF=HANN]
<over>  The fraction of <nfft> to overlap blocks [DEF=0]
<navg>  Num of transforms to average in computing each output FFT frame [DEF=1]
<in2>   Input 2 file name [OPTIONAL]
<out2>  File to receive FFT|PSD of <in2> [OPTIONAL]
<cross> File to receive FFT of <in1> * conjugate of FFT of <in2> [OPTIONAL]

This command performs Fast Fourier Transforms on a stream of data.  It replaces
the X-Midas commands FFT, MFFT, SPECTRA, and UBIQUITOUS.

The transform size, <nfft>, is exact, and must be even if the input files are
real.  Performance is best if factorable by 2, 3, 4, and/or 5.  There is no
upper limit on the transform size.

To output magnitude squared of the FFT bins, use the /MAG switch.
To output power spectral density of the FFT bins, use the /PSD switch.
To output MAG or PSD in 20log format, use the /LOG switch.
The /MAG, /LOG, and /PSD switches do NOT affect the <cross> output.

If <win> is one of the special codes listed in the WINDOW;DSP command, it is
computed internally, otherwise it is assumed to be the name of a file
containing a time domain window to be applied to the data.

 THE FOLLOWING IS A TABLE OF ALLOWABLE WINDOWS AND THEIR PARAMETERS.
 Code     Sidelobe   Equivalent     Rolloff   Window Type
          Max (dB)   Bandwidth    (dB/Octave)
 NONE       -13        1.00           6       Rectangle or boxcar
 BARTlett   -27        1.33          12       Bartlett (triangle)
 HANNing    -32        1.50          18       Hanning (cosine bell)
 HAMMing    -43        1.36           6       Hamming (bell on pedestal)
 BLACkman   -58        1.73          18       Blackman
 BH61       -61        1.61           6       Blackman-Harris 3 weight
 BH67       -67        1.71           6       Blackman-Harris 3 weight optimal
 BH74       -74        1.79           6       Blackman-Harris 4 weight
 BH92       -92        2.00           6       Blackman-Harris 4 weight optimal
 (* see WINDOW;DSP for details)

<over> is the fraction of the transform size, <nfft>, to overlap blocks of
data from the input file.  This parameter is > 0 if overlap is desired, 0 if
blocks are  disjoint with no data skipped, and < 0 for disjoint blocks with
data skipped.  Legal range is (-1K,1).

<navg> specifies the number of FFTs to average in computing each output frame.
If -1, all available input data is used to create a single output frame.

The /NEXP=n switch applies exponential averaging to the output frames.  The
weighting factor is 1/N for each new output frame.  This does not affect the
output frame rate as <navg> does.

To remove the DC bias before computing FFTs, apply the /AC switch. This
eliminates the DC spectral sidelobes that can mask certain features of interest.

The /1D switch causes processing to finish after one output frame has been
produced and sets the outputs to be type 1000 files.  This is the behavior of
the X-Midas FFT command if <navg>=1 and <win>=NONE, and the default behavior of
the X-Midas FFT command if <nfft>=-1.  Combining the /1D switch with the
/PSD switch gives the behavior of the X-Midas SPECTRA command and follows the
default behavior if <over>=.5 and <navg>=-1.


The input files may be complex or real.  If supplied, the second input file must
be of the same type as the first input file.  The <cross> output file is only
allowed if a second input file is supplied.  Keywords are only propagated from
the first input file to the <cross> output file.

The /PACK switch controls how the nyquist bin is handled for real data.  The
/PACK=UNPACK switch unpacks it into its own bin which may cause sub-optimal
transfer lengths.  The /PACK=DC switch packs the real part of the nyquist bin
into the always zero imaginary component of the DC bin.  The /PACK=ZERO simply
drops the nyquist bin.  The default is UNPACK for single frame output modes and
ZERO for multi-frame output modes.

The /PARTIAL switch is used to enable or disable the output of an extra frame if
an input file or pipe ends before providing enough data to complete the current
averaged transform (by zero-padding the input).  The default behavior
(/PARTIAL=START) is to force at least one frame of output if the input stops
short before any frames have been output, but partial data received after the
first output frame will be ignored.  /PARTIAL=NONE will discard any partial
frames, and /PARTIAL=ALL will force an extra frame whenever partial input data
is received, whether or not an output frame has already been written.

For example, if the input file is 700 samples and the transform size
is 1K, then default behavior is to output no results; the /PARTIAL switch forces
the input data to be zero-padded to 1K and a single frame to be output.
Similarly, if the input file size is 8,000 samples, the FFT size is 1K and navg
is 4, then the default is to output one frame whereas /PARTIAL will generate two
frames.

Examples:

  1. To perform the SPECTRA command which produces a single output frame
    FFT/PSD/1D infile outfile 1k hann over=0.5 navg=-1

  2. To perform the FFT command which produces a single output frame
    FFT/1D infile outfile 1k hann

  3. To perform the UBIQUITOUS cross spectral function
    FFT in1=file1 in2=file2 cross=xfft nfft=4k

  4. To perform the X-Midas FFT command with nfft=-1 (means all elements); use
     the win=NONE, navg=1 (default), and /1D switch.
    nM> FFT/1D infile outfile nfft=-1 win=none

Switches:
  /1D         Output a type 1000 file. Stops processing input after producing
              one output frame.
  /ABSC       Align input files by abscissa, FALSE to align by index [DEF=TRUE]
  /AC         Take out DC bias before window and FFT
  /DBF        Compute dB Log output using fast exponent overlay method
              (good to +-.5 dB)
  /DP         Do double precision buffers and output if present
  /LOG        Output 20log of power spectral density (does not apply to <cross>)
  /MAG        Compute magnitude squared of FFT
  /NEXP=      Number of exponential averages [DEF=1]
  /PSD        Compute power spectral density of FFTs (scale by 1/dF)
  /PACK=x     Packing mode for real data (UNPACK,DC,ZERO). See /PACK switch
              docs above for more details.
  /PARTIAL=x  Padding option for incomplete input (NONE,START,ALL) [DEF=START]
  /ROTATE=F   Rotate bins of complex FFT to start at -NY/2 [DEF=TRUE]
  /SCALE=f    Specify a scaling factor
  /SMOOTH=n   Exponential smoothing of output N frames deep
  /TL=n       if transfer length is less than <nfft>, input will be zeropadded
              All consume/overlap will be based on the /TL length. [DEF=<nfft>]

See Also:  SPECTRA, nxm.sys.libm.Fft, WINDOW;DSP, nxm.sys.libm.Window