From ef08ced8da69ff444923da16a8b21f90000bfa13 Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Sun, 12 Sep 2021 17:21:56 -0400 Subject: [PATCH 01/17] update parameters for grdgradient --- pygmt/src/grdgradient.py | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 124adf882f5..1dff80426a7 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -21,7 +21,10 @@ D="direction", E="radiance", G="outgrid", + N="normalize", + Q="norm_control", R="region", + S="slopefile", V="verbose", n="interpolation", ) @@ -89,6 +92,39 @@ def grdgradient(grid, **kwargs): algorithm; in this case the *azim* and *elev* are hardwired to 315 and 45 degrees. This means that even if you provide other values they will be ignored.) + normalize : str or bool + [**e**\|\ **t**][*amp*][**+a**\ *ambient*][**+s**\ *sigma*] + [**+o**\ *offset*]. + The actual gradients *g* are offset and scaled to produce normalized + gradients *gn* with a + maximum output magnitude of *amp*. If *amp* is not given, default + *amp* = 1. If *offset* is not given, it is set to the average of + *g*. **True** yields *gn* = *amp* \* (*g* - *offset*)/max(abs(\ *g* - + *offset*)). **-Ne** normalizes using a cumulative Laplace + distribution yielding *gn* = *amp* \* (1.0 - + exp(sqrt(2) \* (*g* - *offset*)/ *sigma*)), where + *sigma* is estimated using the L1 norm of (*g* - *offset*) if it is + not given. **-Nt** normalizes using a cumulative Cauchy distribution + yielding *gn* = (2 \* *amp* / PI) \* atan( (*g* - *offset*)/ + *sigma*) where *sigma* is estimated using the L2 norm of (*g* - + *offset*) if it is not given. To use *offset* and/or *sigma* from a + previous calculation, leave out the argument to the modifier(s) and + see **-Q** for usage. As a final option, you may add **+a**\ *ambient* + to add *ambient* to all nodes after gradient calculations are completed. + norm_control : str + **c**\|\ **r**\|\ **R** + Controls how normalization via **-N** is carried out. When multiple grids + should be normalized the same way (i.e., with the same *offset* and/or *sigma*), + we must pass these values via **-N**. However, this is inconvenient if we + compute these values from a grid. Use **-Qc** to save the results of + *offset* and *sigma* to a statistics file; if grid output is not needed + for this run then do not specify **-G**. For subsequent runs, just use + **-Qr** to read these values. Using **-QR** will read then delete the + statistics file. See TILES for more information. + slopefile : str + Name of output grid file with scalar magnitudes of gradient vectors. + Requires **-D** but makes **-G** optional. + {R} {V} {n} From 0e3a9ac1639b166236eea94e59bf8e209167c472 Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Thu, 16 Sep 2021 19:54:58 -0400 Subject: [PATCH 02/17] update docstrings --- pygmt/src/grdgradient.py | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 1dff80426a7..e7ec2e0d15b 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -110,20 +110,23 @@ def grdgradient(grid, **kwargs): *offset*) if it is not given. To use *offset* and/or *sigma* from a previous calculation, leave out the argument to the modifier(s) and see **-Q** for usage. As a final option, you may add **+a**\ *ambient* - to add *ambient* to all nodes after gradient calculations are completed. + to add *ambient* to all nodes after gradient calculations are + completed. norm_control : str **c**\|\ **r**\|\ **R** - Controls how normalization via **-N** is carried out. When multiple grids - should be normalized the same way (i.e., with the same *offset* and/or *sigma*), - we must pass these values via **-N**. However, this is inconvenient if we - compute these values from a grid. Use **-Qc** to save the results of - *offset* and *sigma* to a statistics file; if grid output is not needed - for this run then do not specify **-G**. For subsequent runs, just use - **-Qr** to read these values. Using **-QR** will read then delete the - statistics file. See TILES for more information. + Controls how normalization via **-N** is carried out. When multiple + grids should be normalized the same way (i.e., with the same *offset* + and/or *sigma*), + we must pass these values via `normalize`. However, this is + inconvenient if we compute these values from a grid. Use **c** to save + the results of *offset* and *sigma* to a statistics file; if grid + output is not needed for this run then do not specify `outgrid`. For + subsequent runs, just use **r** to read these values. Using **R** + will read then delete the statistics file. See TILES for more + information. slopefile : str Name of output grid file with scalar magnitudes of gradient vectors. - Requires **-D** but makes **-G** optional. + Requires `direction` but makes `outgrid` optional. {R} {V} From 4f9ee59482eb9247e477ce988be38695849fed19 Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Thu, 16 Sep 2021 20:08:48 -0400 Subject: [PATCH 03/17] update docstrings --- pygmt/src/grdgradient.py | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index e7ec2e0d15b..6a65dc0cf60 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -100,34 +100,32 @@ def grdgradient(grid, **kwargs): maximum output magnitude of *amp*. If *amp* is not given, default *amp* = 1. If *offset* is not given, it is set to the average of *g*. **True** yields *gn* = *amp* \* (*g* - *offset*)/max(abs(\ *g* - - *offset*)). **-Ne** normalizes using a cumulative Laplace + *offset*)). **e** normalizes using a cumulative Laplace distribution yielding *gn* = *amp* \* (1.0 - exp(sqrt(2) \* (*g* - *offset*)/ *sigma*)), where *sigma* is estimated using the L1 norm of (*g* - *offset*) if it is - not given. **-Nt** normalizes using a cumulative Cauchy distribution + not given. **t** normalizes using a cumulative Cauchy distribution yielding *gn* = (2 \* *amp* / PI) \* atan( (*g* - *offset*)/ *sigma*) where *sigma* is estimated using the L2 norm of (*g* - *offset*) if it is not given. To use *offset* and/or *sigma* from a previous calculation, leave out the argument to the modifier(s) and - see **-Q** for usage. As a final option, you may add **+a**\ *ambient* - to add *ambient* to all nodes after gradient calculations are - completed. + see `norm_control` for usage. As a final option, you may add **+a**\ + *ambient* to add *ambient* to all nodes after gradient calculations + are completed. norm_control : str **c**\|\ **r**\|\ **R** - Controls how normalization via **-N** is carried out. When multiple - grids should be normalized the same way (i.e., with the same *offset* - and/or *sigma*), + Controls how normalization via `normalize` is carried out. When + multiple grids should be normalized the same way (i.e., with the same + *offset* and/or *sigma*), we must pass these values via `normalize`. However, this is - inconvenient if we compute these values from a grid. Use **c** to save - the results of *offset* and *sigma* to a statistics file; if grid - output is not needed for this run then do not specify `outgrid`. For - subsequent runs, just use **r** to read these values. Using **R** - will read then delete the statistics file. See TILES for more - information. + inconvenient if we compute these values from a grid. Use **c** to + save the results of *offset* and *sigma* to a statistics file; if + grid output is not needed for this run then do not specify `outgrid`. + For subsequent runs, just use **r** to read these values. Using + **R** will read then delete the statistics file. slopefile : str Name of output grid file with scalar magnitudes of gradient vectors. Requires `direction` but makes `outgrid` optional. - {R} {V} {n} From d6a3c1bef6caea1481acdf384f4c1e58f6f28b1c Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Tue, 5 Oct 2021 19:49:50 +0100 Subject: [PATCH 04/17] remove trailing whitespace --- pygmt/src/grdgradient.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 6a65dc0cf60..917a82908f5 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -95,7 +95,7 @@ def grdgradient(grid, **kwargs): normalize : str or bool [**e**\|\ **t**][*amp*][**+a**\ *ambient*][**+s**\ *sigma*] [**+o**\ *offset*]. - The actual gradients *g* are offset and scaled to produce normalized + The actual gradients *g* are offset and scaled to produce normalized gradients *gn* with a maximum output magnitude of *amp*. If *amp* is not given, default *amp* = 1. If *offset* is not given, it is set to the average of @@ -109,19 +109,19 @@ def grdgradient(grid, **kwargs): *sigma*) where *sigma* is estimated using the L2 norm of (*g* - *offset*) if it is not given. To use *offset* and/or *sigma* from a previous calculation, leave out the argument to the modifier(s) and - see `norm_control` for usage. As a final option, you may add **+a**\ - *ambient* to add *ambient* to all nodes after gradient calculations - are completed. + see `norm_control` for usage. As a final option, you may add + **+a**\ *ambient* to add *ambient* to all nodes after gradient + calculations are completed. norm_control : str **c**\|\ **r**\|\ **R** - Controls how normalization via `normalize` is carried out. When - multiple grids should be normalized the same way (i.e., with the same + Controls how normalization via `normalize` is carried out. When + multiple grids should be normalized the same way (i.e., with the same *offset* and/or *sigma*), - we must pass these values via `normalize`. However, this is - inconvenient if we compute these values from a grid. Use **c** to - save the results of *offset* and *sigma* to a statistics file; if - grid output is not needed for this run then do not specify `outgrid`. - For subsequent runs, just use **r** to read these values. Using + we must pass these values via `normalize`. However, this is + inconvenient if we compute these values from a grid. Use **c** to + save the results of *offset* and *sigma* to a statistics file; if + grid output is not needed for this run then do not specify `outgrid`. + For subsequent runs, just use **r** to read these values. Using **R** will read then delete the statistics file. slopefile : str Name of output grid file with scalar magnitudes of gradient vectors. From fda8fadcfab2124cd33175a8d633c95148a6639b Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Mon, 11 Oct 2021 16:07:26 +0100 Subject: [PATCH 05/17] Apply suggestions from code review Co-authored-by: Meghan Jones --- pygmt/src/grdgradient.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 917a82908f5..f8b5902cd76 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -24,7 +24,7 @@ N="normalize", Q="norm_control", R="region", - S="slopefile", + S="slope_file", V="verbose", n="interpolation", ) @@ -123,7 +123,7 @@ def grdgradient(grid, **kwargs): grid output is not needed for this run then do not specify `outgrid`. For subsequent runs, just use **r** to read these values. Using **R** will read then delete the statistics file. - slopefile : str + slope_file : str Name of output grid file with scalar magnitudes of gradient vectors. Requires `direction` but makes `outgrid` optional. {R} From 6ccf844f3fea17e2ba2f8cd53affde0a5bc74f73 Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Mon, 11 Oct 2021 16:55:59 +0100 Subject: [PATCH 06/17] add Q/N check --- pygmt/src/grdgradient.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index f8b5902cd76..81324605314 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -140,6 +140,10 @@ def grdgradient(grid, **kwargs): ``outgrid``) """ with GMTTempFile(suffix=".nc") as tmpfile: + if "Q" in kwargs and "N" not in kwargs: + raise GMTInvalidInput( + """Must specify normalize if norm_control is specified.""" + ) if not args_in_kwargs(args=["A", "D", "E"], kwargs=kwargs): raise GMTInvalidInput( """At least one of the following parameters must be specified: From 728e4bc078fee9ffd8e019966cad86a01f1e08af Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Thu, 21 Oct 2021 21:10:57 +0100 Subject: [PATCH 07/17] Update pygmt/src/grdgradient.py Co-authored-by: Michael Grund <23025878+michaelgrund@users.noreply.github.com> --- pygmt/src/grdgradient.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 81324605314..96f1c72069c 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -89,7 +89,7 @@ def grdgradient(grid, **kwargs): simpler Lambertian algorithm. Note that with this form you only have to provide azimuth and elevation. Alternatively, use **p** for the Peucker piecewise linear approximation (simpler but faster - algorithm; in this case the *azim* and *elev* are hardwired to 315 + algorithm; in this case *azim* and *elev* are hardwired to 315 and 45 degrees. This means that even if you provide other values they will be ignored.) normalize : str or bool From 1026224cae6ab5e80882456f47ff170025af165d Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Wed, 27 Oct 2021 21:09:01 +0100 Subject: [PATCH 08/17] rename "norm_control" to "tiles" --- pygmt/src/grdgradient.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 96f1c72069c..621074d38bb 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -22,7 +22,7 @@ E="radiance", G="outgrid", N="normalize", - Q="norm_control", + Q="tiles", R="region", S="slope_file", V="verbose", @@ -109,10 +109,10 @@ def grdgradient(grid, **kwargs): *sigma*) where *sigma* is estimated using the L2 norm of (*g* - *offset*) if it is not given. To use *offset* and/or *sigma* from a previous calculation, leave out the argument to the modifier(s) and - see `norm_control` for usage. As a final option, you may add + see `tiles` for usage. As a final option, you may add **+a**\ *ambient* to add *ambient* to all nodes after gradient calculations are completed. - norm_control : str + tiles : str **c**\|\ **r**\|\ **R** Controls how normalization via `normalize` is carried out. When multiple grids should be normalized the same way (i.e., with the same @@ -142,7 +142,7 @@ def grdgradient(grid, **kwargs): with GMTTempFile(suffix=".nc") as tmpfile: if "Q" in kwargs and "N" not in kwargs: raise GMTInvalidInput( - """Must specify normalize if norm_control is specified.""" + """Must specify normalize if tiles is specified.""" ) if not args_in_kwargs(args=["A", "D", "E"], kwargs=kwargs): raise GMTInvalidInput( From d53c61bc768dd54a28871cafc0f1fec2a866188d Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Wed, 27 Oct 2021 21:09:39 +0100 Subject: [PATCH 09/17] run make format --- pygmt/src/grdgradient.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 621074d38bb..32b40864254 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -141,9 +141,7 @@ def grdgradient(grid, **kwargs): """ with GMTTempFile(suffix=".nc") as tmpfile: if "Q" in kwargs and "N" not in kwargs: - raise GMTInvalidInput( - """Must specify normalize if tiles is specified.""" - ) + raise GMTInvalidInput("""Must specify normalize if tiles is specified.""") if not args_in_kwargs(args=["A", "D", "E"], kwargs=kwargs): raise GMTInvalidInput( """At least one of the following parameters must be specified: From b482f1c822146f73554194481efc69f03ad55aab Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Thu, 28 Oct 2021 07:11:22 +0100 Subject: [PATCH 10/17] Apply suggestions from code review Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> --- pygmt/src/grdgradient.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 32b40864254..2819dd3195b 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -26,6 +26,7 @@ R="region", S="slope_file", V="verbose", + f="coltypes", n="interpolation", ) @kwargs_to_strings(A="sequence", E="sequence", R="sequence") @@ -113,7 +114,7 @@ def grdgradient(grid, **kwargs): **+a**\ *ambient* to add *ambient* to all nodes after gradient calculations are completed. tiles : str - **c**\|\ **r**\|\ **R** + **c**\|\ **r**\|\ **R**. Controls how normalization via `normalize` is carried out. When multiple grids should be normalized the same way (i.e., with the same *offset* and/or *sigma*), @@ -128,6 +129,7 @@ def grdgradient(grid, **kwargs): Requires `direction` but makes `outgrid` optional. {R} {V} + {f} {n} Returns From b20fca7eeffa03f7d9d8306925ce6da91ad1264e Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Thu, 28 Oct 2021 07:15:07 +0100 Subject: [PATCH 11/17] add test that grdgradient fails when tiles is specified but not normalize --- pygmt/tests/test_grdgradient.py | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/pygmt/tests/test_grdgradient.py b/pygmt/tests/test_grdgradient.py index 4b01038ab6b..71a13f072b2 100644 --- a/pygmt/tests/test_grdgradient.py +++ b/pygmt/tests/test_grdgradient.py @@ -55,8 +55,13 @@ def test_grdgradient_no_outgrid(grid): def test_grdgradient_fails(grid): """ - Check that grdgradient fails correctly when neither of azimuth, direction - or radiance is given. + Check that grdgradient fails correctly + + Check that grdgradient fails correctly when `tiles` is specified but + normalize is not. """ with pytest.raises(GMTInvalidInput): - grdgradient(grid=grid) + grdgradient(grid=grid) # fails without required arguments + with pytest.raises(GMTInvalidInput): + # failes when tiles is specified but not normalize + grdgradient(grid=grid, azimuth=10, direction="c", tiles="c") From 9a6ed3bd00743c153ee60fe77001c84c5bad8bdc Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Thu, 28 Oct 2021 07:16:57 +0100 Subject: [PATCH 12/17] run make format --- pygmt/tests/test_grdgradient.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/tests/test_grdgradient.py b/pygmt/tests/test_grdgradient.py index 71a13f072b2..0407c09de1e 100644 --- a/pygmt/tests/test_grdgradient.py +++ b/pygmt/tests/test_grdgradient.py @@ -55,13 +55,13 @@ def test_grdgradient_no_outgrid(grid): def test_grdgradient_fails(grid): """ - Check that grdgradient fails correctly + Check that grdgradient fails correctly. Check that grdgradient fails correctly when `tiles` is specified but normalize is not. """ with pytest.raises(GMTInvalidInput): - grdgradient(grid=grid) # fails without required arguments + grdgradient(grid=grid) # fails without required arguments with pytest.raises(GMTInvalidInput): # failes when tiles is specified but not normalize grdgradient(grid=grid, azimuth=10, direction="c", tiles="c") From cc39c62b7f54edb815fdb1a0fbd4eae0c0ead804 Mon Sep 17 00:00:00 2001 From: meghanrjones Date: Thu, 28 Oct 2021 11:35:18 -0400 Subject: [PATCH 13/17] Format with lists and LaTeX math --- pygmt/src/grdgradient.py | 82 ++++++++++++++++++++++------------------ 1 file changed, 45 insertions(+), 37 deletions(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 2819dd3195b..bf4590330f3 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -53,15 +53,16 @@ def grdgradient(grid, **kwargs): Azimuthal direction for a directional derivative; *azim* is the angle in the x,y plane measured in degrees positive clockwise from north (the +y direction) toward east (the +x direction). The - negative of the directional derivative, -[dz/dx\*sin(*azim*) + - dz/dy\*cos(\ *azim*)], is found; negation yields positive values - when the slope of z(x,y) is downhill in the *azim* direction, the - correct sense for shading the illumination of an image by a light - source above the x,y plane shining from the *azim* direction. - Optionally, supply two azimuths, *azim*/*azim2*, in which case the - gradients in each of these directions are calculated and the one - larger in magnitude is retained; this is useful for illuminating data - with two directions of lineated structures, e.g., *0*/*270* + negative of the directional derivative, + :math:`-(\frac{{dz}}{{dx}}\sin(\mbox{{azim}}) + \ + \frac{{dz}}{{dy}}\cos(\mbox{{azim}}))`, is found; negation yields + positive values when the slope of :math:`z(x,y)` is downhill in the + *azim* direction, the correct sense for shading the illumination of an + image by a light source above the x,y plane shining from the *azim* + direction. Optionally, supply two azimuths, *azim*/*azim2*, in which + case the gradients in each of these directions are calculated and the + one larger in magnitude is retained; this is useful for illuminating + data with two directions of lineated structures, e.g., *0*/*270* illuminates from the north (top) and west (left). Finally, if *azim* is a file it must be a grid of the same domain, spacing and registration as *grid* that will update the azimuth at each output @@ -69,19 +70,21 @@ def grdgradient(grid, **kwargs): direction : str [**a**][**c**][**o**][**n**]. Find the direction of the positive (up-slope) gradient of the data. - To instead find the aspect (the down-slope direction), use **a**. - By default, directions are measured clockwise from north, as *azim* - in ``azimuth``. Append **c** to use conventional Cartesian angles - measured counterclockwise from the positive x (east) direction. - Append **o** to report orientations (0-180) rather than - directions (0-360). Append **n** to add 90 degrees to all angles - (e.g., to give local strikes of the surface). + The following options are supported: + + - **a** - Find the aspect (i.e., the down-slope direction) + - **c** - Use the conventional Cartesian angles measured + counterclockwise from the positive x (east) direction. + - **o** - Report orientations (0-180) rather than directions (0-360). + - **n** - Add 90 degrees to all angles (e.g., to give local strikes of + the surface). radiance : str or list [**m**\|\ **s**\|\ **p**]\ *azim/elev*\ [**+a**\ *ambient*][**+d**\ *diffuse*][**+p**\ *specular*][**+s**\ *shine*]. - Compute Lambertian radiance appropriate to use with ``grdimage`` - and ``grdview``. The Lambertian Reflection assumes an ideal surface - that reflects all the light that strikes it and the surface appears + Compute Lambertian radiance appropriate to use with + :doc:`pygmt.Figure.grdimage` and :doc:`pygmt.Figure.grdview`. The + Lambertian Reflection assumes an ideal surface that reflects all the + light that strikes it and the surface appears equally bright from all viewing directions. Here, *azim* and *elev* are the azimuth and elevation of the light vector. Optionally, supply *ambient* [0.55], *diffuse* [0.6], *specular* [0.4], or *shine* [10], @@ -94,25 +97,30 @@ def grdgradient(grid, **kwargs): and 45 degrees. This means that even if you provide other values they will be ignored.) normalize : str or bool - [**e**\|\ **t**][*amp*][**+a**\ *ambient*][**+s**\ *sigma*] + [**e**\|\ **t**][*amp*][**+a**\ *ambient*][**+s**\ *sigma*]\ [**+o**\ *offset*]. - The actual gradients *g* are offset and scaled to produce normalized - gradients *gn* with a - maximum output magnitude of *amp*. If *amp* is not given, default - *amp* = 1. If *offset* is not given, it is set to the average of - *g*. **True** yields *gn* = *amp* \* (*g* - *offset*)/max(abs(\ *g* - - *offset*)). **e** normalizes using a cumulative Laplace - distribution yielding *gn* = *amp* \* (1.0 - - exp(sqrt(2) \* (*g* - *offset*)/ *sigma*)), where - *sigma* is estimated using the L1 norm of (*g* - *offset*) if it is - not given. **t** normalizes using a cumulative Cauchy distribution - yielding *gn* = (2 \* *amp* / PI) \* atan( (*g* - *offset*)/ - *sigma*) where *sigma* is estimated using the L2 norm of (*g* - - *offset*) if it is not given. To use *offset* and/or *sigma* from a - previous calculation, leave out the argument to the modifier(s) and - see `tiles` for usage. As a final option, you may add - **+a**\ *ambient* to add *ambient* to all nodes after gradient - calculations are completed. + The actual gradients :math:`g` are offset and scaled to produce + normalized gradients math:`g_n` with a maximum output magnitude of + *amp*. If *amp* is not given, default *amp* = 1. If *offset* is not + given, it is set to the average of :math:`g`. The following forms are + supported: + + - **-N** - Normalize using :math:`g_n = \mbox{{amp}}\ + (\frac{{g - \mbox{{offset}}}}{{max(|g - \mbox{{offset}}|)}})` + - **-Ne** - Normalize using a cumulative Laplace distribution yielding: + :math:`g_n = \mbox{{amp}}(1 - \ + \exp{{(\sqrt{{2}}\frac{{g - \mbox{{offset}}}}{{\sigma}}))}}`, where + :math:`\sigma` is estimated using the L1 norm of + :math:`(g - \mbox{{offset}})` if it is not given. + - **-Nt** - Normalize using a cumulative Cauchy distribution yielding: + :math:`g_n = \ + \frac{{2(\mbox{{amp}})}}{{\pi}}(\tan^{{-1}}(\frac{{g - \ + \mbox{{offset}}}}{{\sigma}}))` where :math:`\sigma` is estimated + using the L2 norm of :math:`(g - \mbox{{offset}})` if it is not + given. + + As a final option, you may add **+a**\ *ambient* to add *ambient* to + all nodes after gradient calculations are completed. tiles : str **c**\|\ **r**\|\ **R**. Controls how normalization via `normalize` is carried out. When From 3c702237471c1a1adcc7a108e825591d439a6235 Mon Sep 17 00:00:00 2001 From: Meghan Jones Date: Thu, 28 Oct 2021 12:23:41 -0400 Subject: [PATCH 14/17] Fix formatting --- pygmt/src/grdgradient.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index bf4590330f3..12f0321c527 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -100,7 +100,7 @@ def grdgradient(grid, **kwargs): [**e**\|\ **t**][*amp*][**+a**\ *ambient*][**+s**\ *sigma*]\ [**+o**\ *offset*]. The actual gradients :math:`g` are offset and scaled to produce - normalized gradients math:`g_n` with a maximum output magnitude of + normalized gradients :math:`g_n` with a maximum output magnitude of *amp*. If *amp* is not given, default *amp* = 1. If *offset* is not given, it is set to the average of :math:`g`. The following forms are supported: From 6ddc91b140a722b09ffa1ce694ec6a7da423d4b3 Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Thu, 28 Oct 2021 18:28:27 +0100 Subject: [PATCH 15/17] Apply suggestions from code review Co-authored-by: Michael Grund <23025878+michaelgrund@users.noreply.github.com> Co-authored-by: Meghan Jones --- pygmt/src/grdgradient.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 12f0321c527..9fba4f0ad50 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -95,7 +95,7 @@ def grdgradient(grid, **kwargs): the Peucker piecewise linear approximation (simpler but faster algorithm; in this case *azim* and *elev* are hardwired to 315 and 45 degrees. This means that even if you provide other values - they will be ignored.) + they will be ignored.). normalize : str or bool [**e**\|\ **t**][*amp*][**+a**\ *ambient*][**+s**\ *sigma*]\ [**+o**\ *offset*]. @@ -123,18 +123,18 @@ def grdgradient(grid, **kwargs): all nodes after gradient calculations are completed. tiles : str **c**\|\ **r**\|\ **R**. - Controls how normalization via `normalize` is carried out. When + Controls how normalization via ``normalize`` is carried out. When multiple grids should be normalized the same way (i.e., with the same *offset* and/or *sigma*), - we must pass these values via `normalize`. However, this is + we must pass these values via ``normalize``. However, this is inconvenient if we compute these values from a grid. Use **c** to save the results of *offset* and *sigma* to a statistics file; if - grid output is not needed for this run then do not specify `outgrid`. - For subsequent runs, just use **r** to read these values. Using - **R** will read then delete the statistics file. + grid output is not needed for this run then do not specify + ``outgrid``. For subsequent runs, just use **r** to read these + values. Using **R** will read then delete the statistics file. slope_file : str Name of output grid file with scalar magnitudes of gradient vectors. - Requires `direction` but makes `outgrid` optional. + Requires ``direction`` but makes ``outgrid`` optional. {R} {V} {f} From 03f5f019bf964908a0d03c5c9f35e441e8709bb1 Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Thu, 28 Oct 2021 22:18:43 +0100 Subject: [PATCH 16/17] Apply suggestions from code review Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> --- pygmt/src/grdgradient.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 9fba4f0ad50..462b9d32e1d 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -105,14 +105,14 @@ def grdgradient(grid, **kwargs): given, it is set to the average of :math:`g`. The following forms are supported: - - **-N** - Normalize using :math:`g_n = \mbox{{amp}}\ + - **True** - Normalize using :math:`g_n = \mbox{{amp}}\ (\frac{{g - \mbox{{offset}}}}{{max(|g - \mbox{{offset}}|)}})` - **-Ne** - Normalize using a cumulative Laplace distribution yielding: :math:`g_n = \mbox{{amp}}(1 - \ \exp{{(\sqrt{{2}}\frac{{g - \mbox{{offset}}}}{{\sigma}}))}}`, where :math:`\sigma` is estimated using the L1 norm of :math:`(g - \mbox{{offset}})` if it is not given. - - **-Nt** - Normalize using a cumulative Cauchy distribution yielding: + - **t** - Normalize using a cumulative Cauchy distribution yielding: :math:`g_n = \ \frac{{2(\mbox{{amp}})}}{{\pi}}(\tan^{{-1}}(\frac{{g - \ \mbox{{offset}}}}{{\sigma}}))` where :math:`\sigma` is estimated @@ -132,10 +132,10 @@ def grdgradient(grid, **kwargs): grid output is not needed for this run then do not specify ``outgrid``. For subsequent runs, just use **r** to read these values. Using **R** will read then delete the statistics file. + {R} slope_file : str Name of output grid file with scalar magnitudes of gradient vectors. Requires ``direction`` but makes ``outgrid`` optional. - {R} {V} {f} {n} From 3a8048dbe2bcb845577f5dcf1665154d37bc53a2 Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Thu, 28 Oct 2021 22:18:57 +0100 Subject: [PATCH 17/17] Update pygmt/src/grdgradient.py Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> --- pygmt/src/grdgradient.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index 462b9d32e1d..4dd3b554235 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -107,7 +107,7 @@ def grdgradient(grid, **kwargs): - **True** - Normalize using :math:`g_n = \mbox{{amp}}\ (\frac{{g - \mbox{{offset}}}}{{max(|g - \mbox{{offset}}|)}})` - - **-Ne** - Normalize using a cumulative Laplace distribution yielding: + - **e** - Normalize using a cumulative Laplace distribution yielding: :math:`g_n = \mbox{{amp}}(1 - \ \exp{{(\sqrt{{2}}\frac{{g - \mbox{{offset}}}}{{\sigma}}))}}`, where :math:`\sigma` is estimated using the L1 norm of