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]  con-
       taining  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 fre-
       quency 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-spec-
              tral error bars are larger and more complicated, being  a  func-
              tion also of the coherency.


OPTIONS

       -C     Read  the  first  two  columns  of input as samples of two time-
              series, 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  mini-
              mized and the coherent outpu t and the noise output are uncorre-
              lated.  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].

       -O     Selects  Overlay  plot mode [Default initializes a new plot sys-
              tem].


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  fea-
       tures  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(l), grdfft(l)


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 estima-
       tion of power spectra: a method based on  time  averaging  over  short,
       modified periodograms, IEEE Transactions on Audio and Electroacoustics,
       Vol AU-15, No 2.



GMT3.4.6                          1 Jan 2005                     SPECTRUM1D(l)

Man(1) output converted with man2html