NAME

       spectrum1d - compute auto- [and cross- ] spectra from one [or two] timeseries.

SYNOPSIS

       spectrum1d [ x[y]file ] -Ssegment_size] [ -C[xycnpago] ] [ -Ddt ] [ -Nname_stem ] [ -V ] [
       -W ] [ -bi[s][n] ] [ -bo[s][n] ]

DESCRIPTION

       spectrum1d reads X [and Y] values from the first [and second] columns  on  standard  input
       [or  x[y]file].  These  values  are  treated  as  timeseries  X(t) [Y(t)] sampled at equal
       intervals spaced dt units apart. There may be any number of  lines  of  input.  spectrum1d
       will  create  file[s] containing auto- [and cross- ] spectral density estimates by Welch's
       method of ensemble ' averaging  of  multiple  overlapped  windows,  using  standard  error
       estimates from Bendat and Piersol.

       The  output files have 3 columns: f or w, p, and e. f or w is the frequency or wavelength,
       p is the spectral density estimate, and e is the one standard deviation  error  bar  size.
       These  files are named based on name_stem. If the -C option is used, up to eight files are
       created; otherwise only one (xpower) is written. The files (which are ASCII unless -bo  is
       set) are as follows:

       name_stem.xpower
              Power spectral density of X(t). Units of X * X * dt.

       name_stem.ypower
              Power spectral density of Y(t). Units of Y * Y * dt.

       name_stem.cpower
              Power spectral density of the coherent output. Units same as ypower.

       name_stem.npower
              Power spectral density of the noise output. Units same as ypower.

       name_stem.gain
              Gain spectrum, or modulus of the transfer function. Units of (Y / X).

       name_stem.phase
              Phase spectrum, or phase of the transfer function. Units are radians.

       name_stem.admit
              Admittance spectrum, or real part of the transfer function. Units of (Y / X).

       name_stem.coh
              (Squared)  coherency  spectrum,  or linear correlation coefficient as a function of
              frequency.  Dimensionless number in [0, 1]. The Signal-to-Noise-Ratio (SNR) is  coh
              / (1 - coh). SNR = 1 when coh = 0.5.

REQUIRED ARGUMENTS

       x[y]file
              ASCII  (or  binary, see -bi) file holding X(t) [Y(t)] samples in the first 1 [or 2]
              columns. If no file is specified, spectrum1d will read from standard input.

       -S     segment_size is a radix-2 number of samples per window for ensemble averaging.  The
              smallest  frequency  estimated  is  1.0/(segment_size  *  dt), while the largest is
              1.0/(2 * dt). One standard error in power spectral density is approximately  1.0  /
              sqrt(n_data  / segment_size), so if segment_size = 256, you need 25,600 data to get
              a one standard error bar of 10%. Cross-spectral error  bars  are  larger  and  more
              complicated, being a function also of the coherency.

OPTIONS

       -C     Read the first two columns of input as samples of two timeseries, X(t) and Y(t).
                Consider  Y(t) to be the output and X(t) the input in a linear system with noise.
              Estimate the optimum f requency response function by least squares, such  that  the
              noise  output  is  minimized  and  the  coherent  outpu  t and the noise output are
              uncorrelated.  Optionally specify up to 8 letters from the set { x y c n p a g o  }
              in  any  order to create only those output files instead of the default [all].  x =
              xpower, y = ypower, c = cpower, n = npower, p = phase, a = admit, g  =  gain,  o  =
              coh.

       -D     dt Set the spacing between samples in the timeseries [Default = 1].

       -N     name_stem Supply the name stem to be used for output files [Default = "spectrum"].

       -V     Selects  verbose  mode,  which  will  send progress reports to stderr [Default runs
              "silently"].

       -W     Write Wavelength rather than frequency in column 1 of the output file[s] [Default =
              frequency, (cycles / dt)].

       -bi    Selects  binary input. Append s for single precision [Default is double].  Append n
              for the number of columns in the binary file(s).  [Default is 2 input columns].

       -bo    Selects binary output. Append s for single precision [Default is double].

EXAMPLES

       Suppose data.g is gravity data in mGal, sampled every 1.5 km. To write its power spectrum,
       in mGal**2-km, to the file data.xpower, try

       spectrum1d data.g -S256 -D1.5 -Ndata

       Suppose  in  addition  to data.g you have data.t, which is topography in meters sampled at
       the same points as  data.g.  To  estimate  various  features  of  the  transfer  function,
       considering data.t as input and data.g as output, try

       paste data.t data.g | spectrum1d -S256 -D1.5 -Ndata -C

SEE ALSO

       gmt(1gmt), grdfft(1gmt)

REFERENCES

       Bendat, J. S., and A. G. Piersol, 1986, Random Data, 2nd revised ed., John Wiley & Sons.
       Welch,  P.  D.,  1967,  "The  use  of  Fast  Fourier Transform for the estimation of power
       spectra:  a method based on  time  averaging  over  short,  modified  periodograms",  IEEE
       Transactions on Audio and Electroacoustics, Vol AU-15, No 2.

                                            1 Jan 2004                              SPECTRUM1D(l)