99 build_arg_string ,
1010 data_kind ,
1111 fmt_docstring ,
12+ kwargs_to_strings ,
1213 use_alias ,
1314)
1415
1516
1617@fmt_docstring
17- @use_alias (V = "verbose" , f = "coltypes" , n = "interpolation" )
18+ @use_alias (
19+ A = "resample" ,
20+ C = "crossprofile" ,
21+ D = "dfile" ,
22+ E = "profile" ,
23+ F = "critical" ,
24+ R = "region" ,
25+ N = "no_skip" ,
26+ S = "stack" ,
27+ T = "radius" ,
28+ V = "verbose" ,
29+ Z = "z_only" ,
30+ f = "coltypes" ,
31+ i = "incols" ,
32+ j = "distcalc" ,
33+ n = "interpolation" ,
34+ )
35+ @kwargs_to_strings (R = "sequence" , S = "sequence" )
1836def grdtrack (points , grid , newcolname = None , outfile = None , ** kwargs ):
19- """
37+ r """
2038 Sample grids at specified (x,y) locations.
2139
22- Grdtrack reads one or more grid files and a table with (x,y) [or (lon,lat)]
23- positions in the first two columns (more columns may be present). It
24- interpolates the grid(s) at the positions in the table and writes out the
25- table with the interpolated values added as (one or more) new columns. A
26- bicubic [Default], bilinear, B-spline or nearest-neighbor interpolation is
27- used, requiring boundary conditions at the limits of the region (see
40+ Reads one or more grid files and a table (from file or an array input; but
41+ see ``profile`` for exception) with (x,y) [or (lon,lat)] positions in the
42+ first two columns (more columns may be present). It interpolates the
43+ grid(s) at the positions in the table and writes out the table with the
44+ interpolated values added as (one or more) new columns. Alternatively
45+ (``crossprofile``), the input is considered to be line-segments and we
46+ create orthogonal cross-profiles at each data point or with an equidistant
47+ separation and sample the grid(s) along these profiles. A bicubic
48+ [Default], bilinear, B-spline or nearest-neighbor interpolation is used,
49+ requiring boundary conditions at the limits of the region (see
2850 ``interpolation``; Default uses "natural" conditions (second partial
2951 derivative normal to edge is zero) unless the grid is automatically
3052 recognized as periodic.)
@@ -51,8 +73,169 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs):
5173 outfile : str
5274 The file name for the output ASCII file.
5375
76+ resample : str
77+ **f**\|\ **p**\|\ **m**\|\ **r**\|\ **R**\ [**+l**]
78+ For track resampling (if ``crossprofile`` or ``profile`` are set) we
79+ can select how this is to be performed. Append **f** to keep original
80+ points, but add intermediate points if needed [Default], **m** as
81+ **f**, but first follow meridian (along y) then parallel (along x),
82+ **p** as **f**, but first follow parallel (along y) then meridian
83+ (along x), **r** to resample at equidistant locations; input points are
84+ not necessarily included in the output, and **R** as **r**, but adjust
85+ given spacing to fit the track length exactly. Finally, append
86+ **+l** if geographic distances should be measured along rhumb lines
87+ (loxodromes) instead of great circles. Ignored unless ``crossprofile``
88+ is used.
89+ crossprofile : str
90+ *length*/\ *ds*\ [*/spacing*][**+a**\|\ **+v**][**l**\|\ **r**].
91+ Use input line segments to create an equidistant and (optionally)
92+ equally-spaced set of crossing profiles along which we sample the
93+ grid(s) [Default simply samples the grid(s) at the input locations].
94+ Specify two length scales that control how the sampling is done:
95+ *length* sets the full length of each cross-profile, while *ds* is
96+ the sampling spacing along each cross-profile. Optionally, append
97+ **/**\ *spacing* for an equidistant spacing between cross-profiles
98+ [Default erects cross-profiles at the input coordinates]; see
99+ ``resample`` for how resampling the input track is controlled. By
100+ default, all cross-profiles have the same direction (left to right
101+ as we look in the direction of the input line segment). Append **+a**
102+ to alternate the direction of cross-profiles, or **v** to enforce
103+ either a "west-to-east" or "south-to-north" view. By default the entire
104+ profiles are output. Choose to only output the left or right halves
105+ of the profiles by appending **+l** or **+r**, respectively. Append
106+ suitable units to *length*; it sets the unit used for *ds* [and
107+ *spacing*] (See :gmt-docs:`Units <grdtrack.html#units>`). The default
108+ unit for geographic grids is meter while Cartesian grids implies the
109+ user unit. The output columns will be *lon*, *lat*, *dist*, *azimuth*,
110+ *z1*, *z2*, ..., *zn* (The *zi* are the sampled values for each of the
111+ *n* grids).
112+ dfile : str
113+ In concert with ``crossprofile`` we can save the (possibly resampled)
114+ original lines to *dfile* [Default only saves the cross-profiles]. The
115+ columns will be *lon*, *lat*, *dist*, *azimuth*, *z1*, *z2*, ...
116+ (sampled value for each grid).
117+ profile : str
118+ *line*\ [,\ *line*,...][**+a**\ *az*][**+c**][**+d**][**+g**]\
119+ [**+i**\ *inc*][**+l**\ *length*][**+n**\ *np*][**+o**\ *az*]\
120+ [**+r**\ *radius*].
121+ Instead of reading input track coordinates, specify profiles via
122+ coordinates and modifiers. The format of each *line* is
123+ *start*/*stop*, where *start* or *stop* are either *lon*/*lat* (*x*/*y*
124+ for Cartesian data) or a 2-character XY key that uses the
125+ :gmt-docs:`text <text.html>`-style justification format to specify
126+ a point on the map as [LCR][BMT]. Each line will be a separate segment
127+ unless **+c** is used which will connect segments with shared joints
128+ into a single segment. In addition to line coordinates, you can use Z-,
129+ Z+ to mean the global minimum and maximum locations in the grid (only
130+ available if a single grid is given via **outfile**). You may append
131+ **+i**\ *inc* to set the sampling interval; if not given then we
132+ default to half the minimum grid interval. For a *line* along parallels
133+ or meridians you can add **+g** to report degrees of longitude or
134+ latitude instead of great circle distances starting at zero. Instead of
135+ two coordinates you can specify an origin and one of **+a**, **+o**, or
136+ **+r**. The **+a** sets the azimuth of a profile of given length
137+ starting at the given origin, while **+o** centers the profile on the
138+ origin; both require **+l**. For circular sampling specify **+r** to
139+ define a circle of given radius centered on the origin; this option
140+ requires either **+n** or **+i**. The **+n**\ *np* modifier sets the
141+ desired number of points, while **+l**\ *length* gives the total length
142+ of the profile. Append **+d** to output the along-track distances after
143+ the coordinates. **Note**: No track file will be read. Also note that
144+ only one distance unit can be chosen. Giving different units will
145+ result in an error. If no units are specified we default to great
146+ circle distances in km (if geographic). If working with geographic data
147+ you can use ``distcalc`` to control distance calculation mode [Default
148+ is Great Circle]. **Note**: If ``crossprofile`` is set and *spacing* is
149+ given then that sampling scheme overrules any modifier set in
150+ ``profile``.
151+ critical : str
152+ [**+b**][**+n**][**+r**][**+z**\ *z0*].
153+ Find critical points along each cross-profile as a function of
154+ along-track distance. Requires ``crossprofile`` and a single input grid
155+ (*z*). We examine each cross-profile generated and report (*dist*,
156+ *lonc*, *latc*, *distc*, *azimuthc*, *zc*) at the center peak of
157+ maximum *z* value, (*lonl*, *latl*, *distl*) and (*lonr*, *latr*,
158+ *distr*) at the first and last non-NaN point whose *z*-value exceeds
159+ *z0*, respectively, and the *width* based on the two extreme points
160+ found. Here, *dist* is the distance along the original input
161+ ``points`` and the other 12 output columns are a function of that
162+ distance. When searching for the center peak and the extreme first and
163+ last values that exceed the threshold we assume the profile is positive
164+ up. If we instead are looking for a trough then you must use **+n** to
165+ temporarily flip the profile to positive. The threshold *z0* value is
166+ always given as >= 0; use **+z** to change it [Default is 0].
167+ Alternatively, use **+b** to determine the balance point and standard
168+ deviation of the profile; this is the weighted mean and weighted
169+ standard deviation of the distances, with *z* acting as the weight.
170+ Finally, use **+r** to obtain the weighted rms about the cross-track
171+ center (*distc* == 0). **Note**: We round the exact results to the
172+ nearest distance nodes along the cross-profiles. We write 13 output
173+ columns per track: *dist, lonc, latc, distc, azimuthc, zc, lonl, latl,
174+ distl, lonr, latr, distr, width*.
175+ {R}
176+ no_skip : bool
177+ Do *not* skip points that fall outside the domain of the grid(s)
178+ [Default only output points within grid domain].
179+ stack : str or list
180+ *method*/*modifiers*.
181+ In conjunction with ``crossprofile``, compute a single stacked profile
182+ from all profiles across each segment. Choose how stacking should be
183+ computed [Default method is **a**]:
184+
185+ - **a** = mean (average)
186+ - **m** = median
187+ - **p** = mode (maximum likelihood)
188+ - **l** = lower
189+ - **L** = lower but only consider positive values
190+ - **u** = upper
191+ - **U** = upper but only consider negative values.
192+
193+ The *modifiers* control the output; choose one or more among these
194+ choices:
195+
196+ - **+a** : Append stacked values to all cross-profiles.
197+ - **+d** : Append stack deviations to all cross-profiles.
198+ - **+r** : Append data residuals (data - stack) to all cross-profiles.
199+ - **+s**\ [*file*] : Save stacked profile to *file* [Default filename
200+ is grdtrack_stacked_profile.txt].
201+ - **+c**\ *fact* : Compute envelope on stacked profile as
202+ ±\ *fact* \*\ *deviation* [Default fact value is 2].
203+
204+ Notes:
205+
206+ 1. Deviations depend on *method* and are st.dev (**a**), L1 scale,
207+ i.e., 1.4826 \* median absolute deviation (MAD) (for **m** and
208+ **p**), or half-range (upper-lower)/2.
209+ 2. The stacked profile file contains a leading column plus groups of
210+ 4-6 columns, with one group for each sampled grid. The leading
211+ column holds cross distance, while the first four columns in a group
212+ hold stacked value, deviation, min value, and max value,
213+ respectively. If *method* is one of **a**\|\ **m**\|\ **p** then we
214+ also write the lower and upper confidence bounds (see **+c**). When
215+ one or more of **+a**, **+d**, and **+r** are used then we also
216+ append the stacking results to the end of each row, for all
217+ cross-profiles. The order is always stacked value (**+a**), followed
218+ by deviations (**+d**) and finally residuals (**+r**). When more
219+ than one grid is sampled this sequence of 1-3 columns is repeated
220+ for each grid.
221+ radius : bool or int or float or str
222+ [*radius*][**+e**\|\ **p**].
223+ To be used with normal grid sampling, and limited to a single, non-IMG
224+ grid. If the nearest node to the input point is NaN, search outwards
225+ until we find the nearest non-NaN node and report that value instead.
226+ Optionally specify a search radius which limits the consideration to
227+ points within this distance from the input point. To report the
228+ location of the nearest node and its distance from the input point,
229+ append **+e**. The default unit for geographic grid distances is
230+ spherical degrees. Use *radius* to change the unit and give *radius* =
231+ 0 if you do not want to limit the radius search. To instead replace the
232+ input point with the coordinates of the nearest node, append **+p**.
54233 {V}
234+ z_only : bool
235+ Only write out the sampled z-values [Default writes all columns].
55236 {f}
237+ {i}
238+ {j}
56239 {n}
57240
58241 Returns
0 commit comments