Add tutorial for plotting datetime inputs

[weiji14]

Description of the desired feature

Following on from #464, we'll need help adding a gallery/tutorial on how to pass in datetime inputs to plot!

Simple goal (gallery example):

Start by taking a look at the top post of #464. The example should cover at least 4 types of Python datetime inputs:

• numpy.datetime64
• pandas.DateTimeIndex
• Raw datetime strings in both ISO and non-ISO formats, e.g., 2010-01-01, 1/1/2018, Jul 5, 2019
• Python's built-in datetime and date

You can adapt the example from the following code:

pygmt/pygmt/tests/test_plot.py

Lines 294 to 325 in a2258a5

	def test_plot_datetime():
	"""Test various datetime input data"""
	fig = Figure()
	fig.basemap(projection="X15c/5c", region="2010-01-01/2020-01-01/0/10", frame=True)
	# numpy.datetime64 types
	x = np.array(
	["2010-06-01", "2011-06-01T12", "2012-01-01T12:34:56"], dtype="datetime64"
	)
	y = [1.0, 2.0, 3.0]
	fig.plot(x, y, style="c0.2c", pen="1p")
	# pandas.DatetimeIndex
	x = pd.date_range("2013", freq="YS", periods=3)
	y = [4, 5, 6]
	fig.plot(x, y, style="t0.2c", pen="1p")
	# xarray.DataArray
	x = xr.DataArray(data=pd.date_range(start="2015-03", freq="QS", periods=3))
	y = [7.5, 6, 4.5]
	fig.plot(x, y, style="s0.2c", pen="1p")
	# raw datetime strings
	x = ["2016-02-01", "2017-03-04T00:00"]
	y = [7, 8]
	fig.plot(x, y, style="a0.2c", pen="1p")
	# the Python built-in datetime and date
	x = [datetime.date(2018, 1, 1), datetime.datetime(2019, 1, 1)]
	y = [8.5, 9.5]
	fig.plot(x, y, style="i0.2c", pen="1p")
	return fig

It would also be good to show how datetime-like arguments can be passed in the 'region' argument of fig.basemap, see #562.

Stretch goal (full tutorial)

Learn how to use pygmt.config to configure Calendar/Time Parameters!

This is a bit more involved, but you can do amazing stuff like abbreviate Sunday to Sun. Example code/figure:

pygmt/pygmt/tests/test_config.py

Lines 77 to 90 in a2258a5

	def test_config_format_time_map():
	"""
	Test that setting `FORMAT_TIME_MAP` config changes both
	`FORMAT_TIME_PRIMARY_MAP` and `FORMAT_TIME_SECONDARY_MAP`.
	"""
	fig = Figure()
	with config(FORMAT_TIME_MAP="abbreviation"):
	fig.basemap(
	region=["2020-1-24T", "2020-1-27T", 0, 1],
	projection="X6c/1c",
	frame=["pa1K", "sa1K", "NWse"],
	)
	fig.basemap(frame=["pa1K", "sa1K", "nwSE"])
	return fig

See also GMT Gallery Example 21 "Time-series of RedHat stock price" at https://docs.generic-mapping-tools.org/6.1/gallery/ex21.html for what is possible!

Are you willing to help implement and maintain this feature? Let's have someone new tackle this!

[michaelgrund]

As the gallery example was merged into master in #779 could you adjust the issue title @weiji14 to only address the missing tutorial?

[weiji14]

Continuing from #1078 (comment) (ping @munzekm, @noorbuchi, @cklima616, @nathandloria), I think adding a datetime tutorial would be a nice follow up to #1070 since you're already familiar with how to write up a tutorial for PyGMT. There's a few challenging aspects to it, but I'm sure that a team of three will make short work of it! These are some sections you could do (but do feel free to come up with new ideas):

1. Different datetime-like Python inputs into fig.basemap, see also https://www.pygmt.org/v0.3.1/gallery/symbols/datetime_inputs.html
2. Using pygmt.info to get the min/max time for passing into the region parameter, but note potential bug at Running info on pandas.DataFrame with time column doesn't work #597
3. Setting a primary and secondary time axis. See https://github.com/weiji14/deepicedrain/blob/v0.4.1/deepicedrain/vizplots.py#L376-L403 for an example (pardon if it's messy), below is a screenshot of how it should look like:

As usual, free to ask any questions, and/or start a draft PR to work on this issue. And thanks again for your continued contributions!

[munzekm]

Thank you @weiji14 for the information about this issue. We would be happy to start working on it. We do have a few questions: Would you want us to create a new python file inside the tutorial folder or use an existing one? Do you want us to work on the existing gallery file as well? Also, how would you like us to set up this tutorial. Our group just wants to make sure we fully understand what we are focusing on.

[weiji14]

Would you want us to create a new python file inside the tutorial folder or use an existing one? Do you want us to work on the existing gallery file as well?

Please make a new python file for the tutorial, and no, the existing gallery example doesn't need to be worked on.

Also, how would you like us to set up this tutorial. Our group just wants to make sure we fully understand what we are focusing on.

The tutorial is intended to walk someone new to make a date-time plot for time-series data. Feel free to discuss within the group and structure things as you see fit (since you're all new to datetime plotting in PyGMT, presumably you would have a list of things you want to know about how to plot time-series data). To be honest, we don't have a strict set of rules on how it needs to be done. But if you're looking for ideas, check out the other tutorials like https://www.pygmt.org/v0.3.1/tutorials/text.html, and see #549 (comment) for suggestions on what could be included.