1GRDFFT(1)                             GMT                            GRDFFT(1)
2
3
4

NAME

6       grdfft - Do mathematical operations on grids in the wavenumber (or fre‐
7       quency) domain
8

SYNOPSIS

10       grdfft ingrid [ ingrid2  ]  [   -Goutfile|table  ]  [   -Aazimuth  ]  [
11       -Czlevel   ]   [    -D[scale|g]   ]   [    -E[r|x|y][+w[k]][+n]   ]   [
12       -F[r|x|y]params ] [  -I[scale|g]  ]  [   -Nparams  ]  [   -Sscale  ]  [
13       -V[level] ] [ -fg ]
14
15       Note:  No  space  is allowed between the option flag and the associated
16       arguments.
17

DESCRIPTION

19       grdfft will take the 2-D forward Fast Fourier Transform and perform one
20       or  more  mathematical operations in the frequency domain before trans‐
21       forming back to the space domain. An option is provided  to  scale  the
22       data  before  writing  the new values to an output file. The horizontal
23       dimensions of the grid are assumed to be in meters. Geographical  grids
24       may be used by specifying the -fg option that scales degrees to meters.
25       If you have grids with dimensions in  km,  you  could  change  this  to
26       meters using grdedit or scale the output with grdmath.
27

REQUIRED ARGUMENTS

29       ingrid 2-D  binary  grid file to be operated on. (See GRID FILE FORMATS
30              below). For cross-spectral operations, also give the second grid
31              file ingrd2.
32
33       -Goutfile
34              Specify the name of the output grid file or the 1-D spectrum ta‐
35              ble (see -E). (See GRID FILE FORMATS below).
36

OPTIONAL ARGUMENTS

38       -Aazimuth
39              Take the directional derivative in the  azimuth  direction  mea‐
40              sured in degrees CW from north.
41
42       -Czlevel
43              Upward  (for  zlevel  > 0) or downward (for zlevel < 0) continue
44              the field zlevel meters.
45
46       -D[scale|g]
47              Differentiate the field, i.e., take d(field)/dz. This is equiva‐
48              lent  to multiplying by kr in the frequency domain (kr is radial
49              wave number). Append  a  scale  to  multiply  by  (kr  *  scale)
50              instead.  Alternatively, append g to indicate that your data are
51              geoid heights in meters and output should be  gravity  anomalies
52              in mGal.  [Default is no scale].
53
54       -E[r|x|y][+w[k]][+n]
55              Estimate  power spectrum in the radial direction [r]. Place x or
56              y immediately after -E to compute the spectrum in  the  x  or  y
57              direction instead. No grid file is created. If one grid is given
58              then f (i.e., frequency or wave number), power[f], and  1  stan‐
59              dard  deviation  in  power[f]  are written to the file set by -G
60              [stdout]. If two grids are given we write f  and  8  quantities:
61              Xpower[f],   Ypower[f],   coherent   power[f],  noise  power[f],
62              phase[f], admittance[f], gain[f], coherency[f].   Each  quantity
63              is  followed by its own 1-std dev error estimate, hence the out‐
64              put is 17 columns wide.  Give +w to write wavelength instead  of
65              frequency, and if your grid is geographic you may further append
66              k to scale wavelengths from meter [Default] to km.  Finally, the
67              spectrum  is  obtained  by  summing  over  several  frequencies.
68              Append +n to normalize so that the mean spectral values per fre‐
69              quency are reported instead.
70
71       -F[r|x|y]params
72              Filter  the  data. Place x or y immediately after -F to filter x
73              or y direction only; default is isotropic [r].  Choose between a
74              cosine-tapered band-pass, a Gaussian band-pass filter, or a But‐
75              terworth band-pass filter.
76
77              Cosine-taper:
78                     Specify four wavelengths  lc/lp/hp/hc  in  correct  units
79                     (see  -fg)  to  design  a  bandpass  filter:  wavelengths
80                     greater than lc or less than hc will be cut,  wavelengths
81                     greater  than  lp  and  less  than hp will be passed, and
82                     wavelengths in  between  will  be  cosine-tapered.  E.g.,
83                     -F1000000/250000/50000/10000  -fg  will bandpass, cutting
84                     wavelengths > 1000 km and < 10  km,  passing  wavelengths
85                     between  250  km and 50 km. To make a highpass or lowpass
86                     filter, give  hyphens  (-)  for  hp/hc  or  lc/lp.  E.g.,
87                     -Fx-/-/50/10 will lowpass x, passing wavelengths > 50 and
88                     rejecting wavelengths < 10. -Fy1000/250/-/- will highpass
89                     y,  passing wavelengths < 250 and rejecting wavelengths >
90                     1000.
91
92              Gaussian band-pass:
93                     Append lo/hi, the two wavelengths in correct  units  (see
94                     -fg)  to  design  a  bandpass  filter. At the given wave‐
95                     lengths the Gaussian filter weights will be 0.5. To  make
96                     a  highpass  or lowpass filter, give a hyphen (-) for the
97                     hi or lo wavelength, respectively. E.g., -F-/30 will low‐
98                     pass the data using a Gaussian filter with half-weight at
99                     30, while -F400/- will highpass the data.
100
101              Butterworth band-pass:
102                     Append lo/hi/order, the two wavelengths in correct  units
103                     (see  -fg)  and the filter order (an integer) to design a
104                     bandpass filter. At the  given  cut-off  wavelengths  the
105                     Butterworth filter weights will be 0.707 (i.e., the power
106                     spectrum will therefore be reduced by  0.5).  To  make  a
107                     highpass  or lowpass filter, give a hyphen (-) for the hi
108                     or lo wavelength, respectively. E.g., -F-/30/2 will  low‐
109                     pass  the data using a 2nd-order Butterworth filter, with
110                     half-weight at 30,  while  -F400/-/2  will  highpass  the
111                     data.
112
113       -Goutfile|table
114              Filename for output netCDF grid file OR 1-D data table (see -E).
115              This is optional for -E (spectrum written to stdout) but  manda‐
116              tory for all other options that require a grid output.
117
118       -I[scale|g]
119              Integrate the field, i.e., compute integral_over_z (field * dz).
120              This is equivalent to divide by kr in the frequency  domain  (kr
121              is radial wave number). Append a scale to divide by (kr * scale)
122              instead. Alternatively, append g to indicate that your data  set
123              is  gravity anomalies in mGal and output should be geoid heights
124              in meters. [Default is no scale].
125
126       -N[a|f|m|r|s|nx/ny][+a|[+d|h|l][+e|n|m][+twidth][+v][+w[suffix]][+z[p]]
127              Choose or inquire about suitable grid dimensions for FFT and set
128              optional parameters. Control the FFT dimension:
129                 -Na lets the FFT select dimensions yielding the most accurate
130                 result.
131
132                 -Nf will force the FFT to use the actual  dimensions  of  the
133                 data.
134
135                 -Nm  lets the FFT select dimensions using the least work mem‐
136                 ory.
137
138                 -Nr lets the FFT select dimensions yielding  the  most  rapid
139                 calculation.
140
141                 -Ns will present a list of optional dimensions, then exit.
142
143                 -Nnx/ny will do FFT on array size nx/ny (must be >= grid file
144                 size). Default chooses  dimensions  >=  data  which  optimize
145                 speed  and  accuracy  of  FFT.  If FFT dimensions > grid file
146                 dimensions, data are extended and tapered to zero.
147
148              Control detrending of data: Append modifiers for removing a lin‐
149              ear trend:
150                 +d:  Detrend  data,  i.e.  remove  best-fitting  linear trend
151                 [Default].
152
153                 +a: Only remove mean value.
154
155                 +h: Only remove mid value, i.e. 0.5 * (max + min).
156
157                 +l: Leave data alone.
158
159              Control extension and tapering of data: Use modifiers to control
160              how the extension and tapering are to be performed:
161                 +e   extends   the   grid  by  imposing  edge-point  symmetry
162                 [Default],
163
164                 +m extends the grid by imposing edge mirror symmetry
165
166                 +n turns off data extension.
167
168                 Tapering is performed from the data edge to the FFT grid edge
169                 [100%].   Change  this  percentage via +twidth. When +n is in
170                 effect, the tapering is applied instead to the  data  margins
171                 as no extension is available [0%].
172
173                 Control  messages  being  reported:  +v  will report suitable
174                 dimensions during processing.
175
176              Control writing of temporary results: For detailed investigation
177              you  can write the intermediate grid being passed to the forward
178              FFT;  this  is  likely  to  have  been  detrended,  extended  by
179              point-symmetry  along  all edges, and tapered. Append +w[suffix]
180              from  which  output  file  name(s)  will   be   created   (i.e.,
181              ingrid_prefix.ext)  [tapered], where ext is your file extension.
182              Finally, you may save the complex grid produced by  the  forward
183              FFT  by appending +z. By default we write the real and imaginary
184              components to ingrid_real.ext and ingrid_imag.ext. Append  p  to
185              save  instead  the  polar  form  of magnitude and phase to files
186              ingrid_mag.ext and ingrid_phase.ext.
187
188       -Sscale
189              Multiply each element by scale in the space  domain  (after  the
190              frequency domain operations). [Default is 1.0].
191
192       -V[level] (more ...)
193              Select verbosity level [c].
194
195       -fg    Geographic  grids  (dimensions  of  longitude, latitude) will be
196              converted to meters via a "Flat Earth" approximation  using  the
197              current ellipsoid parameters.
198
199       -^ or just -
200              Print  a  short  message  about  the syntax of the command, then
201              exits (NOTE: on Windows just use -).
202
203       -+ or just +
204              Print an extensive usage (help) message, including the  explana‐
205              tion  of  any  module-specific  option  (but  not the GMT common
206              options), then exits.
207
208       -? or no arguments
209              Print a complete usage (help) message, including the explanation
210              of all options, then exits.
211

GRID FILE FORMATS

213       By  default  GMT  writes  out  grid  as  single  precision  floats in a
214       COARDS-complaint netCDF file format. However, GMT is  able  to  produce
215       grid  files  in  many  other  commonly  used grid file formats and also
216       facilitates so called "packing" of grids, writing  out  floating  point
217       data as 1- or 2-byte integers. (more ...)
218

GRID DISTANCE UNITS

220       If  the  grid does not have meter as the horizontal unit, append +uunit
221       to the input file name to convert from the specified unit to meter.  If
222       your  grid  is geographic, convert distances to meters by supplying -fg
223       instead.
224

CONSIDERATIONS

226       netCDF COARDS grids will automatically be recognized as geographic. For
227       other  grids  geographical  grids were you want to convert degrees into
228       meters, select -fg. If the data are close to either  pole,  you  should
229       consider  projecting the grid file onto a rectangular coordinate system
230       using grdproject
231

NORMALIZATION OF SPECTRUM

233       By default, the power spectrum returned by -E simply sums the contribu‐
234       tions  from  frequencies that are part of the output frequency.  For x-
235       or y-spectra this means summing the power across  the  other  frequency
236       dimension,  while  for  the  radial  spectrum it means summing up power
237       within each annulus of width delta_q, the radial frequency (q) spacing.
238       A  consequence  of  this summing is that the radial spectrum of a white
239       noise process will give a linear radial power spectrum that is  propor‐
240       tional  to q.  Appending n will instead compute the mean power per out‐
241       put frequency and in this case the white  noise  process  will  have  a
242       white radial spectrum as well.
243

EXAMPLES

245       To  upward  continue  the  sea-level  magnetic  anomalies  in  the file
246       mag_0.nc to a level 800 m above sealevel:
247
248              gmt grdfft mag_0.nc -C800 -V -Gmag_800.nc
249
250       To transform geoid heights in m (geoid.nc) on a  geographical  grid  to
251       free-air gravity anomalies in mGal:
252
253              gmt grdfft geoid.nc -Dg -V -Ggrav.nc
254
255       To  transform  gravity anomalies in mGal (faa.nc) to deflections of the
256       vertical (in micro-radians) in the 038 direction, we must  first  inte‐
257       grate  gravity  to get geoid, then take the directional derivative, and
258       finally scale radians to micro-radians:
259
260              gmt grdfft faa.nc -Ig -A38 -S1e6 -V -Gdefl_38.nc
261
262       Second vertical derivatives of gravity anomalies  are  related  to  the
263       curvature of the field. We can compute these as mGal/m^2 by differenti‐
264       ating twice:
265
266              gmt grdfft gravity.nc -D -D -V -Ggrav_2nd_derivative.nc
267
268       To compute cross-spectral estimates for  co-registered  bathymetry  and
269       gravity grids, and report result as functions of wavelengths in km, try
270
271              gmt grdfft bathymetry.nc gravity.grd -E+wk -fg -V > cross_spectra.txt
272
273       To  examine  the  pre-FFT grid after detrending, point-symmetry reflec‐
274       tion, and tapering has been applied, as well as  saving  the  real  and
275       imaginary components of the raw spectrum of the data in topo.nc, try
276
277              gmt grdfft topo.nc -N+w+z -fg -V
278
279       You  can now make plots of the data in topo_taper.nc, topo_real.nc, and
280       topo_imag.nc.
281

SEE ALSO

283       gmt, grdedit, grdfilter, grdmath, grdproject, gravfft
284
286       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
287
288
289
290
2915.4.5                            Feb 24, 2019                        GRDFFT(1)
Impressum