feat: add plotting subpackage for radar dataset diagnostics

docs/_toc.yml

@@ -9,3 +9,4 @@ chapters:
 - file: it_dpc_precipitation
 - file: uk_metoffice_precipitation
 - file: be_rmi_precipitation
+- file: plotting

docs/plotting.ipynb

@@ -0,0 +1,213 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Plotting & Diagnostics\n",
+    "\n",
+    "The `mlcast_datasets.plotting` subpackage provides publication-quality diagnostic\n",
+    "figures for any dataset in the MLCast catalog.  This notebook demonstrates every\n",
+    "plotting function using the Italian DPC SRI radar precipitation dataset as an\n",
+    "example.\n",
+    "\n",
+    "All sample sizes are kept deliberately small so that this notebook runs quickly\n",
+    "in CI.  Increase `n_samples` / `n_coverage_samples` for higher-quality figures.\n",
+    "\n",
+    "## Installation\n",
+    "\n",
+    "The plotting functions require optional dependencies (cartopy, matplotlib, dask).\n",
+    "Install them with the `plotting` extra:\n",
+    "\n",
+    "```bash\n",
+    "pip install 'mlcast-datasets[plotting]'\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import mlcast_datasets\n",
+    "from mlcast_datasets import plotting"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2",
+   "metadata": {},
+   "source": [
+    "## Load the dataset"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cat = mlcast_datasets.open_catalog()\n",
+    "ds = cat.precipitation.it_dpc_sri_5min.to_dask()\n",
+    "ds"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4",
+   "metadata": {},
+   "source": [
+    "## Domain map\n",
+    "\n",
+    "Shows the spatial footprint of the radar coverage."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plotting.plot_domain_map(ds, n_coverage_samples=10);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
+   "source": [
+    "## Temporal coverage\n",
+    "\n",
+    "Year-by-month completeness heatmap and yearly timestep count."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plotting.plot_temporal_coverage(ds);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8",
+   "metadata": {},
+   "source": [
+    "## Spatial coverage\n",
+    "\n",
+    "Fraction of valid (non-NaN) observations per grid cell."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plotting.plot_spatial_coverage(ds, n_samples=50);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "10",
+   "metadata": {},
+   "source": [
+    "## Precipitation statistics\n",
+    "\n",
+    "Three-panel map (mean, max, std) and a log-log histogram of non-zero values."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "11",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig_maps, fig_hist = plotting.plot_precipitation_stats(ds, n_samples=50)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "12",
+   "metadata": {},
+   "source": [
+    "## Sample precipitation event\n",
+    "\n",
+    "Multi-panel view of a specific event. Here we show the Emilia-Romagna flood\n",
+    "of May 2023."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "13",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plotting.plot_sample_precipitation(\n",
+    "    ds,\n",
+    "    time_slice=slice(\"2023-05-16\", \"2023-05-17T06:00\"),\n",
+    ");"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "14",
+   "metadata": {},
+   "source": [
+    "## Monthly climatology\n",
+    "\n",
+    "Box plot of domain-mean precipitation grouped by calendar month."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "15",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plotting.plot_monthly_cycle(ds, n_samples=2000);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "16",
+   "metadata": {},
+   "source": [
+    "## Summary table\n",
+    "\n",
+    "Compact overview of key dataset properties."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "17",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plotting.generate_summary_table(ds)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pyproject.toml

@@ -4,6 +4,7 @@ dynamic = ["version"]
 description = "Intake catalog for datasets relevant for machine learning based nowcasting"
 authors = [
     {name = "Leif Denby", email = "lcd@dmi.dk"},
+    {name = "Gabriele Franch", email = "franch@fbk.eu"},
 ]
 readme = "README.md"
 requires-python = ">=3.11"
@@ -21,6 +22,15 @@ license-files = [
     "LICENSE-BSD",
 ]
 
+[project.optional-dependencies]
+plotting = [
+    "cartopy>=0.25.0",
+    "dask>=2024.0.0",
+    "matplotlib>=3.10.0",
+    "numpy>=1.24",
+    "pandas>=2.0",
+]
+
 [dependency-groups]
 dev = [
     "ipdb>=0.13.13",
@@ -62,3 +72,6 @@ mlcast_datasets = ["catalog/*.yaml", "catalog/**/*.yaml"]
 
 [tool.setuptools_scm]
 version_scheme = "post-release"
+
+[tool.isort]
+profile = "black"

src/mlcast_datasets/plotting/__init__.py

@@ -0,0 +1,40 @@
+"""Reusable plotting and diagnostic utilities for mlcast radar datasets."""
+
+try:
+    import cartopy  # noqa: F401
+    import matplotlib  # noqa: F401
+except ImportError as exc:
+    raise ImportError(
+        "mlcast-datasets plotting extras are not installed. "
+        "Run: pip install 'mlcast-datasets[plotting]'"
+    ) from exc
+
+from ._metadata import (
+    get_data_crs,
+    get_domain_extent,
+    get_variable_label,
+    infer_time_step_minutes,
+    select_plot_variable,
+)
+from .domain_map import plot_domain_map
+from .monthly_cycle import plot_monthly_cycle
+from .precipitation_stats import plot_precipitation_stats
+from .sample_precipitation import plot_sample_precipitation
+from .spatial_coverage import plot_spatial_coverage
+from .summary_table import generate_summary_table
+from .temporal_coverage import plot_temporal_coverage
+
+__all__ = [
+    "plot_domain_map",
+    "plot_monthly_cycle",
+    "plot_precipitation_stats",
+    "plot_sample_precipitation",
+    "plot_spatial_coverage",
+    "plot_temporal_coverage",
+    "generate_summary_table",
+    "select_plot_variable",
+    "get_data_crs",
+    "get_domain_extent",
+    "infer_time_step_minutes",
+    "get_variable_label",
+]