Provided by: gmt-common_5.2.1+dfsg-3build1_all bug

NAME

       dimfilter - Directional filtering of 2-D gridded files in the space (or time) domain

SYNOPSIS

       dimfilter    input_file.nc    distance_flag    <filtertype><width>[mode]    output_file.nc
       <filtertype><n_sectors> [ cols ] [ increment ] [ region ] [  ] [ [level] ] [ -f<flags> ]

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

DESCRIPTION

       dimfilter will filter a .nc file in the space (or  time)  domain  by  dividing  the  given
       filter  circle  into  n_sectors,  applying  one  of  the  selected  primary convolution or
       non-convolution filters to each sector, and choosing the final outcome  according  to  the
       selected  secondary filter. It computes distances using Cartesian or Spherical geometries.
       The output .nc file can optionally be generated as a subregion of the input and/or with  a
       new  -Increment.  In  this way, one may have "extra space" in the input data so that there
       will be no edge effects for the output grid. If the filter is low-pass,  then  the  output
       may  be less frequently sampled than the input. -Q is for the error analysis mode and only
       requires the total number of columns in  the  input  file,  which  contains  the  filtered
       depths.  Finally, one should know that dimfilter will not produce a smooth output as other
       spatial filters do because it returns a minimum median out of N medians of N sectors.  The
       output  can  be  rough unless the input data is noise-free.  Thus, an additional filtering
       (e.g., Gaussian via grdfilter) of the DiM-filtered data is generally recommended.

REQUIRED ARGUMENTS

       input_file.nc
              The data grid to be filtered.

       -Ddistance_flag
              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.

       -F<filtertype><width>[mode]
              Sets the primary 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.

              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.

       -N<filtertype><n_sectors>
              Sets  the  secondary filter type and the number of bow-tie sectors.  n_sectors must
              be integer and larger than 0. When n_sectors is set to 1, the secondary  filter  is
              not effective. Available secondary filters are:

              (l) Lower: Return the minimum of all filtered values.

              (u) Upper: Return the maximum of all filtered values.

              (a) Average: Return the mean of all filtered values.

              (m) Median: Return the median of all filtered values.

              (p) Mode: Return the mode of all filtered values.

       -Goutput_file.nc
              output_file.nc is the output of the filter.

OPTIONAL ARGUMENTS

       -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.]

       -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].

       -Qcols cols is the total number of columns in the input text table file.  For  this  mode,
              it  expects  to  read depths consisted of several columns. Each column represents a
              filtered grid with a filter width, which can be obtained by grd2xyz -Z. The outcome
              will  be median, MAD, and mean. So, the column with the medians is used to generate
              the regional component and the column with the MADs is used to  conduct  the  error
              analysis.

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

       -f[i|o]colinfo (more ...)
              Specify data types of input and/or output columns.

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

       -+ or just +
              Print  an  extensive  usage  (help)  message,  including  the  explanation  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 options, then
              exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

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 1- or 2-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.  In  case
       the  two  characters  id  is  not  provided,  as in =/scale than a id=nf is assumed.  When
       reading grids, the format is generally automatically recognized. If not, the  same  suffix
       can  be added to input grid file names. See grdconvert and Section grid-file-format 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
       grdconvert  and  Sections  modifiers-for-CF  and  grid-file-format  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 -R90w/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 gmt.conf 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.nc 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. To prevent the medians from being  biased  by
       the  sloping  plane, you want to divide the filter circle into 6 sectors and to choose the
       lowest value among 6 medians. Using spherical distance calculations, you need:

              gmt dimfilter north_pacific_dbdb5.nc -Gfiltered_pacific.nc -Fm600 -D4 \
                  -Nl6 -R150/250/10/40 -I0.5 -V

       Suppose that cape_verde.nc is a file of 0.5 minute bathymetry from 32W to 15W  and  8N  to
       25N,  and  you want to remove small-length-scale features in order to define a swell in an
       area extending from 27.5W to 20.5W and 12.5N to 19.5N, and you want the output value every
       2 minute. Using cartesian distance calculations, you need:

              gmt dimfilter cape_verde.nc -Gt.nc -Fm220 -Nl8 -D2 -R-27.5/-20.5/12.5/19.5 -I2m -V
              gmt grdfilter t.nc -Gcape_swell.nc -Fg50 -D2 -V

       Suppose  that  you  found  a range of filter widths for a given area, and you filtered the
       given bathymetric data using the range of filter widths  (e.g.,  f100.nc  f110.nc  f120.nc
       f130.nc),  and  you  want to define a regional trend using the range of filter widths, and
       you want to obtain median absolute deviation (MAD) estimates at each data point. Then, you
       will need to do:

              gmt grd2xyz f100.nc -Z > f100.d
              gmt grd2xyz f110.nc -Z > f110.d
              gmt grd2xyz f120.nc -Z > f120.d
              gmt grd2xyz f130.nc -Z > f130.d
              paste f100.d f110.d f120.d f130.d > depths.d
              gmt dimfilter depths.d -Q4 > output.z

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 dimfilter on the resulting Cartesian grid.

SCRIPT TEMPLATE

       The dim.template.sh is a skeleton shell script that can be used to set up a  complete  DiM
       analysis, including the MAD analysis.

REFERENCE

       Kim,  S.-S.,  and  Wessel,  P.  (2008), Directional Median Filtering for Regional-Residual
       Separation    of    Bathymetry,    Geochem.     Geophys.      Geosyst.,     9,     Q03005,
       doi:10.1029/2007GC001850.

SEE ALSO

       gmt, grdfilter

COPYRIGHT

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