NAME

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

SYNOPSIS

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

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, 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 frequency
           response function by least squares, such that the noise output is
           minimized and the coherent output and the noise output are
           uncorrelated.

      -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, grdfft

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.