manpagez: man pages & more
man grdfft(1)
Home | html | info | man
grdfft(1)                             GMT                            grdfft(1)




NAME

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


SYNOPSIS

       grdfft ingrid [ ingrid2  ]  [   -Goutfile|table  ]  [   -Aazimuth  ]  [
       -Czlevel   ]   [    -D[scale|g]   ]   [    -E[r|x|y][+w[k]][+n]   ]   [
       -F[r|x|y]params ] [  -I[scale|g]  ]  [   -Nparams  ]  [   -Sscale  ]  [
       -V[level] ] [ -fg ]

       Note:  No  space  is allowed between the option flag and the associated
       arguments.


DESCRIPTION

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


REQUIRED ARGUMENTS

       ingrid 2-D  binary  grid file to be operated on. (See GRID FILE FORMATS
              below). For cross-spectral operations, also give the second grid
              file ingrd2.

       -Goutfile
              Specify the name of the output grid file or the 1-D spectrum ta-
              ble (see -E). (See GRID FILE FORMATS below).


OPTIONAL ARGUMENTS

       -Aazimuth
              Take the directional derivative in the  azimuth  direction  mea-
              sured in degrees CW from north.

       -Czlevel
              Upward  (for  zlevel  > 0) or downward (for zlevel < 0) continue
              the field zlevel meters.

       -D[scale|g]
              Differentiate the field, i.e., take d(field)/dz. This is equiva-
              lent  to multiplying by kr in the frequency domain (kr is radial
              wave number). Append  a  scale  to  multiply  by  (kr  *  scale)
              instead.  Alternatively, append g to indicate that your data are
              geoid heights in meters and output should be  gravity  anomalies
              in mGal.  [Default is no scale].

       -E[r|x|y][+w[k]][+n]
              Estimate  power spectrum in the radial direction [r]. Place x or
              y immediately after -E to compute the spectrum in  the  x  or  y
              direction instead. No grid file is created. If one grid is given
              then f (i.e., frequency or wave number), power[f], and  1  stan-
              dard  deviation  in  power[f]  are written to the file set by -G
              [stdout]. If two grids are given we write f  and  8  quantities:
              Xpower[f],   Ypower[f],   coherent   power[f],  noise  power[f],
              phase[f], admittance[f], gain[f], coherency[f].   Each  quantity
              is  followed by its own 1-std dev error estimate, hence the out-
              put is 17 columns wide.  Give +w to write wavelength instead  of
              frequency, and if your grid is geographic you may further append
              k to scale wavelengths from meter [Default] to km.  Finally, the
              spectrum  is  obtained  by  summing  over  several  frequencies.
              Append +n to normalize so that the mean spectral values per fre-
              quency are reported instead.

       -F[r|x|y]params
              Filter  the  data. Place x or y immediately after -F to filter x
              or y direction only; default is isotropic [r].  Choose between a
              cosine-tapered band-pass, a Gaussian band-pass filter, or a But-
              terworth band-pass filter.

              Cosine-taper:
                     Specify four wavelengths  lc/lp/hp/hc  in  correct  units
                     (see  -fg)  to  design  a  bandpass  filter:  wavelengths
                     greater than lc or less than hc will be cut,  wavelengths
                     greater  than  lp  and  less  than hp will be passed, and
                     wavelengths in  between  will  be  cosine-tapered.  E.g.,
                     -F1000000/250000/50000/10000  -fg  will bandpass, cutting
                     wavelengths > 1000 km and < 10  km,  passing  wavelengths
                     between  250  km and 50 km. To make a highpass or lowpass
                     filter, give  hyphens  (-)  for  hp/hc  or  lc/lp.  E.g.,
                     -Fx-/-/50/10 will lowpass x, passing wavelengths > 50 and
                     rejecting wavelengths < 10. -Fy1000/250/-/- will highpass
                     y,  passing wavelengths < 250 and rejecting wavelengths >
                     1000.

              Gaussian band-pass:
                     Append lo/hi, the two wavelengths in correct  units  (see
                     -fg)  to  design  a  bandpass  filter. At the given wave-
                     lengths the Gaussian filter weights will be 0.5. To  make
                     a  highpass  or lowpass filter, give a hyphen (-) for the
                     hi or lo wavelength, respectively. E.g., -F-/30 will low-
                     pass the data using a Gaussian filter with half-weight at
                     30, while -F400/- will highpass the data.

              Butterworth band-pass:
                     Append lo/hi/order, the two wavelengths in correct  units
                     (see  -fg)  and the filter order (an integer) to design a
                     bandpass filter. At the  given  cut-off  wavelengths  the
                     Butterworth filter weights will be 0.707 (i.e., the power
                     spectrum will therefore be reduced by  0.5).  To  make  a
                     highpass  or lowpass filter, give a hyphen (-) for the hi
                     or lo wavelength, respectively. E.g., -F-/30/2 will  low-
                     pass  the data using a 2nd-order Butterworth filter, with
                     half-weight at 30,  while  -F400/-/2  will  highpass  the
                     data.

       -Goutfile|table
              Filename for output netCDF grid file OR 1-D data table (see -E).
              This is optional for -E (spectrum written to stdout) but  manda-
              tory for all other options that require a grid output.

       -I[scale|g]
              Integrate the field, i.e., compute integral_over_z (field * dz).
              This is equivalent to divide by kr in the frequency  domain  (kr
              is radial wave number). Append a scale to divide by (kr * scale)
              instead. Alternatively, append g to indicate that your data  set
              is  gravity anomalies in mGal and output should be geoid heights
              in meters. [Default is no scale].

       -N[a|f|m|r|s|nx/ny][+a|[+d|h|l][+e|n|m][+twidth][+v][+w[suffix]][+z[p]]
              Choose or inquire about suitable grid dimensions for FFT and set
              optional parameters. Control the FFT dimension:
                 -Na lets the FFT select dimensions yielding the most accurate
                 result.

                 -Nf will force the FFT to use the actual  dimensions  of  the
                 data.

                 -Nm  lets the FFT select dimensions using the least work mem-
                 ory.

                 -Nr lets the FFT select dimensions yielding  the  most  rapid
                 calculation.

                 -Ns will present a list of optional dimensions, then exit.

                 -Nnx/ny will do FFT on array size nx/ny (must be >= grid file
                 size). Default chooses  dimensions  >=  data  which  optimize
                 speed  and  accuracy  of  FFT.  If FFT dimensions > grid file
                 dimensions, data are extended and tapered to zero.

              Control detrending of data: Append modifiers for removing a lin-
              ear trend:
                 +d:  Detrend  data,  i.e.  remove  best-fitting  linear trend
                 [Default].

                 +a: Only remove mean value.

                 +h: Only remove mid value, i.e. 0.5 * (max + min).

                 +l: Leave data alone.

              Control extension and tapering of data: Use modifiers to control
              how the extension and tapering are to be performed:
                 +e   extends   the   grid  by  imposing  edge-point  symmetry
                 [Default],

                 +m extends the grid by imposing edge mirror symmetry

                 +n turns off data extension.

                 Tapering is performed from the data edge to the FFT grid edge
                 [100%].   Change  this  percentage via +twidth. When +n is in
                 effect, the tapering is applied instead to the  data  margins
                 as no extension is available [0%].

                 Control  messages  being  reported:  +v  will report suitable
                 dimensions during processing.

              Control writing of temporary results: For detailed investigation
              you  can write the intermediate grid being passed to the forward
              FFT;  this  is  likely  to  have  been  detrended,  extended  by
              point-symmetry  along  all edges, and tapered. Append +w[suffix]
              from  which  output  file  name(s)  will   be   created   (i.e.,
              ingrid_prefix.ext)  [tapered], where ext is your file extension.
              Finally, you may save the complex grid produced by  the  forward
              FFT  by appending +z. By default we write the real and imaginary
              components to ingrid_real.ext and ingrid_imag.ext. Append  p  to
              save  instead  the  polar  form  of magnitude and phase to files
              ingrid_mag.ext and ingrid_phase.ext.

       -Sscale
              Multiply each element by scale in the space  domain  (after  the
              frequency domain operations). [Default is 1.0].

       -V[level] (more a|)
              Select verbosity level [c].

       -fg    Geographic  grids  (dimensions  of  longitude, latitude) will be
              converted to meters via a aFlat Eartha approximation  using  the
              current ellipsoid parameters.

       -^ or just -
              Print  a  short  message  about  the syntax of the command, then
              exits (NOTE: on Windows just use -).

       -+ or just +
              Print an extensive usage (help) message, including the  explana-
              tion  of  any  module-specific  option  (but  not the GMT common
              options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation
              of all options, then exits.


GRID FILE FORMATS

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


GRID DISTANCE UNITS

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


CONSIDERATIONS

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


NORMALIZATION OF SPECTRUM

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


EXAMPLES

       To  upward  continue  the  sea-level  magnetic  anomalies  in  the file
       mag_0.nc to a level 800 m above sealevel:

              gmt grdfft mag_0.nc -C800 -V -Gmag_800.nc

       To transform geoid heights in m (geoid.nc) on a  geographical  grid  to
       free-air gravity anomalies in mGal:

              gmt grdfft geoid.nc -Dg -V -Ggrav.nc

       To  transform  gravity anomalies in mGal (faa.nc) to deflections of the
       vertical (in micro-radians) in the 038 direction, we must  first  inte-
       grate  gravity  to get geoid, then take the directional derivative, and
       finally scale radians to micro-radians:

              gmt grdfft faa.nc -Ig -A38 -S1e6 -V -Gdefl_38.nc

       Second vertical derivatives of gravity anomalies  are  related  to  the
       curvature of the field. We can compute these as mGal/m^2 by differenti-
       ating twice:

              gmt grdfft gravity.nc -D -D -V -Ggrav_2nd_derivative.nc

       To compute cross-spectral estimates for  co-registered  bathymetry  and
       gravity grids, and report result as functions of wavelengths in km, try

              gmt grdfft bathymetry.nc gravity.grd -E+wk -fg -V > cross_spectra.txt

       To examine the pre-FFT grid after  detrending,  point-symmetry  reflec-
       tion,  and  tapering  has  been applied, as well as saving the real and
       imaginary components of the raw spectrum of the data in topo.nc, try

              gmt grdfft topo.nc -N+w+z -fg -V

       You can now make plots of the data in topo_taper.nc, topo_real.nc,  and
       topo_imag.nc.


SEE ALSO

       gmt(1), grdedit(1), grdfilter(1), grdmath(1), grdproject(1), gravfft(1)


COPYRIGHT

       2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe



5.4.2                            Jun 24, 2017                        grdfft(1)

gmt5 5.4.2 - Generated Wed Jun 28 18:25:25 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.