diff --git a/examples/gallery/embellishments/timestamp.py b/examples/gallery/embellishments/timestamp.py index 56954ff4caa..a45f65499d8 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() @@ -21,15 +20,17 @@ ############################################################################### # 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 + 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..72c558bb1c4 100644 --- a/pygmt/src/timestamp.py +++ b/pygmt/src/timestamp.py @@ -23,27 +23,39 @@ 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 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 ---------- 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: