

 
Manual Reference Pages  SPECTRUM1D (1)
NAME
spectrum1d  compute auto [and cross ] spectra from one [or two] timeseries.
CONTENTS
Synopsis
Description
Required Arguments
Options
Ascii Format Precision
Examples
References
SYNOPSIS
spectrum1d [ x[y]file ] Ssegment_size]
[ C[xycnpago] ] [ Ddt ]
[ Nname_stem ] [ V ] [ W ]
[ b[io][sSdD[ncol]c[var1/...]] ] [ f[io]colinfo ]
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] 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 SignaltoNoiseRatio (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 radix2 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%. Crossspectral 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 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 byteswapping.
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 byteswapping.
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 geographical 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 (absolute 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[io]g means f[io]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 precision, 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**2km,
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 features 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 ALSO
GMT(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 estimation of power spectra: a method
based on time averaging over short, modified periodograms, IEEE Transactions on Audio and Electroacoustics,
Vol AU15, No 2.
GMT 4.5.14  SPECTRUM1D (1)  1 Nov 2015 
Visit the GSP FreeBSD Man Page Interface. Output converted with manServer 1.07. 