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)
Man(1) output converted with
man2html