From aad50f8740c488051d18560d8dcb54dc6237cbbd Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 15 Mar 2023 11:09:57 +0800 Subject: [PATCH 1/4] Figure.timestamp: Improve documentation and gallery example --- examples/gallery/embellishments/timestamp.py | 19 +++++++------ pygmt/src/timestamp.py | 29 ++++++++++++++------ pygmt/tests/test_timestamp.py | 2 -- 3 files changed, 30 insertions(+), 20 deletions(-) diff --git a/examples/gallery/embellishments/timestamp.py b/examples/gallery/embellishments/timestamp.py index 56954ff4caa..bb7a532a9e9 100644 --- a/examples/gallery/embellishments/timestamp.py +++ b/examples/gallery/embellishments/timestamp.py @@ -1,17 +1,16 @@ """ Timestamp --------- -The :meth:`pygmt.Figure.timestamp` method can draw the -GMT timestamp logo on the figure. The timestamp -will always be shown relative to the bottom-left corner -of the figure. By default, the ``offset`` and -``justification`` parameters are set to -``("-54p", "-54p")`` (x, y directions) and ``"BL"`` -(bottom-left), respectively. +The :meth:`pygmt.Figure.timestamp` method can draw the GMT timestamp logo on +the plot. The timestamp will always be shown relative to the bottom-left corner +of the plot. By default, the ``offset`` and ``justification`` parameters are +set to ``("-54p", "-54p")`` (x, y directions) and ``"BL"`` (bottom-left), +respectively. """ - # sphinx_gallery_thumbnail_number = 2 +import os + import pygmt fig = pygmt.Figure() @@ -24,12 +23,14 @@ # label font can be defined via the ``font`` parameter and the timestamp string # format via ``timefmt``. +os.environ["TZ"] = "Pacific/Honolulu" # optionally set the time zone + fig = pygmt.Figure() fig.coast(region="d", projection="H10c", land="black", water="cornsilk", frame="afg") fig.timestamp( label="Powered by PyGMT", justification="TL", font="Times-Bold", - timefmt="%Y-%m-%dT%H:%M", + timefmt="%Y-%m-%dT%H:%M:%S%z", ) fig.show() diff --git a/pygmt/src/timestamp.py b/pygmt/src/timestamp.py index e6c4772910a..2eab211b478 100644 --- a/pygmt/src/timestamp.py +++ b/pygmt/src/timestamp.py @@ -23,27 +23,38 @@ def timestamp( r""" Plot the GMT timestamp logo. + Add the GMT timestamp logo with an optional label at the bottom-left corner + of a plot. The timestamp will be in the locale set by the environment + variable **TZ** (generally local time) and its foramt is controlled by the + parameter ``timefmt``. It can also be replaced with any custom text string + using the ``text`` parameter. + Parameters ---------- text : None or str If ``None``, the current UNIX timestamp is shown in the GMT timestamp - logo. Set this parameter to replace the UNIX timestamp with a - custom text string instead. The text must be less than 64 characters. + logo. Set this parameter to replace the UNIX timestamp with a custom + text string instead. The text must be no longer than 64 characters. label : None or str The text string shown after the GMT timestamp logo. justification : str - Justification of the timestamp. The *justification* is a two-character + Justification of the timestamp box relative to the plot's bottom-left + corner (i.e., the plot origin). The *justification* is a two-character code that is a combination of a horizontal (**L**\ (eft), **C**\ (enter), or **R**\ (ight)) and a vertical (**T**\ (op), - **M**\ (iddle), or **B**\ (ottom)) code. + **M**\ (iddle), or **B**\ (ottom)) code. For example, + ``justification="TL"`` means choosing the **T**\ op **L**\ eft point of + the timestamp as the anchor point. offset : str or tuple *offset* or (*offset_x*, *offset_y*). - Offset the anchor point of the timestamp by *offset_x* and *offset_y*. - If a single value *offset* is given, *offset_y* = *offset_x* = - *offset*. + Offset the anchor point of the timestamp box by *offset_x* and + *offset_y*. If a single value *offset* is given, *offset_y* = + *offset_x* = *offset*. font : str - Font of the timestamp and the optional label. The parameter can't - change the font color for GMT<=6.4.0, only the font ID. + Font of the timestamp and the optional label. Since the GMT logo has a + fixed height, the font sizes are fixed to be 8-point for the timestamp + and 7-point for the label. The parameter can't change the font color + for GMT<=6.4.0, only the font style. timefmt : str Format string for the UNIX timestamp. The format string is parsed by the C function ``strftime``, so that virtually any text can be used diff --git a/pygmt/tests/test_timestamp.py b/pygmt/tests/test_timestamp.py index 9d6d1843b4f..039e1fe3712 100644 --- a/pygmt/tests/test_timestamp.py +++ b/pygmt/tests/test_timestamp.py @@ -86,8 +86,6 @@ def test_timestamp_text_truncated(): """ Passing a text string longer than 64 characters raises a warning and the string will be truncated. - - Requires GMT>=6.5.0. """ fig = Figure() with pytest.warns(expected_warning=RuntimeWarning) as record: From 2e1c4e89d9106dc2c791681249effce5f88ba89e Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 17 Mar 2023 15:25:25 +0800 Subject: [PATCH 2/4] Fix a typo Co-authored-by: Michael Grund <23025878+michaelgrund@users.noreply.github.com> --- pygmt/src/timestamp.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/timestamp.py b/pygmt/src/timestamp.py index 2eab211b478..7581c01f8df 100644 --- a/pygmt/src/timestamp.py +++ b/pygmt/src/timestamp.py @@ -25,7 +25,7 @@ def timestamp( Add the GMT timestamp logo with an optional label at the bottom-left corner of a plot. The timestamp will be in the locale set by the environment - variable **TZ** (generally local time) and its foramt is controlled by the + variable **TZ** (generally local time) and its format is controlled by the parameter ``timefmt``. It can also be replaced with any custom text string using the ``text`` parameter. From b2db32082921a2ad3e5e4c9ba5c0f0dfa9a43ff4 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 17 Mar 2023 20:50:21 +0800 Subject: [PATCH 3/4] Mention that TZ can be changed via os.environ[TZ] --- pygmt/src/timestamp.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pygmt/src/timestamp.py b/pygmt/src/timestamp.py index 7581c01f8df..aec2300ffb0 100644 --- a/pygmt/src/timestamp.py +++ b/pygmt/src/timestamp.py @@ -25,9 +25,10 @@ def timestamp( Add the GMT timestamp logo with an optional label at the bottom-left corner of a plot. The timestamp will be in the locale set by the environment - variable **TZ** (generally local time) and its format is controlled by the - parameter ``timefmt``. It can also be replaced with any custom text string - using the ``text`` parameter. + variable **TZ** (generally local time but can be changed via + ``os.environ["TZ"]``) and its format is controlled by the parameter + ``timefmt``. It can also be replaced with any custom text string using the + ``text`` parameter. Parameters ---------- From 0c0944fd1f5b3d4b18e9a3c82b33fce866fa6b7e Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 17 Mar 2023 22:31:57 +0800 Subject: [PATCH 4/4] 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> --- examples/gallery/embellishments/timestamp.py | 2 +- pygmt/src/timestamp.py | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/examples/gallery/embellishments/timestamp.py b/examples/gallery/embellishments/timestamp.py index bb7a532a9e9..a45f65499d8 100644 --- a/examples/gallery/embellishments/timestamp.py +++ b/examples/gallery/embellishments/timestamp.py @@ -20,7 +20,7 @@ ############################################################################### # Additionally, a custom label can be added via the ``label`` parameter. The -# label font can be defined via the ``font`` parameter and the timestamp string +# font can be defined via the ``font`` parameter and the timestamp string # format via ``timefmt``. os.environ["TZ"] = "Pacific/Honolulu" # optionally set the time zone diff --git a/pygmt/src/timestamp.py b/pygmt/src/timestamp.py index aec2300ffb0..72c558bb1c4 100644 --- a/pygmt/src/timestamp.py +++ b/pygmt/src/timestamp.py @@ -24,11 +24,11 @@ def timestamp( Plot the GMT timestamp logo. Add the GMT timestamp logo with an optional label at the bottom-left corner - of a plot. The timestamp will be in the locale set by the environment - variable **TZ** (generally local time but can be changed via - ``os.environ["TZ"]``) and its format is controlled by the parameter - ``timefmt``. It can also be replaced with any custom text string using the - ``text`` parameter. + of a plot with an offset of ``("-54p", "-54p")``. The timestamp will be + in the locale set by the environment variable **TZ** (generally local time + but can be changed via ``os.environ["TZ"]``) and its format is controlled + by the ``timefmt`` parameter. It can also be replaced with any custom + text string using the ``text`` parameter. Parameters ----------