From b786c1c44c01b2f52e251ceca0bc9c15a3da9277 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 14 Dec 2023 22:25:35 +0800 Subject: [PATCH 01/11] Figure.shift_origin: Improve docstrings, add inline examples and add type hints --- pygmt/src/shift_origin.py | 52 ++++++++++++++++++++++++++++----------- 1 file changed, 38 insertions(+), 14 deletions(-) diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py index 966ccf0bd97..3b4e40c1581 100644 --- a/pygmt/src/shift_origin.py +++ b/pygmt/src/shift_origin.py @@ -1,33 +1,57 @@ """ shift_origin - Shift plot origin in x and/or y directions. """ +from __future__ import annotations from pygmt.clib import Session -def shift_origin(self, xshift=None, yshift=None): - """ +def shift_origin( + self, xshift: float | str | None = None, yshift: float | str | None = None +) -> None: + r""" Shift plot origin in x and/or y directions. - This method shifts the plot origin relative to the current origin - by (*xshift*, *yshift*). Optionally, append the length unit (**c**, - **i**, or **p**). Default unit if not given is **c** for centimeters. + This method shifts the plot origin relative to the current origin by + *xshift* and *yshift* in x and y directions, respectively. Optionally, + append the length unit (**c** for centimeters, **i** for inches, or **p** + for points) to the shifts. Default unit if not explicitely given is **c**, + but can be changed to other units via :gmt-term:`PROJ_LENGTH_UNIT`. + + For *xshift*, a special character **w** can also be used, which represents + the bounding box **width** of the previous plot. The full syntax is + [[±][*f*]\ **w**\ [/\ *d*\ ]±]\ *xoff*, where optional signs, factor *f* + and divisor *d* can be used to compute an offset that may be adjusted + further by ±*off*. For example, assuming that the previous plot has a width + of 10 centimeter, here are some example values for *xshift*: - Prepend **a** to shift the origin back to the original position after - plotting, prepend **c** to center the plot on the center of the paper - (optionally add shift), prepend **f** to shift the origin relative to - the fixed lower left corner of the page, or prepend **r** [Default] to - move the origin relative to its current location. + - ``w``: x-shift is 10 cm + - ``w+2c``: x-shift is 10+2=12 cm + - ``2w+3c``: x-shift is 2*10+3=23 cm + - ``w/2-2c``: x-shift is 10/2-2=3 cm - Detailed usage at - :gmt-docs:`cookbook/options.html#plot-positioning-and-layout-the-x-y-options` + Similarly, for *yshift*, a special character **h** can also be used, which + is the bounding box **height** of the previous plot. Parameters ---------- - xshift : str + xshift Shift plot origin in x direction. - yshift : str + yshift Shift plot origin in y direction. + + Examples + -------- + >>> import pygmt + >>> fig = pygmt.Figure() + >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c/10c", frame=True) + >>> # shift the plot origin in x-direction by 12 cm + >>> fig.shift_origin(xshift=12) + >>> fig.basemap(region=[0, 10, 0, 10], projection="X14c/10c", frame=True) + >>> # shift the plot origin in x-direction based on the previous plot width + >>> # here, the width is 14 cm, and the xshift is 16 cm + >>> fig.shift_origin(xshift="w+2c") + >>> fig.show() """ self._preprocess() args = ["-T"] From 187f39ff46e3e0b07d1575cef1f2d6275a893fa5 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 15 Dec 2023 00:36:47 +0800 Subject: [PATCH 02/11] Apply suggestions from code review Co-authored-by: Michael Grund <23025878+michaelgrund@users.noreply.github.com> --- pygmt/src/shift_origin.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py index 3b4e40c1581..f447de90539 100644 --- a/pygmt/src/shift_origin.py +++ b/pygmt/src/shift_origin.py @@ -15,7 +15,7 @@ def shift_origin( This method shifts the plot origin relative to the current origin by *xshift* and *yshift* in x and y directions, respectively. Optionally, append the length unit (**c** for centimeters, **i** for inches, or **p** - for points) to the shifts. Default unit if not explicitely given is **c**, + for points) to the shifts. Default unit if not explicitly given is **c**, but can be changed to other units via :gmt-term:`PROJ_LENGTH_UNIT`. For *xshift*, a special character **w** can also be used, which represents @@ -23,7 +23,7 @@ def shift_origin( [[±][*f*]\ **w**\ [/\ *d*\ ]±]\ *xoff*, where optional signs, factor *f* and divisor *d* can be used to compute an offset that may be adjusted further by ±*off*. For example, assuming that the previous plot has a width - of 10 centimeter, here are some example values for *xshift*: + of 10 centimeters, here are some example values for *xshift*: - ``w``: x-shift is 10 cm - ``w+2c``: x-shift is 10+2=12 cm From 8ba1353f9982dbf3afc760f55df527af1651e722 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 15 Dec 2023 08:48:46 +0800 Subject: [PATCH 03/11] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com> --- pygmt/src/shift_origin.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py index f447de90539..7dbd656db20 100644 --- a/pygmt/src/shift_origin.py +++ b/pygmt/src/shift_origin.py @@ -22,7 +22,7 @@ def shift_origin( the bounding box **width** of the previous plot. The full syntax is [[±][*f*]\ **w**\ [/\ *d*\ ]±]\ *xoff*, where optional signs, factor *f* and divisor *d* can be used to compute an offset that may be adjusted - further by ±*off*. For example, assuming that the previous plot has a width + further by ±\ *xoff*. For example, assuming that the previous plot has a width of 10 centimeters, here are some example values for *xshift*: - ``w``: x-shift is 10 cm From dafd034942c1ab8526d811eda2c5eadc3ea6a18a Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 15 Dec 2023 13:53:38 +0800 Subject: [PATCH 04/11] fix --- pygmt/src/shift_origin.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py index 7dbd656db20..367b15a72c7 100644 --- a/pygmt/src/shift_origin.py +++ b/pygmt/src/shift_origin.py @@ -22,8 +22,8 @@ def shift_origin( the bounding box **width** of the previous plot. The full syntax is [[±][*f*]\ **w**\ [/\ *d*\ ]±]\ *xoff*, where optional signs, factor *f* and divisor *d* can be used to compute an offset that may be adjusted - further by ±\ *xoff*. For example, assuming that the previous plot has a width - of 10 centimeters, here are some example values for *xshift*: + further by ±\ *xoff*. For example, assuming that the previous plot has a + width of 10 centimeters, here are some example values for *xshift*: - ``w``: x-shift is 10 cm - ``w+2c``: x-shift is 10+2=12 cm From c325925b22404f38f3f68f93bd451de61f6454cf Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 2 Jan 2024 13:39:02 +0800 Subject: [PATCH 05/11] Rewrap to 88 characters --- pygmt/src/shift_origin.py | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py index 367b15a72c7..635d318e6ef 100644 --- a/pygmt/src/shift_origin.py +++ b/pygmt/src/shift_origin.py @@ -12,26 +12,26 @@ def shift_origin( r""" Shift plot origin in x and/or y directions. - This method shifts the plot origin relative to the current origin by - *xshift* and *yshift* in x and y directions, respectively. Optionally, - append the length unit (**c** for centimeters, **i** for inches, or **p** - for points) to the shifts. Default unit if not explicitly given is **c**, - but can be changed to other units via :gmt-term:`PROJ_LENGTH_UNIT`. + This method shifts the plot origin relative to the current origin by *xshift* and + *yshift* in x and y directions, respectively. Optionally, append the length unit + (**c** for centimeters, **i** for inches, or **p** for points) to the shifts. + Default unit if not explicitly given is **c**, but can be changed to other units + via :gmt-term:`PROJ_LENGTH_UNIT`. - For *xshift*, a special character **w** can also be used, which represents - the bounding box **width** of the previous plot. The full syntax is - [[±][*f*]\ **w**\ [/\ *d*\ ]±]\ *xoff*, where optional signs, factor *f* - and divisor *d* can be used to compute an offset that may be adjusted - further by ±\ *xoff*. For example, assuming that the previous plot has a - width of 10 centimeters, here are some example values for *xshift*: + For *xshift*, a special character **w** can also be used, which represents the + bounding box **width** of the previous plot. The full syntax is + [[±][*f*]\ **w**\ [/\ *d*\ ]±]\ *xoff*, where optional signs, factor *f* and + divisor *d* can be used to compute an offset that may be adjusted further by + ±\ *xoff*. For example, assuming that the previous plot has a width of 10 + centimeters, here are some example values for *xshift*: - ``w``: x-shift is 10 cm - ``w+2c``: x-shift is 10+2=12 cm - ``2w+3c``: x-shift is 2*10+3=23 cm - ``w/2-2c``: x-shift is 10/2-2=3 cm - Similarly, for *yshift*, a special character **h** can also be used, which - is the bounding box **height** of the previous plot. + Similarly, for *yshift*, a special character **h** can also be used, which is the + bounding box **height** of the previous plot. Parameters ---------- From 7ece697b3d20f19f9d4e129552dd543f94e52580 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 3 Jan 2024 00:00:59 +0800 Subject: [PATCH 06/11] Explicitly set shift unit --- examples/gallery/3d_plots/scatter3d.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/gallery/3d_plots/scatter3d.py b/examples/gallery/3d_plots/scatter3d.py index 46a3765622a..0f6a6d1609c 100644 --- a/examples/gallery/3d_plots/scatter3d.py +++ b/examples/gallery/3d_plots/scatter3d.py @@ -93,7 +93,7 @@ ) # Shift plot origin in x direction -fig.shift_origin(xshift=3.1) +fig.shift_origin(xshift="3.1c") # Add colorbar legend fig.colorbar() From 6d6a7898e044daacae6fb0be98372aa7c1882bc3 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 5 Jan 2024 23:11:29 +0800 Subject: [PATCH 07/11] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com> --- pygmt/src/shift_origin.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py index 635d318e6ef..b722dd80b96 100644 --- a/pygmt/src/shift_origin.py +++ b/pygmt/src/shift_origin.py @@ -22,13 +22,13 @@ def shift_origin( bounding box **width** of the previous plot. The full syntax is [[±][*f*]\ **w**\ [/\ *d*\ ]±]\ *xoff*, where optional signs, factor *f* and divisor *d* can be used to compute an offset that may be adjusted further by - ±\ *xoff*. For example, assuming that the previous plot has a width of 10 + ±\ *xoff*. Assuming that the previous plot has a width of 10 centimeters, here are some example values for *xshift*: - - ``w``: x-shift is 10 cm - - ``w+2c``: x-shift is 10+2=12 cm - - ``2w+3c``: x-shift is 2*10+3=23 cm - - ``w/2-2c``: x-shift is 10/2-2=3 cm + - ``"w"``: x-shift is 10 cm + - ``"w+2c"``: x-shift is 10+2=12 cm + - ``"2w+3c"``: x-shift is 2*10+3=23 cm + - ``"w/2-2c"``: x-shift is 10/2-2=3 cm Similarly, for *yshift*, a special character **h** can also be used, which is the bounding box **height** of the previous plot. @@ -45,11 +45,11 @@ def shift_origin( >>> import pygmt >>> fig = pygmt.Figure() >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c/10c", frame=True) - >>> # shift the plot origin in x-direction by 12 cm + >>> # Shift the plot origin in x direction by 12 cm >>> fig.shift_origin(xshift=12) >>> fig.basemap(region=[0, 10, 0, 10], projection="X14c/10c", frame=True) - >>> # shift the plot origin in x-direction based on the previous plot width - >>> # here, the width is 14 cm, and the xshift is 16 cm + >>> # Shift the plot origin in x direction based on the previous plot width + >>> # Here, the width is 14 cm, and xshift is 16 cm >>> fig.shift_origin(xshift="w+2c") >>> fig.show() """ From 1148c8876f6aa01915e3d11a349ebec4e56b2b88 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 5 Jan 2024 23:22:09 +0800 Subject: [PATCH 08/11] Rewrap to 88 characters --- pygmt/src/shift_origin.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py index b722dd80b96..200555b8f73 100644 --- a/pygmt/src/shift_origin.py +++ b/pygmt/src/shift_origin.py @@ -15,15 +15,15 @@ def shift_origin( This method shifts the plot origin relative to the current origin by *xshift* and *yshift* in x and y directions, respectively. Optionally, append the length unit (**c** for centimeters, **i** for inches, or **p** for points) to the shifts. - Default unit if not explicitly given is **c**, but can be changed to other units - via :gmt-term:`PROJ_LENGTH_UNIT`. + Default unit if not explicitly given is **c**, but can be changed to other units via + :gmt-term:`PROJ_LENGTH_UNIT`. For *xshift*, a special character **w** can also be used, which represents the bounding box **width** of the previous plot. The full syntax is - [[±][*f*]\ **w**\ [/\ *d*\ ]±]\ *xoff*, where optional signs, factor *f* and - divisor *d* can be used to compute an offset that may be adjusted further by - ±\ *xoff*. Assuming that the previous plot has a width of 10 - centimeters, here are some example values for *xshift*: + [[±][*f*]\ **w**\ [/\ *d*\ ]±]\ *xoff*, where optional signs, factor *f* and divisor + *d* can be used to compute an offset that may be adjusted further by ±\ *xoff*. + Assuming that the previous plot has a width of 10 centimeters, here are some example + values for *xshift*: - ``"w"``: x-shift is 10 cm - ``"w+2c"``: x-shift is 10+2=12 cm From 677b7c0eba0fc25d19d9cfecbcb5d4a1f9d7e058 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 6 Jan 2024 21:48:21 +0800 Subject: [PATCH 09/11] Update pygmt/src/shift_origin.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com> --- pygmt/src/shift_origin.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py index 200555b8f73..cd1f699ed37 100644 --- a/pygmt/src/shift_origin.py +++ b/pygmt/src/shift_origin.py @@ -33,6 +33,9 @@ def shift_origin( Similarly, for *yshift*, a special character **h** can also be used, which is the bounding box **height** of the previous plot. + **Note**: The previous plot bounding box refers to the last object plotted, which + may be a basemap, image, logo, legend, colorbar, etc. + Parameters ---------- xshift From 8bb1768ad7409e194a3234761278788785f85801 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 6 Jan 2024 21:48:41 +0800 Subject: [PATCH 10/11] Update pygmt/src/shift_origin.py --- pygmt/src/shift_origin.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py index cd1f699ed37..f9f53926487 100644 --- a/pygmt/src/shift_origin.py +++ b/pygmt/src/shift_origin.py @@ -8,7 +8,7 @@ def shift_origin( self, xshift: float | str | None = None, yshift: float | str | None = None -) -> None: +): r""" Shift plot origin in x and/or y directions. From 69901b6b52cf2ee0a71b043b7b1c134a69d6807f Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 6 Jan 2024 21:52:17 +0800 Subject: [PATCH 11/11] formatting --- pygmt/src/shift_origin.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py index f9f53926487..d877a89d62b 100644 --- a/pygmt/src/shift_origin.py +++ b/pygmt/src/shift_origin.py @@ -35,7 +35,7 @@ def shift_origin( **Note**: The previous plot bounding box refers to the last object plotted, which may be a basemap, image, logo, legend, colorbar, etc. - + Parameters ---------- xshift