1DIMFILTER(1) Generic Mapping Tools DIMFILTER(1)
2
6 dimfilter - Directional filtering of 2-D gridded files in the space (or
7 time) domain
8
10 dimfilter input_file.grd -Ddistance_flag -F<filtertype><width>[mode]
11 -Goutput_file.grd -N<filtertype><n_sectors> -Qcols [
12 -Ixinc[unit][=|+][/yinc[unit][=|+]] ] [ -Rwest/east/south/north[r] ] [
13 -T ] [ -V ]
14
16 dimfilter will filter a .grd file in the space (or time) domain by
17 dividing the given filter circle into n_sectors, applying one of the
18 selected primary convolution or non-convolution filters to each sector,
19 and choosing the final outcome according to the selected secondary fil‐
20 ter. It computes distances using Cartesian or Spherical geometries.
21 The output .grd file can optionally be generated as a sub-Region of the
22 input and/or with a new -Increment. In this way, one may have "extra
23 space" in the input data so that the edges will not be used and the
24 output can be within one-half-width of the input edges. If the filter
25 is low-pass, then the output may be less frequently sampled than the
26 input. -Q is for the error analysis mode and only requires the total
27 number of columns in the input file, which contains the filtered
28 depths. Finally, one should know that dimfilter will not produce a
29 smooth output as other spatial filters do because it returns a minimum
30 median out of N medians of N sectors. The output can be edgy unless
31 the input data is noise-free. Thus, an additional filtering (e.g.,
32 Gaussian) to the DiM-filtered data is generally recommended.
33 input_file.grd
35 The file of points to be filtered.
36 -D Distance flag tells how grid (x,y) relates to filter width as
38 follows:
39 flag = 0: grid (x,y) same units as width, Cartesian distances.
41 flag = 1: grid (x,y) in degrees, width in kilometers, Cartesian
42 distances.
43 flag = 2: grid (x,y) in degrees, width in km, dx scaled by
44 cos(middle y), Cartesian distances.
45 The above options are fastest because they allow weight matrix
47 to be computed only once. The next three options are slower
48 because they recompute weights for each latitude.
49 flag = 3: grid (x,y) in degrees, width in km, dx scaled by
51 cosine(y), Cartesian distance calculation.
52 flag = 4: grid (x,y) in degrees, width in km, Spherical dis‐
53 tance calculation.
54 -F Sets the primary filter type. Choose among convolution and non-
56 convolution filters. Append the filter code followed by the
57 full diameter width. Available convolution filters are:
58 (b) Boxcar: All weights are equal.
59 (c) Cosine Arch: Weights follow a cosine arch curve.
60 (g) Gaussian: Weights are given by the Gaussian function.
61 Non-convolution filters are:
62 (m) Median: Returns median value.
63 (p) Maximum likelihood probability (a mode estimator): Return
64 modal value. If more than one mode is found we return their
65 average value. Append - or + to the filter width if you rather
66 want to return the smallest or largest of the modal values.
67 -N Sets the secondary filter type and the number of bow-tie sec‐
69 tors. n_sectors must be integer and larger than 0. When n_sec‐
70 tors is set to 1, the secondary filter is not effective. Avail‐
71 able secondary filters are:
72 (l) Lower: Return the minimum of all filtered values.
73 (u) Upper: Return the maximum of all filtered values.
74 (a) Average: Return the mean of all filtered values.
75 (m) Median: Return the median of all filtered values.
76 (p) Mode: Return the mode of all filtered values.
77 -G output_file.grd is the output of the filter.
79
81 -I x_inc [and optionally y_inc] is the output Increment. Append m
82 to indicate minutes, or c to indicate seconds. If the new
83 x_inc, y_inc are NOT integer multiples of the old ones (in the
84 input data), filtering will be considerably slower. [Default:
85 Same as input.]
86 -R west, east, south, and north defines the Region of the output
88 points. [Default: Same as input.]
89 -T Toggle the node registration for the output grid so as to become
91 the opposite of the input grid [Default gives the same registra‐
92 tion as the input grid].
93 -Q cols is the total number of columns in the input file. For this
95 mode, it expects to read depths consisted of several columns.
96 Each column represents a filtered grid with a filter width,
97 which can be obtained by 'grd2xyz -Z'. The outcome will be
98 median, MAD, and mean. So, the column with the medians is used
99 to generate the regional component and the column with the MADs
100 to conduct the error analysis.
101 -V Selects verbose mode, which will send progress reports to stderr
103 [Default runs "silently"].
104
106 By default GMT writes out grid as single precision floats in a COARDS-
107 complaint netCDF file format. However, GMT is able to produce grid
108 files in many other commonly used grid file formats and also facili‐
109 tates so called "packing" of grids, writing out floating point data as
110 2- or 4-byte integers. To specify the precision, scale and offset, the
111 user should add the suffix =id[/scale/offset[/nan]], where id is a two-
112 letter identifier of the grid type and precision, and scale and offset
113 are optional scale factor and offset to be applied to all grid values,
114 and nan is the value used to indicate missing data. When reading
115 grids, the format is generally automatically recognized. If not, the
116 same suffix can be added to input grid file names. See grdreformat(1)
117 and Section 4.17 of the GMT Technical Reference and Cookbook for more
118 information.
119 When reading a netCDF file that contains multiple grids, GMT will read,
121 by default, the first 2-dimensional grid that can find in that file. To
122 coax GMT into reading another multi-dimensional variable in the grid
123 file, append ?varname to the file name, where varname is the name of
124 the variable. Note that you may need to escape the special meaning of ?
125 in your shell program by putting a backslash in front of it, or by
126 placing the filename and suffix between quotes or double quotes. The
127 ?varname suffix can also be used for output grids to specify a variable
128 name different from the default: "z". See grdreformat(1) and Section
129 4.18 of the GMT Technical Reference and Cookbook for more information,
130 particularly on how to read splices of 3-, 4-, or 5-dimensional grids.
131
133 When the output grid type is netCDF, the coordinates will be labeled
134 "longitude", "latitude", or "time" based on the attributes of the input
135 data or grid (if any) or on the -f or -R options. For example, both
136 -f0x -f1t and -R90w/90e/0t/3t will result in a longitude/time grid.
137 When the x, y, or z coordinate is time, it will be stored in the grid
138 as relative time since epoch as specified by TIME_UNIT and TIME_EPOCH
139 in the .gmtdefaults file or on the command line. In addition, the unit
140 attribute of the time variable will indicate both this unit and epoch.
141
143 Suppose that north_pacific_dbdb5.grd is a file of 5 minute bathymetry
144 from 140E to 260E and 0N to 50N, and you want to find the medians of
145 values within a 300km radius (600km full width) of the output points,
146 which you choose to be from 150E to 250E and 10N to 40N, and you want
147 the output values every 0.5 degree. To prevent the medians from being
148 biased by the sloping plane, you want to divide the filter circle into
149 6 sectors and to choose the lowest value among 6 medians. Using spheri‐
150 cal distance calculations, you need:
151 dimfilter north_pacific_dbdb5.grd -Gfiltered_pacific.grd -Fm600 -D4
153 -Nl6 -R150/250/10/40 -I0.5 -V
154 Suppose that cape_verde.grd is a file of 0.5 minute bathymetry from 32W
156 to 15W and 8N to 25N, and you want to remove small-length-scale fea‐
157 tures in order to define a swell in an area extending from 27.5W to
158 20.5W and 12.5N to 19.5N, and you want the output value every 2 minute.
159 Using cartesian distance calculations, you need:
160 dimfilter cape_verde.grd -Gt.grd -Fm220 -Nl8 -D2
162 -R-27.5/-20.5/12.5/19.5 -I2m -V
163 grdfilter t.grd -Gcape_swell.grd -Fg50 -D2 -V
164 Suppose that you found a range of filter widths for a given area, and
166 you filtered the given bathymetric data using the range of filter
167 widths (e.g., f100.grd f110.grd f120.grd f130.grd), and you want to
168 define a regional trend using the range of filter widths, and you want
169 to obtain median absolute deviation (MAD) estimates at each data point,
170 you need:
171 grd2xyz f100.grd -Z > f100.d
173 grd2xyz f110.grd -Z > f110.d
174 grd2xyz f120.grd -Z > f120.d
175 grd2xyz f130.grd -Z > f130.d
176 paste f100.d f110.d f120.d f130.d > depths.d
177 dimfilter depths.d -Q4 > output.z
178
181 When working with geographic (lat, lon) grids, all three convolution
182 filters (boxcar, cosine arch, and gaussian) will properly normalize the
183 filter weights for the variation in gridbox size with latitude, and
184 correctly determine which nodes are needed for the convolution when the
185 filter "circle" crosses a periodic (0-360) boundary or contains a geo‐
186 graphic pole. However, the spatial filters, such as median and mode
187 filters, do not use weights and thus should only be used on Cartesian
188 grids (or at very low latitudes) only. If you want to apply such spa‐
189 tial filters you should project your data to an equal-area projection
190 and run dimfilter on the resulting Cartesian grid.
191
193 The dim.template.sh is a skeleton shell script that can be used to set
194 up a complete DiM analysis, including the MAD analysis.
195
197 Kim, S.-S., and Wessel, P. (2008), Directional Median Filtering for
198 Regional-Residual Separation of Bathymetry, Geochem. Geophys. Geosyst.,
199 9(Q03005), doi:10.1029/2007GC001850.
200
202 GMT(1), grdfilter(1)
203GMT 4.5.6 10 Mar 2011 DIMFILTER(1)