SPECTRUM1D(1) Generic Mapping Tools SPECTRUM1D(1)NAMEspectrum1d - compute auto- [and cross- ] spectra from one [or two]
timeseries.
SYNOPSISspectrum1d [ x[y]file ] -Ssegment_size] [ -C[xycnpago] ] [ -Ddt ] [
-Nname_stem ] [ -V ] [ -W ] [ -b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [
-f[i|o]colinfo ]
DESCRIPTIONspectrum1d 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 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
d (double)]. Uppercase S or D will force byte-swapping.
Optionally, append ncol, the number of columns in your binary
input file if it exceeds the columns needed by the program. Or
append c if the input file is netCDF. Optionally, append
var1/var2/... to specify the variables to be read. [Default is
2 input columns].
-bo Selects binary output. Append s for single precision [Default
is d (double)]. Uppercase S or D will force byte-swapping.
Optionally, append ncol, the number of desired columns in your
binary output file. [Default is 2 output columns].
-f Special formatting of input and/or output columns (time or geo‐
graphical data). Specify i or o to make this apply only to
input or output [Default applies to both]. Give one or more
columns (or column ranges) separated by commas. Append T (abso‐
lute calendar time), t (relative time in chosen TIME_UNIT since
TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
to each column or column range item. Shorthand -f[i|o]g means
-f[i|o]0x,1y (geographic coordinates).
ASCII FORMAT PRECISION
The ASCII output formats of numerical data are controlled by parameters
in your .gmtdefaults4 file. Longitude and latitude are formatted
according to OUTPUT_DEGREE_FORMAT, whereas other values are formatted
according to D_FORMAT. Be aware that the format in effect can lead to
loss of precision in the output, which can lead to various problems
downstream. If you find the output is not written with enough preci‐
sion, consider switching to binary output (-bo if available) or specify
more decimals using the D_FORMAT setting.
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 -S 256 -D 1.5 -N data
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-S 256 -D 1.5 -N data -C
SEE ALSOGMT(1), grdfft(1)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.
GMT 4.5.14 1 Nov 2015 SPECTRUM1D(1)
