Add Figure.timestamp to plot the GMT timestamp logo #2208

seisman · 2022-11-24T10:35:19Z

Description of proposed changes

In this PR, I add the Figure.timestamp method to plot the GMT timestamp logo, just like what GMT's -U option does. The final goal is to remove the timestamp alias from all the plotting methods (c.f. #2135 and #924 (comment)).

Here are some notes:

The full syntax of the -U option is: -U[<label>][+c][+j<just>][+o<dx>[/<dy>]]. -U+c can be used to append the raw GMT command (e.g., gmt coast -R... -J...) after the timestamp logo. It's not implemented because (1) It's rarely used. A figure is usually produced by multiple commands, so it makes no sense to show the command string of a single command; (2) It makes little sense to show the raw GMT command string for a figure produced by a Python script; (3) It's also impossible to implement it in the Figure.timestamp() function.
The Figure.timestamp method is implemented by calling gmt plot -T -U...
There are four GMT defaults (FONT_LOGO, MAP_LOGO, MAP_LOGO_POS, and FORMAT_TIME_STAMP) that can affect the timestamp logo.
- MAP_LOGO controls if a timestamp logo should be plotted. It makes no sense here, so ignored.
- MAP_LOGO_POS defaults to BL/-54p/-54p. It's equivalent to setting the +j and +o modifiers. So it's ignored.
- FONT_LOGO can control the font ID of the text strings. It's implemented by passing --FONT_LOGO=xxx to the GMT C API.
- FORMAT_TIME_STAMP can control the format of the timestamp. It's implemented by passing --FORMAT_TIME_STAMP to the GMT C API.
An upstream bug of the +o modifier for GMT <=6.4.0 (-U doesn't work with a single offset value gmt#7107).
For GMT<=6.4.0, FONT_LOGO can only change the font ID, but since GMT 6.5.0, it can also change both the font ID and color (but not the font size). See Allow FONT_LOGO to change font color gmt#7125
In GMT 6.5.0, a new modifier +t will be added. See Allow FONT_LOGO to change font color gmt#7125.
It's difficult to test this function, because the image has the timestamp string, which changes every second. The workaround here is passing a constant format string to FORMAT_TIME_STAMP (e.g., --FORMAT_TIME_STAMP="9999-99-99T99:99:99").

Examples:

>>> # Plot the GMT timestamp logo.
>>> import pygmt
>>> fig = pygmt.Figure()
>>> fig.timestamp()
>>> fig.show()

>>> # Plot the GMT timestamp logo with a custom label.
>>> fig = pygmt.Figure()
>>> fig.timestamp(label="Powered by PyGMT")
>>> fig.show()

Documentation preview: https://pygmt-dev--2208.org.readthedocs.build/en/2208/api/generated/pygmt.Figure.timestamp.html#pygmt.Figure.timestamp

Reminders

Run make format and make check to make sure the code follows the style guide.
Add tests for new features or tests that would have caught the bug that you're fixing.
Add new public functions/methods/classes to doc/api/index.rst.
Write detailed docstrings for all functions/methods.
If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

/format: automatically format and lint the code
/test-gmt-dev: run full tests on the latest GMT development version

pygmt/src/timestamp.py

seisman · 2022-12-02T15:44:33Z

pygmt/src/timestamp.py

+    if is_nonstr_iter(offset):  # given a list
+        kwdict["U"] += "+o" + "/".join(f"{item}" for item in offset)


Please note that we can't use decorator @kwargs_to_strings(offset="sequence") here, because the decorator can only deal with keyword arguments and doesn't work for the default values. I.e., it doesn't work for Figure.timestamp() but works for Figure.timestamp(offset=["-54p", "-54p"]), although offset defaults to ["-54p", "-54p"].

Related issue report at #2361.

seisman · 2023-01-02T11:35:08Z

Ping @GenericMappingTools/pygmt-maintainers for comments on the current implementation of the Figure.timestamp() function and ideas about how to test it.

seisman · 2023-01-03T04:20:40Z

The libfaketime package can be used to temporarily change the system date/time. It's also available on conda-forge, but it's a CLI program.

There are Python wrapper (https://github.com/simon-weber/python-libfaketime) and pytest plugin (https://github.com/touilleMan/pytest-libfaketime), but both are not actively maintained.

seisman · 2023-01-03T04:28:49Z

pygmt/src/timestamp.py

+        lib.call_module(
+            module="plot",
+            args=build_arg_string(kwdict)
+            + f" --FONT_LOGO={font} --FORMAT_TIME_STAMP={timefmt}",


Two thoughts when implementing this function:

Add a new parameter (e.g., confdict) to the build_arg_string function, so that we can pass a dict of GMT defaults to the call_module function, e.g.,

build_arg_string(kwdict, confdict={"FONT_LOGO": font, "FORMAT_TIME_STAMP": timefmt}

The three parameters FONT_LOGO, MAP_LOGO, and MAP_LOGO_POS won't be used after the Figure.timestamp function is used (FORMAT_TIME_STAMP is still used in other places), so they can be removed from the pygmt.config keyword list:

pygmt/pygmt/src/config.py

Lines 26 to 28 in 9253af3

_keywords = [

"COLOR_BACKGROUND",

"COLOR_FOREGROUND",

Hmm, point 1 seems ok, but I'm not sure about point 2. I'd prefer to keep the three parameters in the list, because even if you remove it, you're only removing the autocompletion, but users can still manually set those parameters.

Point 1 was implemented in PR #2324

weiji14 · 2023-01-03T16:43:41Z

7. It's difficult to write tests for this module, because the image has the timestamp string, which changes every second. We can't test it unless we can find a way to set the current time to a fixed value.

Maybe use @check_figures_equal following https://github.com/GenericMappingTools/pygmt/blob/v0.8.0/doc/contributing.md#using-check_figures_equal, and output only the date and not the precise time down to the second?

seisman · 2023-01-04T02:53:41Z

timefmt : str

    Format of the time information in the UNIX time stamp. This format is
    parsed by the C function ``strftime``, so that virtually any text can
    be used (even not containing any time information).

I just realized that it's possible to specify a fixed timestamp by passing a text to the timefmt parameter (actually GMT's FORMAT_TIME_STAMP parameter).

Here is a CLI example:

gmt plot -T -U --FORMAT_TIME_STAMP="1970-01-01T00:00:00" -png map

I think we can trust the timestamp string is always correct and focus on testing the function parameters.

github-actions · 2023-01-31T13:07:53Z

Summary of changed images

This is an auto-generated report of images that have changed on the DVC remote

Status	Path
added	pygmt/tests/baseline/test_timestamp.png
added	pygmt/tests/baseline/test_timestamp_font.png
added	pygmt/tests/baseline/test_timestamp_justification.png
added	pygmt/tests/baseline/test_timestamp_label.png
added	pygmt/tests/baseline/test_timestamp_offset.png

Image diff(s)

Added images

pygmt/tests/baseline/test_timestamp.png

pygmt/tests/baseline/test_timestamp_font.png

pygmt/tests/baseline/test_timestamp_justification.png

pygmt/tests/baseline/test_timestamp_label.png

pygmt/tests/baseline/test_timestamp_offset.png

Modified images

Path	Old	New

Report last updated at commit 0079643

seisman · 2023-03-02T03:57:37Z

Ping @GenericMappingTools/pygmt-maintainers for reviews.

weiji14 · 2023-03-02T04:07:37Z

pygmt/tests/test_timestamp.py

+def test_timestamp_justification():
+    """
+    Check if the "justification" parameter works.
+
+    Only a subset of justification codes are tested to avoid overlapping
+    timestamps.
+    """
+    fig = Figure()
+    fig.basemap(projection="X10c/5c", region=[0, 10, 0, 5], frame=0)
+    for just in ["BL", "BR", "TL", "TR"]:
+        fig.timestamp(justification=just, timefmt=just)
+    return fig


The output of the justification image doesn't look correct?

All of the timestamps are on the bottom left (BL). Shouldn't they be at the four different corners?

Unlike other embellishments (e.g., inset, legend or direction rose), the timestamp logo is always located at the lower left corner of the map. I believe this is GMT's design.

See https://docs.generic-mapping-tools.org/dev/gmt.conf.html#term-MAP_LOGO_POS

Sets the justification and the position of the logo/timestamp box relative to the current plot’s lower left corner (i.e., map origin)

Interesting design choice 😅 Actually, I just realized I was thinking of position rather than justification. Maybe we should document the default offset="-54p/-54p" under the offset docstring?

The default values are clear from the function definition:

Figure.timestamp((text=None, label=None, justification='BL', offset=('-54p', '-54p'), font='Helvetica,black', timefmt='%Y %b %d %H:%M:%S')

I'm hesitate to document the defaults in the docstring.

Ah ok, was thinking of adding [Default is ('-54p', '-54p')], but it's not really needed I guess.

pygmt/src/timestamp.py

weiji14 · 2023-03-02T04:14:39Z

pygmt/src/timestamp.py

+        Font of the timestamp and the optional label. The parameter can't
+        change the font color for GMT<=6.4.0.


Should a GMTInvalidInput error be raised when users pass font as a parameter with GMT 6.3.0? Or is the error clear enough from GMT?

The font parameter works for any GMT versions.

For GMT>6.4.0, it can change both the font ID and font color, but for GMT<=6.4.0, the font color is always black so it can only change the font ID.

Ah ok, maybe reword it into something like this?

Suggested change

Font of the timestamp and the optional label. The parameter can't

change the font color for GMT<=6.4.0.

Font of the timestamp and the optional label. The parameter can't

change the font color for GMT<=6.4.0, only the font label.

I'm afraid "font label" is incorrect here. It should be "font ID" or "font name".

Owh, you mean like font style (e.g. Helvetica)? Feel free to edit the suggested changes.

Added "only the font ID" in 0079643.

Co-authored-by: Wei Ji <[email protected]>

weiji14

Only a very minor suggestion as mentioned in https://github.com/GenericMappingTools/pygmt/pull/2208/files#r1122590265 (up to you to apply), but otherwise wait for second reviewer to approve.

pygmt/src/timestamp.py

michaelgrund · 2023-03-02T08:11:09Z

Would you also like to add a gallery example or should we do this in a separate PR @seisman ?

seisman · 2023-03-02T09:01:52Z

Would you also like to add a gallery example or should we do this in a separate PR @seisman ?

It's not on my todo list, so better to wait for someone else to work on the gallery example in another PR.

seisman commented Nov 24, 2022

View reviewed changes

pygmt/src/timestamp.py Outdated Show resolved Hide resolved

seisman added the feature Brand new feature label Nov 30, 2022

seisman added this to the 0.8.0 milestone Nov 30, 2022

Add Figure.timestamp to plot the GMT timestamp logo

c8206ec

seisman changed the title ~~WIP: Add Figure.timestamp to plot the GMT timestamp logo~~ Add Figure.timestamp to plot the GMT timestamp logo Dec 2, 2022

seisman force-pushed the timestamp branch from bf29f17 to c8206ec Compare December 2, 2022 15:05

seisman commented Dec 2, 2022

View reviewed changes

seisman marked this pull request as ready for review December 2, 2022 15:44

seisman modified the milestones: 0.8.0, 0.9.0 Dec 20, 2022

seisman marked this pull request as draft December 30, 2022 07:59

seisman added 3 commits January 1, 2023 16:29

Merge branch 'main' into timestamp

2096760

Add Figure.timestamp to the API reference documentation

e0bb6bb

Improve the timestamp function

4d6d777

seisman force-pushed the timestamp branch from b7be5f3 to 4d6d777 Compare January 1, 2023 09:16

seisman added 2 commits January 1, 2023 17:22

Add the timefmt parmater to set time timestamp format

fffe3cd

Fix formattingg

54f4307

seisman commented Jan 3, 2023

View reviewed changes

seisman mentioned this pull request Jan 4, 2023

Let the build_arg_string function handle GMT configurations #2299

Closed

seisman added 3 commits January 29, 2023 19:59

Merge branch 'main' into timestamp

fe8eeac

Merge branch 'main' into timestamp

97574ac

Fix the configurations

1e8de17

seisman force-pushed the timestamp branch from d37781e to 93024de Compare January 31, 2023 13:06

Add the first test

79460fb

seisman force-pushed the timestamp branch from 93024de to 79460fb Compare January 31, 2023 13:23

seisman added 9 commits February 17, 2023 21:21

Merge branch 'main' into timestamp

16c0368

Use the package-level variable __gmt_version__

98b6762

Merge branch 'main' into timestamp

b8a7fbb

Fix formatting

688f6b0

Merge branch 'main' into timestamp

6e168e1

Use the __gmt_version__ variable

5857866

Merge branch 'main' into timestamp

01a3cbb

Remove unused imports

4fa2e72

Minor changes to the docstrings

0c07a48

weiji14 reviewed Mar 2, 2023

View reviewed changes

Update pygmt/src/timestamp.py

e4bd94c

Co-authored-by: Wei Ji <[email protected]>

weiji14 approved these changes Mar 2, 2023

View reviewed changes

weiji14 added final review call This PR requires final review and approval from a second reviewer and removed needs review This PR has higher priority and needs review. labels Mar 2, 2023

seisman commented Mar 2, 2023

View reviewed changes

pygmt/src/timestamp.py Outdated Show resolved Hide resolved

Fix docstrings for font

0079643

seisman merged commit b7926ae into main Mar 3, 2023

seisman deleted the timestamp branch March 3, 2023 02:49

seisman mentioned this pull request Mar 3, 2023

Add a gallery example for the Figure.timestamp method #2390

Closed

michaelgrund mentioned this pull request Mar 6, 2023

Add a gallery example for the Figure.timestamp method #2391

Merged

7 tasks

seisman removed the final review call This PR requires final review and approval from a second reviewer label Mar 7, 2023

seisman mentioned this pull request Mar 7, 2023

Remove the xshift (X) and yshift (Y) aliases from all plotting modules? #924

Closed

seisman mentioned this pull request Nov 22, 2023

Let kwargs_to_strings work with default values and positional arguments #2826

Merged

7 tasks

seisman mentioned this pull request Jan 15, 2024

Figure.timestamp: Deprecate parameter 'justification' to 'justify' (remove in v0.13.0) #3002

Merged

seisman mentioned this pull request Dec 17, 2024

Figure.timestamp: Plot GMT timestamp logo #3646

Closed

14 tasks

weiji14 mentioned this pull request Sep 30, 2025

Remove deprecated codes after dropping GMT 6.4 support #4128

Merged

weiji14 mentioned this pull request Oct 7, 2025

Colorbar annotation size does not change #3041

Closed

		if is_nonstr_iter(offset): # given a list
		kwdict["U"] += "+o" + "/".join(f"{item}" for item in offset)

		Font of the timestamp and the optional label. The parameter can't
		change the font color for GMT<=6.4.0.

Add Figure.timestamp to plot the GMT timestamp logo #2208

Add Figure.timestamp to plot the GMT timestamp logo #2208

Uh oh!

Conversation

seisman commented Nov 24, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seisman commented Jan 2, 2023

Uh oh!

seisman commented Jan 3, 2023

Uh oh!

seisman Jan 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weiji14 commented Jan 3, 2023

Uh oh!

seisman commented Jan 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 31, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of changed images

Image diff(s)

Added images

Modified images

Uh oh!

seisman commented Mar 2, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seisman Mar 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weiji14 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

michaelgrund commented Mar 2, 2023

Uh oh!

seisman commented Mar 2, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

seisman commented Nov 24, 2022 •

edited

Loading

seisman Jan 3, 2023 •

edited

Loading

seisman commented Jan 4, 2023 •

edited

Loading

github-actions bot commented Jan 31, 2023 •

edited

Loading

seisman Mar 2, 2023 •

edited

Loading