1SPECTRUM1D(1) Generic Mapping Tools SPECTRUM1D(1)
2
6 spectrum1d - compute auto- [and cross- ] spectra from one [or two]
7 timeseries.
8
10 spectrum1d [ x[y]file ] -Ssegment_size] [ -C[xycnpago] ] [ -Ddt ] [
11 -Nname_stem ] [ -V ] [ -W ] [ -b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [
12 -f[i|o]colinfo ]
13
15 spectrum1d reads X [and Y] values from the first [and second] columns
16 on standard input [or x[y]file]. These values are treated as time‐
17 series X(t) [Y(t)] sampled at equal intervals spaced dt units apart.
18 There may be any number of lines of input. spectrum1d will create
19 file[s] containing auto- [and cross- ] spectral density estimates by
20 Welch's method of ensemble averaging of multiple overlapped windows,
21 using standard error estimates from Bendat and Piersol.
22 The output files have 3 columns: f or w, p, and e. f or w is the fre‐
24 quency or wavelength, p is the spectral density estimate, and e is the
25 one standard deviation error bar size. These files are named based on
26 name_stem. If the -C option is used, up to eight files are created;
27 otherwise only one (xpower) is written. The files (which are ASCII
28 unless -bo is set) are as follows:
29 name_stem.xpower
31 Power spectral density of X(t). Units of X * X * dt.
32 name_stem.ypower
34 Power spectral density of Y(t). Units of Y * Y * dt.
35 name_stem.cpower
37 Power spectral density of the coherent output. Units same as
38 ypower.
39 name_stem.npower
41 Power spectral density of the noise output. Units same as
42 ypower.
43 name_stem.gain
45 Gain spectrum, or modulus of the transfer function. Units of (Y
46 / X).
47 name_stem.phase
49 Phase spectrum, or phase of the transfer function. Units are
50 radians.
51 name_stem.admit
53 Admittance spectrum, or real part of the transfer function.
54 Units of (Y / X).
55 name_stem.coh
57 (Squared) coherency spectrum, or linear correlation coefficient
58 as a function of frequency. Dimensionless number in [0, 1].
59 The Signal-to-Noise-Ratio (SNR) is coh / (1 - coh). SNR = 1
60 when coh = 0.5.
61
63 x[y]file
64 ASCII (or binary, see -bi) file holding X(t) [Y(t)] samples in
65 the first 1 [or 2] columns. If no file is specified, spectrum1d
66 will read from standard input.
67 -S segment_size is a radix-2 number of samples per window for
69 ensemble averaging. The smallest frequency estimated is
70 1.0/(segment_size * dt), while the largest is 1.0/(2 * dt). One
71 standard error in power spectral density is approximately 1.0 /
72 sqrt(n_data / segment_size), so if segment_size = 256, you need
73 25,600 data to get a one standard error bar of 10%. Cross-spec‐
74 tral error bars are larger and more complicated, being a func‐
75 tion also of the coherency.
76
78 -C Read the first two columns of input as samples of two time‐
79 series, X(t) and Y(t). Consider Y(t) to be the output and X(t)
80 the input in a linear system with noise. Estimate the optimum
81 frequency response function by least squares, such that the
82 noise output is minimized and the coherent output and the noise
83 output are uncorrelated. Optionally specify up to 8 letters
84 from the set { x y c n p a g o } in any order to create only
85 those output files instead of the default [all]. x = xpower, y
86 = ypower, c = cpower, n = npower, p = phase, a = admit, g =
87 gain, o = coh.
88 -D dt Set the spacing between samples in the timeseries [Default =
90 1].
91 -N name_stem Supply the name stem to be used for output files
93 [Default = "spectrum"].
94 -V Selects verbose mode, which will send progress reports to stderr
96 [Default runs "silently"].
97 -W Write Wavelength rather than frequency in column 1 of the output
99 file[s] [Default = frequency, (cycles / dt)].
100 -bi Selects binary input. Append s for single precision [Default is
102 d (double)]. Uppercase S or D will force byte-swapping.
103 Optionally, append ncol, the number of columns in your binary
104 input file if it exceeds the columns needed by the program. Or
105 append c if the input file is netCDF. Optionally, append
106 var1/var2/... to specify the variables to be read. [Default is
107 2 input columns].
108 -bo Selects binary output. Append s for single precision [Default
110 is d (double)]. Uppercase S or D will force byte-swapping.
111 Optionally, append ncol, the number of desired columns in your
112 binary output file. [Default is 2 output columns].
113 -f Special formatting of input and/or output columns (time or geo‐
115 graphical data). Specify i or o to make this apply only to
116 input or output [Default applies to both]. Give one or more
117 columns (or column ranges) separated by commas. Append T (abso‐
118 lute calendar time), t (relative time in chosen TIME_UNIT since
119 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
120 to each column or column range item. Shorthand -f[i|o]g means
121 -f[i|o]0x,1y (geographic coordinates).
122
124 The ASCII output formats of numerical data are controlled by parameters
125 in your .gmtdefaults4 file. Longitude and latitude are formatted
126 according to OUTPUT_DEGREE_FORMAT, whereas other values are formatted
127 according to D_FORMAT. Be aware that the format in effect can lead to
128 loss of precision in the output, which can lead to various problems
129 downstream. If you find the output is not written with enough preci‐
130 sion, consider switching to binary output (-bo if available) or specify
131 more decimals using the D_FORMAT setting.
132
134 Suppose data.g is gravity data in mGal, sampled every 1.5 km. To write
135 its power spectrum, in mGal**2-km, to the file data.xpower, use
136 spectrum1d data.g -S256 -D1.5 -Ndata
138 Suppose in addition to data.g you have data.t, which is topography in
140 meters sampled at the same points as data.g. To estimate various fea‐
141 tures of the transfer function, considering data.t as input and data.g
142 as output, use
143 paste data.t data.g | spectrum1d -S256 -D1.5 -Ndata -C
145
147 GMT(1), grdfft(1)
148
150 Bendat, J. S., and A. G. Piersol, 1986, Random Data, 2nd revised ed.,
151 John Wiley & Sons.
152 Welch, P. D., 1967, The use of Fast Fourier Transform for the estima‐
153 tion of power spectra: a method based on time averaging over short,
154 modified periodograms, IEEE Transactions on Audio and Electroacoustics,
155 Vol AU-15, No 2.
156GMT 4.5.6 10 Mar 2011 SPECTRUM1D(1)