xenial (1) dimfilter.1gmt.gz

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

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