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




NAME

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


SYNOPSIS

       dimfilter input_file.nc  -Ddistance_flag
        -Fxwidth[mode]  -Goutput_file.nc
        -Nxsectors [  -Qcols ] [  -Iincrement ]  [   -Rregion  ]  [   -T  ]  [
       -V[level] ] [ -fflags ]

       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 fil-
       ter. 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  aextra
       spacea  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 fil-
       tering  (e.g., Gaussian via grdfilter) of the DiM-filtered data is gen-
       erally 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.

       -Fxwidth[mode]
              Sets the primary  filter  type.  Choose  among  convolution  and
              non-convolution  filters.  Append  the filter code x 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.

       -Nxsectors
              Sets  the secondary filter type x and the number of bow-tie sec-
              tors.  sectors must be integer and larger than 0.  When  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 registra-
              tion 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 a|)
              Select verbosity level [c].

       -f[i|o]colinfo (more a|)
              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 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|)


GEOGRAPHICAL AND TIME COORDINATES

       When  the  output  grid type is netCDF, the coordinates will be labeled
       alongitudea, alatitudea, or atimea 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 spheri-
       cal 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 fea-
       tures 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  acirclea crosses a periodic (0-360) boundary or contains a geo-
       graphic 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  spa-
       tial  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(1), grdfilter(1)


COPYRIGHT

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



5.4.2                            Jun 24, 2017                     dimfilter(1)

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