Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       grdfilter - Filter a 2-D grid file in the space (or time) domain

SYNOPSIS

       grdfilter   input_file   -Ddistance_flag   -F<filtertype><width>[mode]   -Goutput_file   [
       -Ixinc[unit][=|+][/yinc[unit][=|+]] ] [ -Ni|p|r ] [ -Rwest/east/south/north[r] ] [ -T ]  [
       -V ] [ -f[i|o]colinfo ]

DESCRIPTION

       grdfilter will filter a .grd file in the time domain using one of the selected convolution
       or non-convolution isotropic filters and compute distances using  Cartesian  or  Spherical
       geometries.   The  output .grd file can optionally be generated as a subOPT(R)egion of the
       input and/or with a new -I ncrement.  In this way, one may have "extra space" in the input
       data  so  that  the edges will not be used and the output can be within one-half- width of
       the input edges.  If the filter is low-pass,  then  the  output  may  be  less  frequently
       sampled than the input.

       input_file
              The grid file of points to be filtered.  (See GRID FILE FORMATS below).

       -D     Distance flag tells how grid (x,y) relates to filter width as follows:

              flag = 0:  grid (x,y) same units as width, Cartesian distances.
              flag = 1:  grid (x,y) in degrees, width in kilometers, Cartesian distances.
              flag  =  2:   grid  (x,y)  in  degrees,  width  in  km, dx scaled by cos(middle y),
              Cartesian distances.

              The above options are fastest because they allow weight matrix to be computed  only
              once.   The  next  three options are slower because they recompute weights for each
              latitude.

              flag = 3:  grid (x,y) in degrees, width in km, dx scaled  by  cosine(y),  Cartesian
              distance calculation.
              flag = 4:  grid (x,y) in degrees, width in km, Spherical distance calculation.
              flag  =  5:  grid (x,y) in Mercator -Jm1 img units, width in km, Spherical distance
              calculation.

       -F     Sets the filter  type.   Choose  among  convolution  and  non-convolution  filters.
              Append  the  filter code followed by the full diameter width. Available convolution
              filters are:
              (b) Boxcar: All weights are equal.
              (c) Cosine Arch: Weights follow a cosine arch curve.
              (g) Gaussian: Weights are given by the Gaussian function, where width  is  6  times
              the conventional Gaussian sigma.
              Non-convolution filters are:
              (m) Median: Returns median value.
              (p) Maximum likelihood probability (a mode estimator): Return modal value.  If more
              than one mode is found we return their average value.  Append - or + to the  filter
              width if you rather want to return the smallest or largest of the modal values.
              (l) Lower: Return the minimum of all values.
              (L) Lower: Return minimum of all positive values only.
              (u) Upper: Return maximum of all values.
              (U) Upper: Return maximum or all negative values only.
              In  the  case  of  L|U it is possible that no data passes the initial sign test; in
              that case the filter will return 0.0.

       -G     output_file is the output grid file of the filter.  (See GRID FILE FORMATS below).

OPTIONS

       -I     x_inc [and optionally y_inc] is the output Increment. Append m to indicate minutes,
              or  c  to  indicate seconds.  If  the new x_inc, y_inc are NOT integer multiples of
              the old ones (in the input data), filtering will be considerably slower.  [Default:
              Same as input.]

       -N     Determine  how  NaN-values in the input grid affects the filtered outout:  Append i
              to ignore all NaNs in the calculation of filtered value [Default], r is same  as  i
              except  if  the  input  node  was NaN then the output node will be set to NaN (only
              applies if both grids are coregistered), and p which will force the filtered  value
              to be NaN if any grid-nodes with NaN-values are found inside the filter circle.

       -R     west,  east,  south,  and north defines the Region of the output points.  [Default:
              Same as input.]

       -T     Toggle the node registration for the output grid so as to become  the  opposite  of
              the input grid [Default gives the same registration as the input grid].

       -V     Selects  verbose  mode,  which  will  send progress reports to stderr [Default runs
              "silently"].

       -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[i|o]g means -f[i|o]0x,1y (geographic coordinates).

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 "packing" of grids, writing out floating point
       data as 2- or 4-byte integers. To specify the precision, scale and offset, the user should
       add  the  suffix =id[/scale/offset[/nan]], where id is a two-letter identifier of the grid
       type and precision, and scale and offset are  optional  scale  factor  and  offset  to  be
       applied  to  all  grid  values,  and nan is the value used to indicate missing data.  When
       reading grids, the format is generally automatically recognized. If not, the  same  suffix
       can  be  added  to  input grid file names.  See grdreformat(1) and Section 4.17 of the GMT
       Technical Reference and Cookbook for more information.

       When reading a netCDF file that contains multiple grids, GMT will read,  by  default,  the
       first  2-dimensional  grid  that  can  find in that file. To coax GMT into reading another
       multi-dimensional variable in the grid file, append  ?varname  to  the  file  name,  where
       varname  is the name of the variable. Note that you may need to escape the special meaning
       of ? in your shell program by putting a backslash in  front  of  it,  or  by  placing  the
       filename and suffix between quotes or double quotes.  The ?varname suffix can also be used
       for output grids to specify  a  variable  name  different  from  the  default:  "z".   See
       grdreformat(1)  and  Section  4.18  of  the  GMT Technical Reference and Cookbook for more
       information, particularly on how to read splices of 3-, 4-, or 5-dimensional grids.

GEOGRAPHICAL AND TIME COORDINATES

       When the output grid  type  is  netCDF,  the  coordinates  will  be  labeled  "longitude",
       "latitude", or "time" based on the attributes of the input data or grid (if any) or on the
       -f or -R options. For example, both -f0x -f1t  and  -R  90w/90e/0t/3t  will  result  in  a
       longitude/time grid. When the x, y, or z coordinate is time, it will be stored in the grid
       as relative time since epoch as specified by TIME_UNIT and TIME_EPOCH in the  .gmtdefaults
       file  or  on  the command line.  In addition, the unit attribute of the time variable will
       indicate both this unit and epoch.

EXAMPLES

       Suppose that north_pacific_dbdb5.grd is a file of 5 minute bathymetry from  140E  to  260E
       and  0N  to  50N,  and you want to find the medians of values within a 300km radius (600km
       full width) of the output points, which you choose to be from 150E to 250E and 10N to 40N,
       and  you  want the output values every 0.5 degree.  Using spherical distance calculations,
       you need:

       grdfilter north_pacific_dbdb5.grd -G filtered_pacific.grd -Fm 600 -D 4 -R 150/250/10/40 -I
       0.5 -V

LIMITATIONS

       When  working  with  geographic  (lat,  lon) grids, all three convolution filters (boxcar,
       cosine arch, and gaussian) will properly normalize the filter weights for the variation in
       gridbox  size  with  latitude,  and  correctly  determine  which  nodes are needed for the
       convolution when the filter "circle" crosses a periodic (0-360)  boundary  or  contains  a
       geographic  pole.   However,  the spatial filters, such as median and mode filters, do not
       use weights and thus should only be used on Cartesian grids (or  at  very  low  latitudes)
       only.  If you want to apply such spatial filters you should project your data to an equal-
       area projection and run grdfilter on the resulting Cartesian grid.
       To use the -D 5 option the input Mercator grid must be created by img2mercgrd using the -C
       option  so  the origin of the y-values is the Equator (i.e., x = y = 0 correspond to lon =
       lat = 0).

SEE ALSO

       GMT(1), grdfft(1) img2mercgrd(1)