From 95c8f636277ae50b83a764a2e92cf51a30777453 Mon Sep 17 00:00:00 2001
From: Michael Grund <michael_grund@gmx.de>
Date: Fri, 1 Jan 2021 19:55:59 +0100
Subject: [PATCH] Create gallery example for datetime inputs

Based on #464 and #549 I prepared a gallery example for plotting datetime inputs.
---
 examples/gallery/plot/datetime-inputs.py | 58 ++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 examples/gallery/plot/datetime-inputs.py

diff --git a/examples/gallery/plot/datetime-inputs.py b/examples/gallery/plot/datetime-inputs.py
new file mode 100644
index 00000000000..53496a4f04d
--- /dev/null
+++ b/examples/gallery/plot/datetime-inputs.py
@@ -0,0 +1,58 @@
+"""
+Datetime inputs
+---------------
+
+The :meth:`pygmt.Figure.plot` method can plot datetime inputs of individual types:
+
+- numpy.datetime64: for available options see https://numpy.org/doc/stable/reference/arrays.datetime.html
+- :class:`pandas.DatetimeIndex`
+- :class:`xarray.DataArray`: datetimes included in a *xarray.DataArray*
+- raw datetime strings in ISO format (e.g. ``["YYYY-MM-DD", "YYYY-MM-DDTHH", "YYYY-MM-DDTHH:MM:SS"]``)
+- Python built-in :class:`datetime.datetime` and :class:`datetime.date`
+
+We can pass datetime inputs based on one of the types listed above directly to the ``x`` and ``y`` options.
+ 
+The ``region`` argument has to include the :math:`x` and :math:`y` axis limits as *str* in the form 
+``"date_min/data_max/ymin/ymax"``.
+
+"""
+
+import datetime
+import numpy as np
+import pandas as pd
+import xarray as xr
+import pygmt
+
+fig = pygmt.Figure()
+
+# create a basemap with limits of 2010-01-01 to 2020-06-01 on the x axis and
+# 0 to 10 on the y axis
+fig.basemap(projection="X15c/5c", region="2010-01-01/2020-06-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, 2, 3]
+fig.plot(x, y, style="c0.4c", pen="1p", color="red3")
+
+# pandas.DatetimeIndex
+x = pd.date_range("2013", periods=3, freq="YS")
+y = [4, 5, 6]
+fig.plot(x, y, style="t0.4c", pen="1p", color="gold")
+
+# xarray.DataArray
+x = xr.DataArray(data=pd.date_range(start="2015-03", periods=3, freq="QS"))
+y = [7.5, 6, 4.5]
+fig.plot(x, y, style="s0.4c", pen="1p")
+
+# raw datetime strings
+x = ["2016-02-01", "2016-06-04T14", "2016-10-04T00:00:15"]
+y = [7, 8, 9]
+fig.plot(x, y, style="a0.4c", pen="1p", color="dodgerblue")
+
+# the Python built-in datetime and date
+x = [datetime.date(2018, 1, 1), datetime.datetime(2019, 6, 1, 20, 5, 45)]
+y = [6.5, 4.5]
+fig.plot(x, y, style="i0.4c", pen="1p", color="seagreen")
+
+fig.show()