SPECTRUM1D(l) SPECTRUM1D(l)
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 time-
series 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, 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 / seg-
ment_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 f requency response function
by least squares, such that the noise output is minimized and the coherent outpu t and the noise output are uncorrelated. Option-
ally 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].
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(1gmt), grdfft(1gmt)
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.
1 Jan 2004 SPECTRUM1D(l)