NAME

     stft - routine to provide a time - frequency  representation
     of  input  seismic data using a short time Fourier Transform
     technique.  This  approach  allows  the  input  data  to  be
     resolved  in  terms of not just frequency and amplitude, but
     frequency, amplitude, time and space.

SYNOPSIS

     stft [ -Nntap ] [ -Ootap ] [  -Tempttap  ]  [  -nsnstr  ]  [
     -nenetr  ]  [  -rsnrst ] [ -renred ] [ -snrst ] [ -enred ] [
     -nwinsamp ] [ -TV ] [ -R ] [ -V ] [ -?  or  -h or  -help ]

DESCRIPTION

     stft computes a time-frequency spectrum for each input trace
     using  a short time Fourier transform algorithm. The program
     output  is  collections  of  sub-band  traces.   Two  output
     arrangements are possible:

     Sub-band Records [the default]

     will see N output sub-band records for  each  input  record.
     The magnitude of N is a function of the command line parame-
     ter -nwin, [N = nwin  /  2].   Each  sub-band  will  contain
     information  from  a  different  range  of frequencies.  The
     sub-bandwidth is a function of  the  input  dataset  Nyquist
     frequency.  There will be N equally spaced sub-bands between
     zero Hertz and Nyquist. The sub-bands contain  band  limited
     data arranged such that the sample values for the first half
     of the trace are amplitude and the last half  phase  [as  in
     output  from  USP  routines  fft2da or fftxy].  You will see
     upon viewing a record transformed in this  manner  that  the
     amplitude  information  for  a given sub-band is distributed
     temporally and spatially within the record. This allows  the
     processer  to  realize  where, in time and space, induvidual
     frequency components are located.  This  temporal  localiza-
     tion  of  frequency  information  is not available through a
     classical FFT of trace data.

     Time - Frequency Spectra [-TV option]

     There will be as many output  records  as  there  are  input
     traces.   Each  output  record  will  contain  N traces [the
     number of sub-bands from above].  The  first  half  of  each
     output  trace  contains  the  amplitude spectra and the last
     half the phase.

      stft  allows for localization in time, space and  frequency
     of  unwanted [or wanted] signal and the removal [or enhance-
     ment] of that signal within the data.  The ability to effect
     a given frequency band over a small range of time and offset
     makes possible filtering that would not be possible using  a
     full  trace  FFT  or  even  full  record  FK transform.  For
     example, in marine data  the  water  column  is  alive  with
     energy  bouncing  between  the seafloor and sea surface at a
     very diagnostic period.  Since  energy  travelling  in  this
     medium  is not suffering the frequency dependant attenuation
     that affects energy travelling through the earth, it  has  a
     diagnositic  signature  on  a  time-frequency display of the
     data.  There will be a couple of sub-bands where an event of
     water  column  periodicity  is  seen to exist over the whole
     band showing little attenuation with time.   These  arrivals
     can  be removed from the data by treating only the sub-bands
     affected thus vastly attenuating water column reverbation at
     little cost to the underlying data.

     stft gets both its data and its parameters from command line
     arguments.   These  arguments specify the input, output, the
     temporary disk buffer [if needed], the temporal  FFT  window
     length  in  samples, the start and end traces, start and end
     records, start and end sample times, the  inverse  transform
     flag, the time - frequency output flag and verbose printout,
     if desired.

  Command line arguments
     -N ntap  [default: stdin]
          Enter the input data set name or file immediately after
          typing -N unless the input is from a pipe in which case
          the -N entry must be omitted. This  input  file  should
          include the complete path name if the file resides in a
          different directory.  Example -N/b/vsp/dummy tells  the
          program to look for file 'dummy' in directory '/b/vsp'.

     -O otap  [default: stdout]
          Enter the output data  set  name  or  file  immediately
          after  typing -O. This output file is not required when
          piping the output to another process. The  output  data
          set also requires the full path name (see above).

     -Temp ttap  [default: not used]
          Enter the temporary disk buffer data set name  or  file
          immediately  after  typing -Temp. This buffer file will
          only be used if there is not enough local  RAM  to  run
          the program.

     -s ist  [default: 0]
          Enter the start time in the temporal units of the  data
          [milliseconds  for  millisecond  data, microseconds for
          microsecond data].

     -e iend  [default: all]
          Enter the end time in the temporal units  of  the  data
          [milliseconds  for  millisecond  data, microseconds for
          microsecond data].

     -ns ns  [default: 1]
          Enter the start trace number.

     -ne ne  [default: all]
          Enter the end trace number.

     -rs irs  [default: 1]
          Enter start record number.

     -re ire  [default: all]
          Enter end record number.

     -nwin nwin  [default: 32]
          Enter then number of samples in the  fft  window.   The
          default,  and  for  now the minimum, is 32 samples.  If
          you want to make this bigger do  so  in  increments  of
          two.  (i.e. 64, 128 etc).  The number of frequency sub-
          bands will be the number of samples in this window / 2.

     -R   Enter the command line  argument  '-R'  to  perform  an
          inverse short time Fourier transform on the input data.

     -TF  Enter the command line argument '-TF' to output a  time
          - frequency spectrum for each input trace.  The default
          is to output [nwin/2] sub-band records for  each  input
          record.

     -V   Enter the command line argument '-V' to get  additional
          printout.

     -? or -h or -help
          Enter the command line argument '-?'  or  -h  or  -help
          to  get  online help.  The program terminates after the
          help screen is printed.

DISCUSSION

     The following trace - wise algorithm is implimented in  stft
     .  An  nwin  sample window is positioned at the start of the
     trace.  The samples falling within this window are  weighted
     using   a  Gaussian  operator.   The  weighted  samples  are
     transformed using an FFT.  The resulting amplitude and phase
     spectra  are output for the central time only of the window.
     The  window  is  moved  down  one  sample  and  the  process
     repeated.   The inverse is acquired by retrieving the ampli-
     tude and phase spectra at  a  given  sample,  performing  an
     inverse FFT, and outputing the central amplitude at the out-
     put time.

BUGS

     Although not technically a bug, the following is  viewed  as
     such  by  some.   This routine, although a trace independant
     operation, has been implemented as a two dimensional process
     in  it's  default  mode.  For this reason it is expecting an
     input dataset with more than 1 trace  per  record.   If  you
     wish  to  run  this  routine  on  stacked data do one of two
     things. Firstly you could use program  utop  and reverse the
     line  header entries for NumRec and NumTrc so that the stack
     looks like a single record of  many  traces.   Alternatively
     you  could  use the routine  rwindow  to subdivide the input
     stack into a selection of padded records.

SEE ALSO

     stft_mute(1)

AUTHOR

     [A. Vassiliou: Socon  422-3749,  USP  implimentation  P.G.A.
     Garossino Socon 422-3932].

COPYRIGHT

     copyright 2001, Amoco Production Company
               All Rights Reserved
          an affiliate of BP America Inc.