1SPECTRUM1D(1)                Generic Mapping Tools               SPECTRUM1D(1)
2
3
4

NAME

6       spectrum1d  -  compute  auto-  [and  cross- ] spectra from one [or two]
7       timeseries.
8

SYNOPSIS

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

DESCRIPTION

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
23       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
30       name_stem.xpower
31              Power spectral density of X(t).  Units of X * X * dt.
32
33       name_stem.ypower
34              Power spectral density of Y(t).  Units of Y * Y * dt.
35
36       name_stem.cpower
37              Power  spectral  density  of the coherent output.  Units same as
38              ypower.
39
40       name_stem.npower
41              Power spectral density of  the  noise  output.   Units  same  as
42              ypower.
43
44       name_stem.gain
45              Gain spectrum, or modulus of the transfer function.  Units of (Y
46              / X).
47
48       name_stem.phase
49              Phase spectrum, or phase of the transfer  function.   Units  are
50              radians.
51
52       name_stem.admit
53              Admittance  spectrum,  or  real  part  of the transfer function.
54              Units of (Y / X).
55
56       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

REQUIRED ARGUMENTS

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
68       -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

OPTIONS

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
89       -D     dt  Set the spacing between samples in the timeseries [Default =
90              1].
91
92       -N     name_stem  Supply the name stem to  be  used  for  output  files
93              [Default = "spectrum"].
94
95       -V     Selects verbose mode, which will send progress reports to stderr
96              [Default runs "silently"].
97
98       -W     Write Wavelength rather than frequency in column 1 of the output
99              file[s] [Default = frequency, (cycles / dt)].
100
101       -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
109       -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
114       -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

ASCII FORMAT PRECISION

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

EXAMPLES

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
137       spectrum1d data.g -S256 -D1.5 -Ndata
138
139       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
144       paste data.t data.g | spectrum1d -S256 -D1.5 -Ndata -C
145

SEE ALSO

147       GMT(1), grdfft(1)
148

REFERENCES

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.
156
157
158
159GMT 4.3.1                         15 May 2008                    SPECTRUM1D(1)
Impressum