Add tutorial to show interactive data visualization via 'panel'

ci/requirements/docs.yml

@@ -14,6 +14,7 @@ dependencies:
     # Optional dependencies
     - contextily
     - geopandas
+    - panel
     - rioxarray
     # Development dependencies (general)
     - build

doc/conf.py

@@ -59,6 +59,7 @@
     "numpy": ("https://numpy.org/doc/stable/", None),
     "python": ("https://docs.python.org/3/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "panel": ("https://panel.holoviz.org/index.html", None),
     "rasterio": ("https://rasterio.readthedocs.io/en/stable/", None),
     "rioxarray": ("https://corteva.github.io/rioxarray/stable/", None),
     "xarray": ("https://docs.xarray.dev/en/stable/", None),

doc/install.rst

@@ -108,6 +108,7 @@ The following are optional dependencies:
 * `IPython <https://ipython.org>`__: For embedding the figures in Jupyter notebooks (recommended).
 * `Contextily <https://contextily.readthedocs.io>`__: For retrieving tile maps from the internet.
 * `GeoPandas <https://geopandas.org>`__: For using and plotting GeoDataFrame objects.
+* `Panel <https://panel.holoviz.org/index.html>`__: For creating interactive dashboards.
 * `RioXarray <https://corteva.github.io/rioxarray>`__: For saving multi-band rasters to GeoTIFFs.
 
 Installing GMT and other dependencies

environment.yml

@@ -15,6 +15,7 @@ dependencies:
     - contextily
     - geopandas
     - ipython
+    - panel
     - rioxarray
     # Development dependencies (general)
     - build

examples/tutorials/advanced/panel_extension.py

@@ -0,0 +1,121 @@
+r"""
+Dynamic data visualization using ``Panel``
+==========================================
+*Please run the following code examples in a notebook environment otherwise
+the interactive parts of this tutorial will not work. You can use the button
+"Download Jupyter notebook: panel_extension.ipynb" at the bottom of this page
+to download this script as a Jupyter notebook.*
+
+The library ``Panel`` (https://panel.holoviz.org/index.html) can be used to
+create interactive dashboards by connecting user-defined widgets to plots.
+``Panel`` can be used as an extension to Jupyter notebook / lab.
+
+This tutorial is split into three parts:
+- Make a static map
+- Make a dynamic map
+- Add a grid for Earth relief
+"""
+
+# sphinx_gallery_thumbnail_number = 1
+
+
+# Import the requiered packages
+import numpy as np
+import panel as pn
+import pygmt
+
+pn.extension()
+
+
+###############################################################################
+# Make a static map
+# -----------------
+
+# Create figure instance
+fig = pygmt.Figure()
+fig.coast(
+    projection="G30/15/10c",  # Orthographic projection
+    region="g",  # global
+    frame="g30",  # Add gridlines in steps of 30 degrees on top
+    land="gray",
+    water="lightblue",
+    shorelines="1/0.25p,gray50",
+)
+fig.show()
+
+
+###############################################################################
+# Make a dynamic map
+# ------------------
+# Vary the central longitude used for the Orthographic projection to create
+# a rotation of the Earth around the vertical axis.
+
+# Create a slider
+slider_lon = pn.widgets.DiscreteSlider(
+    name="Central longitude",
+    options=list(np.arange(0, 361, 10)),
+    value=0,
+)
+
+
+# Define a function for plotting the single slices
+@pn.depends(central_lon=slider_lon)
+def view(central_lon):
+    # Create figure instance
+    fig = pygmt.Figure()
+    fig.coast(
+        # Vary the central longitude used for the Orthographic projection
+        projection="G" + str(central_lon) + "/15/12c",
+        region="g",
+        frame="g30",  # Add gridlines in steps of 30 degrees on top
+        land="gray",
+        water="lightblue",
+        shorelines="1/0.25p,gray50",
+    )
+    return fig
+
+
+# Make an interactive dashboard
+pn.Column(slider_lon, view)
+
+
+###############################################################################
+# Add a grid for Earth relief
+# ---------------------------
+
+# Download a grid for Earth relief
+grd_relief = pygmt.datasets.load_earth_relief(resolution="10m")
+
+# Create a slider
+slider_lon = pn.widgets.DiscreteSlider(
+    name="Central longitude",
+    options=list(np.arange(0, 361, 10)),
+    value=0,
+)
+
+
+# Define a function for plotting the single slices
+@pn.depends(central_lon=slider_lon)
+def view(central_lon):
+    # Create figure instance
+    fig = pygmt.Figure()
+    # Set up a colormap for the elevation
+    pygmt.makecpt(
+        cmap="oleron",
+        series=[int(np.min(grd_relief)), int(np.max(grd_relief)) + 1, 100],
+    )
+    # Plot the grid for the elevation
+    fig.grdimage(
+        projection="G" + str(central_lon) + "/15/12c",
+        region="g",
+        grid=grd_relief,  # Use gird downloaded above
+        cmap=True,  # Use colormap defined above
+        frame="g30",  # Add gridlines in steps of 30 degrees on top
+    )
+    # Add a colorbar for the elevation
+    fig.colorbar(frame=["a2000f1000", "x+lElevation", "y+lm"])
+    return fig
+
+
+# Make an interactive dashboard
+pn.Column(slider_lon, view)

pyproject.toml

@@ -44,6 +44,7 @@ all = [
     "contextily",
     "geopandas",
     "ipython",
+    "panel",
     "rioxarray",
 ]