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)

Man(1) output converted with man2html