From 11920957c5f1403dbe1fafc6c4a51f622fd7cb8f Mon Sep 17 00:00:00 2001
From: Wei Ji <23487320+weiji14@users.noreply.github.com>
Date: Fri, 29 Mar 2024 17:58:47 +1300
Subject: [PATCH] Add tutorial section on passing xr.Dataset with 1-D data_vars
 as input

Show how an xarray.Dataset with 1-D data variables can be passed into the `data` parameter of PyGMT functions/methods.
---
 examples/get_started/04_table_inputs.py | 34 +++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/examples/get_started/04_table_inputs.py b/examples/get_started/04_table_inputs.py
index 8ea55d9b2c9..66b2500ee85 100644
--- a/examples/get_started/04_table_inputs.py
+++ b/examples/get_started/04_table_inputs.py
@@ -27,6 +27,7 @@
 import numpy as np
 import pandas as pd
 import pygmt
+import xarray as xr
 
 # %%
 # ASCII table file
@@ -110,6 +111,39 @@
 fig.plot(data=gdf, style="c0.2c", fill="purple")
 fig.show()
 
+# %%
+# :class:`xarray.Dataset` with 1-D data variables
+# -----------------------------------------------
+#
+# For slightly advanced users that have tabular-like data stored in an
+# :class:`xarray.Dataset` object, it is also possible to pass this into the ``data``
+# parameter, provided that:
+#
+# 1. The :class:`xarray.Dataset` input is made up of 1-D :class:`xarray.DataArray` data
+#    variables.
+# 2. The data you want to plot or process is stored under ``data_vars``, and not under
+#    ``coords`` in the :class:`xarray.Dataset` data structure. Use
+#    :meth:`xarray.Dataset.reset_coords` if you need to convert a coordinate into a
+#    data variable.
+#
+# This is useful if you are working with data stored in file formats like HDF5 which can
+# be read using :func:`xarray.open_dataset`, but not ``pandas``
+
+# Example xr.Dataset
+index = np.arange(start=0, stop=10)
+distance = np.linspace(start=20, stop=50, num=10)
+elevation = np.logspace(start=1, stop=-3, num=10)
+
+ds = xr.Dataset(
+    data_vars={"distance": (["index"], distance), "y": (["index"], elevation)}
+)
+ds  # noqa: B018
+
+# %%
+fig = pygmt.Figure()
+fig.plot(data=ds, frame=["xaf+lDistance", "yaf+lElevation"])
+fig.show()
+
 # %%
 # Scalar values or 1-D arrays
 # ---------------------------