diff --git a/.gitignore b/.gitignore
index 664c162..68c3204 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,5 @@
dist/
requirements.txt
+**/.ipynb_checkpoints/
+**/.jupyter_ystore.db
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 57f7f9a..8d9c56c 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -21,6 +21,8 @@ repos:
args: ["--maxkb=1500", "--enforce-all"]
exclude: |
(?x)^(
+ .*\.ipynb
+ |.*\.gif
)$
- repo: https://github.com/python-poetry/poetry
diff --git a/README.md b/README.md
index 2c222f8..86d80e2 100644
--- a/README.md
+++ b/README.md
@@ -50,7 +50,18 @@ poetry install
# Usage
-## Command line interface
+> \[!NOTE\]
+> When running in a Jupyter notebook, to make progress bars and interactive widgets work, make sure to install `ipywidgets` and to enable the widgets extension.
+
+```bash
+pip install ipywidgets
+# optional, not needed with Jupyter Notebook 7+
+jupyter nbextension enable --py widgetsnbextension
+```
+
+## Generating EPW Files
+
+### Command line interface
Example usage:
@@ -66,7 +77,7 @@ By default, the `time-zone` argument is used only to populate the `LOCATION` hea
Use `--help` to have a list of available options.
-## Python API
+### Python API
Example usage:
@@ -85,15 +96,65 @@ download_and_make_epw(
)
```
-When running in a Jupyter notebook, to make progress bars and interactive widgets work, make sure to install `ipywidgets` and to enable the widgets extension:
+## Visualizing EPW Files
+
+The package includes an interactive visualization tool for EPW files that supports three types of plots: 2D line charts, 3D surface plots, and radar (polar) plots.
+
+### Command line interface
```bash
-pip install ipywidgets
-# optional, not needed with Jupyter Notebook 7+
-jupyter nbextension enable --py widgetsnbextension
+# List available weather series in an EPW file
+era5epw_visualize path/to/file.epw --list-series
+
+# Create a 2D line plot (default)
+era5epw_visualize path/to/file.epw --series "Dry Bulb Temperature" --type 2D
+
+# Create a 3D surface plot
+era5epw_visualize path/to/file.epw --series "Wind Speed" --type 3D
+
+# Create a radar plot showing daily min/max values
+era5epw_visualize path/to/file.epw --series "Global Horizontal Radiation" --type radar
+
+# Save visualization to HTML file
+era5epw_visualize path/to/file.epw --series "Dry Bulb Temperature" --output visualization.html
+```
+
+### Python API
+
+Use in Jupyter notebooks or Python scripts:
+
+```python
+from era5epw.visualize import visualize_epw
+
+# Create interactive 2D plot
+fig = visualize_epw(
+ epw_file_path="path/to/file.epw",
+ series_name="Dry Bulb Temperature",
+ plot_type="2D",
+ show=True # Display immediately in Jupyter
+)
+
+# Create 3D surface plot
+fig = visualize_epw(
+ epw_file_path="path/to/file.epw",
+ series_name="Wind Speed",
+ plot_type="3D",
+ show=True
+)
+
+# Create radar plot
+fig = visualize_epw(
+ epw_file_path="path/to/file.epw",
+ series_name="Global Horizontal Radiation",
+ plot_type="radar",
+ show=True
+)
+
+# Save to HTML file
+fig.write_html("visualization.html")
```
-
+[](./doc/era5epw_dl_viz_notebook.gif)
# Documentation
diff --git a/doc/era5epw_dl_viz_notebook.gif b/doc/era5epw_dl_viz_notebook.gif
new file mode 100644
index 0000000..8e0da5d
Binary files /dev/null and b/doc/era5epw_dl_viz_notebook.gif differ
diff --git a/doc/notebook.ipynb b/doc/notebook.ipynb
new file mode 100644
index 0000000..5fb221f
--- /dev/null
+++ b/doc/notebook.ipynb
@@ -0,0 +1,11960 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "a53d43d4-1c64-4aec-af44-c65b26f4b2d4",
+ "metadata": {},
+ "source": [
+ "## Setup"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "a9b882b8-9fd1-406b-8132-4196e1b83783",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# make sure we have the dependencies installed.\n",
+ "# if not, uncomment and execute line below, then restart jupyter.\n",
+ "# !pip install era5epw ipywidgets\n",
+ "!pip show era5epw ipywidgets"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "d96ecb2c-760b-49d8-9f9e-97acc32dccbb",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# set CDS/ADS API key\n",
+ "import os\n",
+ "\n",
+ "os.environ[\"CDSADS_API_KEY\"] = \"YOUR_KEY\""
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3c7583bb-85bb-4df8-b602-4affe52003c6",
+ "metadata": {},
+ "source": [
+ "## Download"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "e17ea226-831e-48aa-aead-f7d5c0652f26",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Download data and make EPW\n",
+ "from era5epw.main import download_and_make_epw\n",
+ "\n",
+ "download_and_make_epw(\n",
+ " year=2025,\n",
+ " latitude=48.8,\n",
+ " longitude=2.4,\n",
+ " city_name=\"Paris\",\n",
+ " time_zone=1,\n",
+ " elevation=0,\n",
+ " output_file=\"/tmp/era5epw_paris_2025.epw\",\n",
+ " apply_time_zone_to_data=True,\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "47673358-9d29-4fce-a342-4e0e71ee2d4c",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Get the file\n",
+ "from era5epw.utils import generate_download_link\n",
+ "\n",
+ "generate_download_link(\"/tmp/era5epw_paris_2025.epw\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "64a6b706-bbcf-4e35-937a-aafe670aebab",
+ "metadata": {},
+ "source": [
+ "## Visualization"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "e546ddce-beff-4514-a48f-cfae59be0fe3",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from era5epw.visualize import visualize_epw"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "ffd25448-4d53-4215-ad13-7eb080b136a8",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ " \n",
+ " \n",
+ " "
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/html": [
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "fig = visualize_epw(\n",
+ " epw_file_path=\"/tmp/era5epw_paris_2025.epw\",\n",
+ " series_name=\"Dry Bulb Temperature\",\n",
+ " plot_type=\"2D\",\n",
+ " show=True\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "8d9bd35a-514f-4321-a797-4cb8569d023f",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ " \n",
+ "