Hvplot (timeseries)

CHANGELOG.rst

@@ -8,6 +8,7 @@ Contributors to this version: Trevor James Smith (:user:`Zeitsperre`), Marco Bra
 
 New features and enhancements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* `figanos` now has timeseries available in the hvplot plotting library (:pull:`198`).
 * `figanos` now supports Python 3.12. (:pull:`210`).
 * Use list or ndarray as levels for colorbar in gridmap and small bug fixes (:pull:`176`).
 * Added style sheet ``transparent.mplstyle`` (:issue:`183`, :pull:`185`)

docs/index.rst

@@ -19,6 +19,7 @@ Need help?
    notebooks/figanos_docs
    notebooks/figanos_colours
    notebooks/figanos_multiplots
+   notebooks/figanos_hvplot
    api
    contributing
    releasing

docs/notebooks/figanos_hvplot.ipynb

@@ -0,0 +1,194 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {
+    "jupyter": {
+     "outputs_hidden": false
+    }
+   },
+   "source": [
+    "# Interactive plotting"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {
+    "jupyter": {
+     "outputs_hidden": false
+    }
+   },
+   "source": [
+    "Figanos can also be used with the [hvplot](https://hvplot.holoviz.org/) library, which provides a high-level plotting API built on HoloViews to produce interactive plots."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "import numpy as np\n",
+    "import xarray as xr\n",
+    "from xclim import ensembles\n",
+    "xr.set_options(keep_attrs=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3",
+   "metadata": {},
+   "source": [
+    "## HvPlot ouranos theme "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from figanos.hvplot.utils import set_hv_style\n",
+    "\n",
+    "set_hv_style('ouranos')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5",
+   "metadata": {},
+   "source": [
+    "## Timeseries\n",
+    "\n",
+    "The main elements of a plot are dependent on four arguments, each accepting dictionaries:\n",
+    "\n",
+    "1. `data` : a dictionary containing the Xarray objects and their respective keys, used as labels on the plot.\n",
+    "2. `use_attrs`: a dictionary linking attributes from the Xarray object to plot text elements.\n",
+    "3. `plot_kw` : a dictionary using the same keys as `data` to pass arguments to the underlying plotting function, in this case [hvplot.line](https://hvplot.holoviz.org/reference/tabular/line.html).\n",
+    "4. `opts_kw`: a dictionary using the same keys as `data` plus overlay (to be passed to the combined elements of all `data` values) to pass to the underlying `.opts` [holoviz funciton](https://holoviews.org/user_guide/Customizing_Plots.html).\n",
+    "\n",
+    "When labels are passed in `data`, any 'label' argument passed in `plot_kw` will be ignored."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# creates dataset\n",
+    "\n",
+    "time = pd.date_range(start='1960-01-01', end='2020-01-01', periods=10)\n",
+    "np.random.seed(1231)\n",
+    "dat_1 = np.random.rand(10) * 20\n",
+    "dat_2 = np.random.rand(10) * 20\n",
+    "dat_3 = np.random.rand(10) * 20\n",
+    "\n",
+    "dt = xr.Dataset(data_vars={'tas': (['realization', \n",
+    "                                      #'group', \n",
+    "                                      'time'], \n",
+    "                                     #np.array([[dat_1, dat_2], [dat_2, dat_3], [dat_3, dat_1]])\n",
+    "                                     np.array([dat_1, dat_2, dat_3])\n",
+    "                                    )\n",
+    "                            },\n",
+    "                     coords={'time': time, \n",
+    "                             'lat': 41,\n",
+    "                             'lon':-73,                            \n",
+    "                             #'group': ['a', 'b'], \n",
+    "                             'realization': [0, 1, 2]},\n",
+    "                 )\n",
+    "dt.tas.attrs={'long_name': 'Randomly generated time-series',\n",
+    "                'standart_name': 'air_temp',\n",
+    "                'description': \"Synthetic time-series\",\n",
+    "                'units': 'degC',}\n",
+    "                 \n",
+    "data2 = dt+10\n",
+    "\n",
+    "perc = ensembles.ensemble_percentiles(dt, values=[25, 50, 75], split=False)\n",
+    "stat =  ensembles.ensemble_mean_std_max_min(dt).drop_vars('tas_stdev')\n",
+    "perc2 = ensembles.ensemble_percentiles(data2, values=[10, 50, 90], split=False)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from figanos.hvplot import timeseries\n",
+    "timeseries(data2)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "timeseries(data2, legend='in_plot', show_lat_lon='lower left')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "timeseries({'rcp85': data2, 'rcp45': dt}, opts_kw={'overlay': {'legend_position': 'bottom_right', 'legend_cols': 2}}, show_lat_lon='lower left')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "10",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "timeseries({'val1': data2, 'val2': dt}, plot_kw={'val1': {'color': 'yellow'}, 'val2': {'line_width': 5, 'color': 'teal'}}, opts_kw={'overlay': {'legend_position': 'right'}}, show_lat_lon='lower left')\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "11",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "timeseries({'ssp245': perc, 'ssp585': perc2}, legend='full' , show_lat_lon=False, opts_kw={'overlay': {'legend_position': 'right'}})"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

environment-dev.yml

@@ -4,6 +4,7 @@ channels:
   - default
 dependencies:
   - python>=3.9,<3.13
+  # Don't forget to sync changes between environment.yml and pyproject.toml!
   # Main
   - cartopy >=0.23.0
   - cairosvg
@@ -18,6 +19,11 @@ dependencies:
   - scikit-image
   - xarray
   - xclim >=0.47
+  # for interactive figures
+  - hvplot
+  - holoviews
+  - geoviews
+  - bokeh
   # To make the package and notebooks usable
   - dask
   - h5py

pyproject.toml

@@ -47,7 +47,11 @@ dependencies = [
   "seaborn",
   "scikit-image",
   "xarray",
-  "xclim >=0.47"
+  "xclim >=0.47",
+  "hvplot",
+  "holoviews",
+  "geoviews",
+  "bokeh"
 ]
 
 [project.optional-dependencies]

src/figanos/__init__.py

@@ -22,6 +22,6 @@
 __email__ = "bourdeau-goulet.sarah-claude@ouranos.ca"
 __version__ = "0.3.1-dev.12"
 
-from . import matplotlib
+from . import hvplot, matplotlib
 from ._data import data
 from ._logo import Logos

src/figanos/hvplot/__init__.py

@@ -0,0 +1,4 @@
+"""Figanos hvplot plotting module."""
+
+from .plot import timeseries
+from .utils import get_hv_styles, set_hv_style