From 4ba70b1ad09928d051b54d26923d8628e2e443fa Mon Sep 17 00:00:00 2001 From: Wei Ji <23487320+weiji14@users.noreply.github.com> Date: Tue, 6 Apr 2021 20:23:47 +1200 Subject: [PATCH 1/9] Start completing documentation for grdtrack Starting to properly document all major parameters for `grdtrack` as per upstream GMT docs at https://docs.generic-mapping-tools.org/6.1/grdtrack. Begin by adding long aliases for resampling (A), cross_profile (C), profile (E), and common aliases region (R) and distcalc (j). --- pygmt/src/grdtrack.py | 101 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 94 insertions(+), 7 deletions(-) diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index eaa1f0e13cc..d86af489772 100644 --- a/pygmt/src/grdtrack.py +++ b/pygmt/src/grdtrack.py @@ -9,23 +9,38 @@ build_arg_string, data_kind, dummy_context, + kwargs_to_strings, fmt_docstring, use_alias, ) @fmt_docstring -@use_alias(V="verbose", f="coltypes", n="interpolation") +@use_alias( + A="resampling", + C="cross_profile", + E="profile", + R="region", + V="verbose", + f="coltypes", + j="distcalc", + n="interpolation", +) +@kwargs_to_strings(R="sequence") def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): """ Sample grids at specified (x,y) locations. - Grdtrack reads one or more grid files and a table with (x,y) [or (lon,lat)] - positions in the first two columns (more columns may be present). It - interpolates the grid(s) at the positions in the table and writes out the - table with the interpolated values added as (one or more) new columns. A - bicubic [Default], bilinear, B-spline or nearest-neighbor interpolation is - used, requiring boundary conditions at the limits of the region (see + Reads one or more grid files and a table (from file or an array input; but + see ``profile`` for exception) with (x,y) [or (lon,lat)] positions in the + first two columns (more columns may be present). It interpolates the + grid(s) at the positions in the table and writes out the table with the + interpolated values added as (one or more) new columns. Alternatively + (``cross_profile``), the input is considered to be line-segments and we + create orthogonal cross-profiles at each data point or with an equidistant + separation and sample the grid(s) along these profiles. A bicubic + [Default], bilinear, B-spline or nearest-neighbor interpolation is used, + requiring boundary conditions at the limits of the region (see ``interpolation``; Default uses "natural" conditions (second partial derivative normal to edge is zero) unless the grid is automatically recognized as periodic.) @@ -54,8 +69,80 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): Required if ``points`` is a file. The file name for the output ASCII file. + resampling : str + **f**\|\ **p**\|\ **m**\|\ **r**\|\ **R**\ [**+l**] + For track resampling (if ``cross_profile`` or ``profile`` are set) we + can select how this is to be performed. Append **f** to keep original + points, but add intermediate points if needed [Default], **m** as + **f**, but first follow meridian (along y) then parallel (along x), + **p** as **f**, but first follow parallel (along y) then meridian + (along x), **r** to resample at equidistant locations; input points are + not necessarily included in the output, and **R** as **r**, but adjust + given spacing to fit the track length exactly. Finally, append + **+l** if geographic distances should be measured along rhumb lines + (loxodromes) instead of great circles. Ignored unless ``cross_profile`` + is used. + cross_profile : str + *length*/\ *ds*\ [*/spacing*][**+a**\|\ **+v**][**l**\|\ **r**]. + Use input line segments to create an equidistant and (optionally) + equally-spaced set of crossing profiles along which we sample the + grid(s) [Default simply samples the grid(s) at the input locations]. + Specify two length scales that control how the sampling is done: + *length* sets the full length of each cross-profile, while *ds* is + the sampling spacing along each cross-profile. Optionally, append + **/**\ *spacing* for an equidistant spacing between cross-profiles + [Default erects cross-profiles at the input coordinates]; see + ``resampling`` for how resampling the input track is controlled. By + default, all cross-profiles have the same direction (left to right + as we look in the direction of the input line segment). Append **+a** + to alternate the direction of cross-profiles, or **v** to enforce + either a "west-to-east" or "south-to-north" view. By default the entire + profiles are output. Choose to only output the left or right halves + of the profiles by appending **+l** or **+r**, respectively. Append + suitable units to *length*; it sets the unit used for *ds* [and + *spacing*] (See :gmt-docs:`Units `). The default + unit for geographic grids is meter while Cartesian grids implies the + user unit. The output columns will be *lon*, *lat*, *dist*, *azimuth*, + *z1*, *z2*, ..., *zn* (The *zi* are the sampled values for each of the + *n* grids). + profile : str + *line*\ [,\ *line*,...][**+a**\ *az*][**+c**][**+d**][**+g**]\ + [**+i**\ *inc*][**+l**\ *length*][**+n**\ *np*][**+o**\ *az*]\ + [**+r**\ *radius*]. + Instead of reading input track coordinates, specify profiles via + coordinates and modifiers. The format of each *line* is + *start*/*stop*, where *start* or *stop* are either *lon*/*lat* (*x*/*y* + for Cartesian data) or a 2-character XY key that uses the + :gmt-docs:`text `-style justification format to specify + a point on the map as [LCR][BMT]. Each line will be a separate segment + unless **+c** is used which will connect segments with shared joints + into a single segment. In addition to line coordinates, you can use Z-, + Z+ to mean the global minimum and maximum locations in the grid (only + available if a single grid is given via **outfile**). You may append + **+i**\ *inc* to set the sampling interval; if not given then we + default to half the minimum grid interval. For a *line* along parallels + or meridians you can add **+g** to report degrees of longitude or + latitude instead of great circle distances starting at zero. Instead of + two coordinates you can specify an origin and one of **+a**, **+o**, or + **+r**. The **+a** sets the azimuth of a profile of given length + starting at the given origin, while **+o** centers the profile on the + origin; both require **+l**. For circular sampling specify **+r** to + define a circle of given radius centered on the origin; this option + requires either **+n** or **+i**. The **+n**\ *np* modifier sets the + desired number of points, while **+l**\ *length* gives the total length + of the profile. Append **+d** to output the along-track distances after + the coordinates. **Note**: No track file will be read. Also note that + only one distance unit can be chosen. Giving different units will + result in an error. If no units are specified we default to great + circle distances in km (if geographic). If working with geographic data + you can use ``distcalc`` to control distance calculation mode [Default + is Great Circle]. **Note**: If ``cross_profile`` is set and *spacing* + is given then that sampling scheme overrules any modifier set in + ``profile``. + {R} {V} {f} + {j} {n} Returns From 962acfd93f4bd64eb4e462083c55e22b77686057 Mon Sep 17 00:00:00 2001 From: Wei Ji <23487320+weiji14@users.noreply.github.com> Date: Thu, 8 Apr 2021 13:03:53 +1200 Subject: [PATCH 2/9] Rename cross_profile alias to crossprofile --- pygmt/src/grdtrack.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index d86af489772..534cb3b30cc 100644 --- a/pygmt/src/grdtrack.py +++ b/pygmt/src/grdtrack.py @@ -18,7 +18,7 @@ @fmt_docstring @use_alias( A="resampling", - C="cross_profile", + C="crossprofile", E="profile", R="region", V="verbose", @@ -36,7 +36,7 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): first two columns (more columns may be present). It interpolates the grid(s) at the positions in the table and writes out the table with the interpolated values added as (one or more) new columns. Alternatively - (``cross_profile``), the input is considered to be line-segments and we + (``crossprofile``), the input is considered to be line-segments and we create orthogonal cross-profiles at each data point or with an equidistant separation and sample the grid(s) along these profiles. A bicubic [Default], bilinear, B-spline or nearest-neighbor interpolation is used, @@ -71,7 +71,7 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): resampling : str **f**\|\ **p**\|\ **m**\|\ **r**\|\ **R**\ [**+l**] - For track resampling (if ``cross_profile`` or ``profile`` are set) we + For track resampling (if ``crossprofile`` or ``profile`` are set) we can select how this is to be performed. Append **f** to keep original points, but add intermediate points if needed [Default], **m** as **f**, but first follow meridian (along y) then parallel (along x), @@ -80,9 +80,9 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): not necessarily included in the output, and **R** as **r**, but adjust given spacing to fit the track length exactly. Finally, append **+l** if geographic distances should be measured along rhumb lines - (loxodromes) instead of great circles. Ignored unless ``cross_profile`` + (loxodromes) instead of great circles. Ignored unless ``crossprofile`` is used. - cross_profile : str + crossprofile : str *length*/\ *ds*\ [*/spacing*][**+a**\|\ **+v**][**l**\|\ **r**]. Use input line segments to create an equidistant and (optionally) equally-spaced set of crossing profiles along which we sample the @@ -136,8 +136,8 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): result in an error. If no units are specified we default to great circle distances in km (if geographic). If working with geographic data you can use ``distcalc`` to control distance calculation mode [Default - is Great Circle]. **Note**: If ``cross_profile`` is set and *spacing* - is given then that sampling scheme overrules any modifier set in + is Great Circle]. **Note**: If ``crossprofile`` is set and *spacing* is + given then that sampling scheme overrules any modifier set in ``profile``. {R} {V} From f3b324db847bcfb3f1472186f59c8857e2fb3381 Mon Sep 17 00:00:00 2001 From: Wei Ji <23487320+weiji14@users.noreply.github.com> Date: Thu, 8 Apr 2021 13:07:25 +1200 Subject: [PATCH 3/9] Alias no_skip (N) and z_only (Z) for grdtrack --- pygmt/src/grdtrack.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index 534cb3b30cc..892e2f328a6 100644 --- a/pygmt/src/grdtrack.py +++ b/pygmt/src/grdtrack.py @@ -21,7 +21,9 @@ C="crossprofile", E="profile", R="region", + N="no_skip", V="verbose", + Z="z_only", f="coltypes", j="distcalc", n="interpolation", @@ -140,7 +142,12 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): given then that sampling scheme overrules any modifier set in ``profile``. {R} + no_skip : bool + Do *not* skip points that fall outside the domain of the grid(s) + [Default only output points within grid domain]. {V} + z_only : bool + Only write out the sampled z-values [Default writes all columns]. {f} {j} {n} From bae11a6cc170d52536bbe0ab6753efb50cfd7f34 Mon Sep 17 00:00:00 2001 From: Wei Ji <23487320+weiji14@users.noreply.github.com> Date: Tue, 18 May 2021 10:03:00 +1200 Subject: [PATCH 4/9] Alias dfile (D) for grdtrack --- pygmt/src/grdtrack.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index e37c60c6119..9ca377ab104 100644 --- a/pygmt/src/grdtrack.py +++ b/pygmt/src/grdtrack.py @@ -18,6 +18,7 @@ @use_alias( A="resampling", C="crossprofile", + D="dfile", E="profile", R="region", N="no_skip", @@ -104,6 +105,11 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): user unit. The output columns will be *lon*, *lat*, *dist*, *azimuth*, *z1*, *z2*, ..., *zn* (The *zi* are the sampled values for each of the *n* grids). + dfile : str + In concert with ``crossprofile`` we can save the (possibly resampled) + original lines to *dfile* [Default only saves the cross-profiles]. The + columns will be *lon*, *lat*, *dist*, *azimuth*, *z1*, *z2*, ... + (sampled value for each grid). profile : str *line*\ [,\ *line*,...][**+a**\ *az*][**+c**][**+d**][**+g**]\ [**+i**\ *inc*][**+l**\ *length*][**+n**\ *np*][**+o**\ *az*]\ From 4d58d0f4cc4fd6049c1a05acfbdc2f2ebb1060af Mon Sep 17 00:00:00 2001 From: Wei Ji <23487320+weiji14@users.noreply.github.com> Date: Tue, 18 May 2021 10:27:38 +1200 Subject: [PATCH 5/9] Alias critical (F) for grdtrack --- pygmt/src/grdtrack.py | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index 9ca377ab104..46204b5e1bf 100644 --- a/pygmt/src/grdtrack.py +++ b/pygmt/src/grdtrack.py @@ -8,8 +8,8 @@ GMTTempFile, build_arg_string, data_kind, - kwargs_to_strings, fmt_docstring, + kwargs_to_strings, use_alias, ) @@ -20,6 +20,7 @@ C="crossprofile", D="dfile", E="profile", + F="critical", R="region", N="no_skip", V="verbose", @@ -30,7 +31,7 @@ ) @kwargs_to_strings(R="sequence") def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): - """ + r""" Sample grids at specified (x,y) locations. Reads one or more grid files and a table (from file or an array input; but @@ -144,6 +145,30 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): is Great Circle]. **Note**: If ``crossprofile`` is set and *spacing* is given then that sampling scheme overrules any modifier set in ``profile``. + critical : str + [**+b**][**+n**][**+r**][**+z**\ *z0*]. + Find critical points along each cross-profile as a function of + along-track distance. Requires ``crossprofile`` and a single input grid + (*z*). We examine each cross-profile generated and report (*dist*, + *lonc*, *latc*, *distc*, *azimuthc*, *zc*) at the center peak of + maximum *z* value, (*lonl*, *latl*, *distl*) and (*lonr*, *latr*, + *distr*) at the first and last non-NaN point whose *z*-value exceeds + *z0*, respectively, and the *width* based on the two extreme points + found. Here, *dist* is the distance along the original input + ``points`` and the other 12 output columns are a function of that + distance. When searching for the center peak and the extreme first and + last values that exceed the threshold we assume the profile is positive + up. If we instead are looking for a trough then you must use **+n** to + temporarily flip the profile to positive. The threshold *z0* value is + always given as >= 0; use **+z** to change it [Default is 0]. + Alternatively, use **+b** to determine the balance point and standard + deviation of the profile; this is the weighted mean and weighted + standard deviation of the distances, with *z* acting as the weight. + Finally, use **+r** to obtain the weighted rms about the cross-track + center (*distc* == 0). **Note**: We round the exact results to the + nearest distance nodes along the cross-profiles. We write 13 output + columns per track: *dist, lonc, latc, distc, azimuthc, zc, lonl, latl, + distl, lonr, latr, distr, width*. {R} no_skip : bool Do *not* skip points that fall outside the domain of the grid(s) From 8075cbf63f41dd482d1e7ffbe730e7d9babb9e9b Mon Sep 17 00:00:00 2001 From: Wei Ji <23487320+weiji14@users.noreply.github.com> Date: Tue, 18 May 2021 10:35:41 +1200 Subject: [PATCH 6/9] Alias stack (S) for grdtrack --- pygmt/src/grdtrack.py | 45 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index 46204b5e1bf..108a94a9ad6 100644 --- a/pygmt/src/grdtrack.py +++ b/pygmt/src/grdtrack.py @@ -23,13 +23,14 @@ F="critical", R="region", N="no_skip", + S="stack", V="verbose", Z="z_only", f="coltypes", j="distcalc", n="interpolation", ) -@kwargs_to_strings(R="sequence") +@kwargs_to_strings(R="sequence", S="sequence") def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): r""" Sample grids at specified (x,y) locations. @@ -173,6 +174,48 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): no_skip : bool Do *not* skip points that fall outside the domain of the grid(s) [Default only output points within grid domain]. + stack : str or list + *method*/*modifiers*. + In conjunction with ``crossprofile``, compute a single stacked profile + from all profiles across each segment. Choose how stacking should be + computed [Default method is **a**]: + + - **a** = mean (average) + - **m** = median + - **p** = mode (maximum likelihood) + - **l** = lower + - **L** = lower but only consider positive values + - **u** = upper + - **U** = upper but only consider negative values. + + The *modifiers* control the output; choose one or more among these + choices: + + - **+a** : Append stacked values to all cross-profiles. + - **+d** : Append stack deviations to all cross-profiles. + - **+r** : Append data residuals (data - stack) to all cross-profiles. + - **+s**\ [*file*] : Save stacked profile to *file* [Default filename + is grdtrack_stacked_profile.txt]. + - **+c**\ *fact* : Compute envelope on stacked profile as + ±\ *fact* \*\ *deviation* [Default fact value is 2]. + + Notes: + + 1. Deviations depend on *method* and are st.dev (**a**), L1 scale, + i.e., 1.4826 \* median absolute deviation (MAD) (for **m** and + **p**), or half-range (upper-lower)/2. + 2. The stacked profile file contains a leading column plus groups of + 4-6 columns, with one group for each sampled grid. The leading + column holds cross distance, while the first four columns in a group + hold stacked value, deviation, min value, and max value, + respectively. If *method* is one of **a**\|\ **m**\|\ **p** then we + also write the lower and upper confidence bounds (see **+c**). When + one or more of **+a**, **+d**, and **+r** are used then we also + append the stacking results to the end of each row, for all + cross-profiles. The order is always stacked value (**+a**), followed + by deviations (**+d**) and finally residuals (**+r**). When more + than one grid is sampled this sequence of 1-3 columns is repeated + for each grid. {V} z_only : bool Only write out the sampled z-values [Default writes all columns]. From 197da51944d236cb05f8d7abd6b9408f909b0f42 Mon Sep 17 00:00:00 2001 From: Wei Ji <23487320+weiji14@users.noreply.github.com> Date: Tue, 18 May 2021 10:39:13 +1200 Subject: [PATCH 7/9] Alias radius (T) for grdtrack --- pygmt/src/grdtrack.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index 108a94a9ad6..35d6f721401 100644 --- a/pygmt/src/grdtrack.py +++ b/pygmt/src/grdtrack.py @@ -24,6 +24,7 @@ R="region", N="no_skip", S="stack", + T="radius", V="verbose", Z="z_only", f="coltypes", @@ -216,6 +217,18 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): by deviations (**+d**) and finally residuals (**+r**). When more than one grid is sampled this sequence of 1-3 columns is repeated for each grid. + radius : bool or int or float or str + [*radius*][**+e**\|\ **p**]. + To be used with normal grid sampling, and limited to a single, non-IMG + grid. If the nearest node to the input point is NaN, search outwards + until we find the nearest non-NaN node and report that value instead. + Optionally specify a search radius which limits the consideration to + points within this distance from the input point. To report the + location of the nearest node and its distance from the input point, + append **+e**. The default unit for geographic grid distances is + spherical degrees. Use *radius* to change the unit and give *radius* = + 0 if you do not want to limit the radius search. To instead replace the + input point with the coordinates of the nearest node, append **+p**. {V} z_only : bool Only write out the sampled z-values [Default writes all columns]. From c022979482a23c4cf61b66ecb057f25f5f6a0ee9 Mon Sep 17 00:00:00 2001 From: Wei Ji <23487320+weiji14@users.noreply.github.com> Date: Fri, 28 May 2021 11:35:46 +1200 Subject: [PATCH 8/9] Alias incols (i) for grdtrack --- pygmt/src/grdtrack.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index 35d6f721401..041b41d1476 100644 --- a/pygmt/src/grdtrack.py +++ b/pygmt/src/grdtrack.py @@ -28,6 +28,7 @@ V="verbose", Z="z_only", f="coltypes", + i="incols", j="distcalc", n="interpolation", ) @@ -233,6 +234,7 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): z_only : bool Only write out the sampled z-values [Default writes all columns]. {f} + {i} {j} {n} From c10eba6d79d4b622fe01f0a5e330533e21a2afdf Mon Sep 17 00:00:00 2001 From: Wei Ji <23487320+weiji14@users.noreply.github.com> Date: Mon, 31 May 2021 16:29:34 +1200 Subject: [PATCH 9/9] Rename alias resampling to resample (A) Co-Authored-By: Meghan Jones --- pygmt/src/grdtrack.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index 041b41d1476..e931b7be3ea 100644 --- a/pygmt/src/grdtrack.py +++ b/pygmt/src/grdtrack.py @@ -16,7 +16,7 @@ @fmt_docstring @use_alias( - A="resampling", + A="resample", C="crossprofile", D="dfile", E="profile", @@ -73,7 +73,7 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): outfile : str The file name for the output ASCII file. - resampling : str + resample : str **f**\|\ **p**\|\ **m**\|\ **r**\|\ **R**\ [**+l**] For track resampling (if ``crossprofile`` or ``profile`` are set) we can select how this is to be performed. Append **f** to keep original @@ -96,7 +96,7 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): the sampling spacing along each cross-profile. Optionally, append **/**\ *spacing* for an equidistant spacing between cross-profiles [Default erects cross-profiles at the input coordinates]; see - ``resampling`` for how resampling the input track is controlled. By + ``resample`` for how resampling the input track is controlled. By default, all cross-profiles have the same direction (left to right as we look in the direction of the input line segment). Append **+a** to alternate the direction of cross-profiles, or **v** to enforce