Support timedelta64 dtype as input

[weiji14]

Description of proposed changes

Map np.timedelta64 to GMT_LONG in clib/session.py's DTYPES dictionary. Added a unit test in test_clib_put_vectors.py to test passing a numpy array with timedelta64 dtypes of various time units (year to microsecond).

TODO:

• Allow passing in np.timedelta64 via put_vector
• Handle np.timedelta64 min/max values in the region parameter

Example usage:

import numpy as np
import pygmt
    

fig = pygmt.Figure()
fig.basemap(
    projection="X8c/5c",
    region=[0, 8, 0, 10],
    frame=["WSne", "xaf+lForecast Days", "yaf+lRMSE"],
)
fig.plot(
    x=np.arange(np.timedelta64(0, "D"), np.timedelta64(8, "D")),
    y=np.geomspace(start=0.1, stop=9, num=8),
    style="c0.2c",
    pen="1p",
)
fig.show()

produces

Addresses #2848, extends #464 and #562.

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.
• Use underscores (not hyphens) in names of Python files and directories.

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

[weiji14]

Ideally, we could pass in np.timedelta64 into the region argument as mentioned at #2848 (comment).

Suggested change

	region=[0, 8, 0, 10],
	region=[np.timedelta64(0, "D"), np.timedelta64(8, "D"), 0, 10],

[weiji14]

Ah ok, looks like I modified kwargs_to_strings 3 years ago at #562 to handle datetime objects in region, so could probably do something similar here for timedelta64.

[github-actions]

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_plot_timedelta64.png

Image diff(s)

Details

Added images

• test_plot_timedelta64.png

Modified images

Path	Old	New

Report last updated at commit 4426d95

[weiji14]

This double getattr to obtain item.dtype.name isn't very nice, wondering if there's a good alternative.

[weiji14]

Apparently Python has a built-in datetime.timedelta objects, but it's super hard to cast it to an integer type while preserving the orignal unit (e.g. day, hour, minute, etc). E.g.

import datetime

td = datetime.timedelta(hours=24)

print(np.timedelta64(td))
# numpy.timedelta64(86400000000,'us')
print(np.timedelta64(td).astype(int))
# 86400000000

Should we still support datetime.timedelta? Or only np.timedelta64?

[weiji14]

The if-then logic here might get a lot more complicated if we also decide to support passing PyArrow time/date types (xref #2800) into region/-R. At such, it might be good to isolate this logic into a separate function instead, so I'm thinking of maybe reverting commit d5bedc2 for now, but cherry-pick that change into a separate PR.

Specifically, we might want to create a dedicated _cast_datetime_to_str function. There's actually something similar used in solar (see 6406b43), so we could potentially re-use the function in many places.

[seisman]

Sounds good.

[weiji14]

Ok, commit reverted in 849feda. Should be ready to review now.

[seisman]

Looks good, but maybe wait for #2694?

[weiji14]

Ok, re-generated the baseline image using GMT 6.5.0 and ghostscript 10.02.1 at 4426d95, and test_plot_timedelta64 passes at 4426d95, so merging.