## 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] ] [ -f[i|o]col-
           info ]

## 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
                  frequency  response  function  by  least  squares, such that the
                  noise output is minimized and the coherent output 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].  Append n for the  number  of  columns  in  the  binary
                  file(s).

           -f     Special  formatting  of  input  and output columns (time or geo-
                  graphical data) Specify i(nput) or  o(utput)  [Default  is  both
                  input  and output].  Give one or more columns (or column ranges)
                  separated by commas.  Append T (Absolute calendar time), t (time
                  relative  to  chosen TIME_EPOCH), x (longitude), y (latitude), g
                  (geographic coordinate), or f (floating point) to each column or
                  column range item.

## 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, use

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

           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.

    GMT4.0                            1 Oct 2004                     SPECTRUM1D(l)