## 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)