Merge branch 'main' into hotfix/pipaudit

ThomasBouche · ThomasBouche · commit fdb3185097b0 · 2025-10-27T14:44:53.000+01:00
diff --git a/.github/workflows/ci-cd-mkdocs.yml b/.github/workflows/ci-cd-mkdocs.yml
@@ -19,9 +19,9 @@
       name: Build doc
       runs-on: ubuntu-latest
       steps:
-        - uses: actions/checkout@v4
+        - uses: actions/checkout@v5
         - name: Install Python
-          uses: actions/setup-python@v5
+          uses: actions/setup-python@v6
           with:
             python-version: '3.11'
         - name: Install package with optional dependency 'doc'
@@ -32,7 +32,7 @@
           working-directory: ./docs
           run: mkdocs build
         - name: Upload Pages artifact
-          uses: actions/upload-pages-artifact@v3
+          uses: actions/upload-pages-artifact@v4
           with:
             path: "docs/site/"
     publish:
diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
@@ -19,9 +19,9 @@
         runs-on: ubuntu-latest
         steps:
           - name: Checkout
-            uses: actions/checkout@v4
+            uses: actions/checkout@v5
           - name: Set up Python version
-            uses: actions/setup-python@v5
+            uses: actions/setup-python@v6
             with:
               python-version: |
                 3.9
@@ -52,9 +52,9 @@
           id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
         steps:
           - name: Checkout
-            uses: actions/checkout@v4
+            uses: actions/checkout@v5
           - name: Set up Python version
-            uses: actions/setup-python@v5
+            uses: actions/setup-python@v6
             with:
               python-version: '3.13'
           - name: Build package
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,13 +4,19 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.2.1] - August, 2024
+## [0.2.2] - August, 2025
+
+### Features
+
+* Support for Météo-France ensemble model `PE-AROME` (#38)
+
+## [0.2.1] - August, 2025
 
 ### Features
 
 * Support for Python3.12 and Python 3.13
 
-## [0.2.0] - January, 2024
+## [0.2.0] - January, 2025
 
 ### Features
 
diff --git a/README.md b/README.md
@@ -50,11 +50,14 @@ Create an account on [the Météo-France API portal](https://portail-api.meteofr
 
 Meteole allows you to retrieve forecasts for a wide range of weather indicators. Here's how to get started:
 
-| Characteristics  | AROME                | ARPEGE                      | AROME INSTANTANE               | PIAF               |
-|------------------|----------------------|-----------------------------| -------------------------------| -------------------------------|
-| Resolution       | 1.3 km               | 10 km                       | 1.3 km                         | 1.3 km                         |
-| Update Frequency | Every 3 hours        | Every 6 hours               | Every 1 hour                   | Every 10 minutes |
-| Forecast Range   | Every hour, up to 51 hours | Every hour, up to 114 hours | Every 15 minutes, up to 360 minutes | Every 5 minutes, up to 195 minutes |
+| Characteristics  | AROME                      | AROME-PE                   | ARPEGE                      | AROME INSTANTANE               | PIAF               |
+|------------------|----------------------------|----------------------------|-----------------------------|--------------------------------| -------------------------------|
+| Resolution       | 1.3 km                     | 2.8 km                     | 10 km                       | 1.3 km                         | 1.3 km                         |
+| Update Frequency | Every 3 hours              | Every 6 hours              | Every 6 hours               | Every 1 hour                   | Every 10 minutes |
+| Forecast Range   | Every hour, up to 51 hours | Every hour, up to 51 hours | Every hour, up to 114 hours | Every 15 minutes, up to 360 minutes | Every 5 minutes, up to 195 minutes |
+| Numbers of scenarios   | 1 | 25 | 1 | 1 | 1 |
+
+The AromePE model is an ensemble model. Instead of making a single forecast of the most likely weather, a set (or ensemble) of forecasts is produced. This set of forecasts aims to give an indication of the range of possible future states of the atmosphere ([from Wikipedia](https://en.wikipedia.org/wiki/Ensemble_forecasting)). It provides 25 scenarios of the possible weather parameters instead of one for the standard determinist models.
 
 *note : the date of the run cannot be more than 4 days in the past. Consequently, change the date of the run in the example below.*
 
@@ -88,7 +91,8 @@ df_arome = arome_client.get_coverage(
     lat = (41.33356, 51.0889),                                                 # Optional: latitude
     coverage_id=None,                                                          # Optional: an alternative to indicator/run/interval
     temp_dir=None,                                                             # Optional: Directory to store the temporary file
-)
+    ensemble_numbers=range(3),                                                 # Optional: Only for ensemble models (AromePE), the number of scenarios
+    )
 ```
 Note: The coverage_id can be used instead of indicator, run, and interval.
 
diff --git a/docs/pages/how_to.md b/docs/pages/how_to.md
@@ -1,3 +1,4 @@
+
 Ensure that you have correctly installed **Meteole** before, check the [Installation](installation.md) page :wrench:
 
 ## Get a token, an API key or an application ID
@@ -46,14 +47,17 @@ client.get_vignette()
 
 ## Get data
 
-Meteole allows you to retrieve forecasts for a wide range of weather indicators. Here's how to get started with AROME, AROME INSTANTANE, ARPEGE or PIAF:
+Meteole allows you to retrieve forecasts for a wide range of weather indicators. Here's how to get started with AROME, AROME-PE, AROME INSTANTANE, ARPEGE or PIAF:
 
-| Characteristics  | AROME                      | ARPEGE                      | AROME INSTANTANE               | PIAF               |
-|------------------|----------------------------|-----------------------------|--------------------------------| -------------------------------|
-| Resolution       | 1.3 km                     | 10 km                       | 1.3 km                         | 1.3 km                         |
-| Update Frequency | Every 3 hours              | Every 6 hours               | Every 1 hour                   | Every 10 minutes |
-| Forecast Range   | Every hour, up to 51 hours | Every hour, up to 114 hours | Every 15 minutes, up to 360 minutes | Every 5 minutes, up to 195 minutes |
+| Characteristics  | AROME                      | AROME-PE                   | ARPEGE                      | AROME INSTANTANE               | PIAF               |
+|------------------|----------------------------|----------------------------|-----------------------------|--------------------------------| -------------------------------|
+| Resolution       | 1.3 km                     | 2.8 km                     | 10 km                       | 1.3 km                         | 1.3 km                         |
+| Update Frequency | Every 3 hours              | Every 6 hours              | Every 6 hours               | Every 1 hour                   | Every 10 minutes |
+| Forecast Range   | Every hour, up to 51 hours | Every hour, up to 51 hours | Every hour, up to 114 hours | Every 15 minutes, up to 360 minutes | Every 5 minutes, up to 195 minutes |
+| Numbers of scenarios   | 1 | 25 | 1 | 1 | 1 |
 
+The AromePE model is an ensemble model. Instead of making a single forecast of the most likely weather, a set (or ensemble) of forecasts is produced. This set of forecasts aims to give an indication of the range of possible future states of the atmosphere ([from Wikipedia](https://en.wikipedia.org/wiki/Ensemble_forecasting)). It provides 25 scenarios of the possible weather parameters instead of one for the standard determinist models. 
+ 
 *note : the date of the run cannot be more than 4 days in the past. Consequently, change the date of the run in the example below.*
 
 ```python
@@ -88,4 +92,6 @@ df_arome = arome_client.get_coverage(
 )
 ```
 
-The `get_combined_coverage` method allows you to retrieve weather data for multiple indicators at the same time, streamlining the process of gathering forecasts for different parameters (e.g., temperature, wind speed, etc.). For detailed guidance on using this feature, refer to this [tutorial](https://github.com/MAIF/meteole/tree/docs/update_readme/tutorial/tutorial/Fetch_forecast_for_multiple_indicators.ipynb).
+The `get_combined_coverage` method allows you to retrieve weather data for multiple indicators at the same time, streamlining the process of gathering forecasts for different parameters (e.g., temperature, wind speed, etc.). For detailed guidance on using this feature, refer to this [tutorial](https://github.com/MAIF/meteole/tree/docs/update_readme/tutorial/tutorial/Fetch_forecast_for_multiple_indicators.ipynb).
+
+The use of ensemble models is slightly different as they retrieve several forecast scenarios for each run. See this [tutorial](https://github.com/MAIF/meteole/tree/docs/update_readme/tutorial/tutorial/Fetch_forecasts_ensemble.ipynb) for a guided example.
diff --git a/src/meteole/__init__.py b/src/meteole/__init__.py
@@ -1,11 +1,12 @@
 from importlib.metadata import version
 
 from meteole._arome import AromeForecast
+from meteole._arome_ensemble import AromePEForecast
 from meteole._arome_instantane import AromePIForecast
 from meteole._arpege import ArpegeForecast
 from meteole._piaf import PiafForecast
 from meteole._vigilance import Vigilance
 
-__all__ = ["AromeForecast", "AromePIForecast", "ArpegeForecast", "PiafForecast", "Vigilance"]
+__all__ = ["AromeForecast", "AromePIForecast", "ArpegeForecast", "PiafForecast", "Vigilance", "AromePEForecast"]
 
 __version__ = version("meteole")
diff --git a/src/meteole/_arome.py b/src/meteole/_arome.py
@@ -61,6 +61,8 @@ class AromeForecast(WeatherForecast):
     INDICATORS: list[str] = AROME_INSTANT_INDICATORS + AROME_OTHER_INDICATORS
     INSTANT_INDICATORS: list[str] = AROME_INSTANT_INDICATORS
     BASE_ENTRY_POINT: str = "wcs/MF-NWP-HIGHRES-AROME"
+    MODEL_TYPE: str = "DETER"
+    ENSEMBLE_NUMBERS: int = 1
     DEFAULT_TERRITORY: str = "FRANCE"
     DEFAULT_PRECISION: float = 0.01
     CLIENT_CLASS: type[BaseClient] = MeteoFranceClient
diff --git a/src/meteole/_arome_ensemble.py b/src/meteole/_arome_ensemble.py
@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import logging
+from typing import final
+
+from meteole.clients import BaseClient, MeteoFranceClient
+from meteole.forecast import WeatherForecast
+
+logger = logging.getLogger(__name__)
+
+AVAILABLE_AROME_TERRITORY: list[str] = [
+    "FRANCE",
+    "NCALED",
+    "INDIEN",
+    "POLYN",
+    "GUYANE",
+    "ANTIL",
+]
+
+AROME_INSTANT_INDICATORS: list[str] = [
+    "BRIGHTNESS_TEMPERATURE__GROUND_OR_WATER_SURFACE",
+    "BRIGHTNESS_TEMPERATURE_CHANNEL62__GROUND_OR_WATER_SURFACE",
+    "INHIBITION_CONVECTIVE__GROUND_OR_WATER_SURFACE",
+    "TOTAL_WATER_VAPOUR__GROUND_OR_WATER_SURFACE",
+    "RELATIVE_DIVERGENCE__ISOBARIC_SURFACE",
+    "RELATIVE_HUMIDITY__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "RELATIVE_HUMIDITY__ISOBARIC_SURFACE",
+    "LOW_CLOUD_COVER__GROUND_OR_WATER_SURFACE",
+    "PRECIPITATION_TYPE_MOST_SEVERE__GROUND_OR_WATER_SURFACE",
+    "PRECIPITATION_TYPE__GROUND_OR_WATER_SURFACE",
+    "PRESSURE__MEAN_SEA_LEVEL",
+    "REFLECTIVITY_MAXIMUM__GROUND_OR_WATER_SURFACE",
+    "REFLECTIVITY_DBZ__ISOBARIC_SURFACE",
+    "MAXIMUM_TEMPERATURE__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "MINIMUM_TEMPERATURE__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "PSEUDO_ADIABATIC_POTENTIAL_TEMPERATURE__ISOBARIC_SURFACE",
+    "TEMPERATURE__GROUND_OR_WATER_SURFACE",
+    "TEMPERATURE__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "TEMPERATURE__ISOBARIC_SURFACE",
+    "U_COMPONENT_OF_WIND_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "U_COMPONENT_OF_WIND__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "MINIMUM_VISIBILITY_PRECIPITATING_HYDROMETEORS__GROUND_OR_WATER_SURFACE",
+    "MINIMUM_VISIBILITY_NON_PRECIPITATING_HYDROMETEORS__GROUND_OR_WATER_SURFACE",
+    "VERTICAL_VELOCITY_PRESSURE__ISOBARIC_SURFACE",
+    "V_COMPONENT_OF_WIND_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "V_COMPONENT_OF_WIND__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "GEOPOTENTIAL__ISOBARIC_SURFACE",
+]
+
+AROME_OTHER_INDICATORS: list[str] = [
+    "TOTAL_WATER_PRECIPITATION__GROUND_OR_WATER_SURFACE",
+    "TOTAL_GRAUPEL_PRECIPITATION__GROUND_OR_WATER_SURFACE",
+    "LIGHTNING_DENSITY_CUMULATED__GROUND_OR_WATER_SURFACE",
+    "TOTAL_SNOW_PRECIPITATION__GROUND_OR_WATER_SURFACE",
+    "TOTAL_PRECIPITATION__GROUND_OR_WATER_SURFACE",
+]
+
+
+@final
+class AromePEForecast(WeatherForecast):
+    """Access the PE-AROME ensemble forecast data from Meteo-France API."""
+
+    MODEL_NAME: str = "pearome"
+    BASE_ENTRY_POINT: str = "wcs/MF-NWP-HIGHRES-PEARO"
+    MODEL_TYPE: str = "ENSEMBLE"
+    ENSEMBLE_NUMBERS: int = 25
+    DEFAULT_TERRITORY: str = "FRANCE"
+    CLIENT_CLASS: type[BaseClient] = MeteoFranceClient
+    INDICATORS: list[str] = AROME_INSTANT_INDICATORS + AROME_OTHER_INDICATORS
+    INSTANT_INDICATORS: list[str] = AROME_INSTANT_INDICATORS
+
+    def __init__(self, client=None, **kwargs):
+        super().__init__(client, precision=0.025, **kwargs)
+
+    def _validate_parameters(self) -> None:
+        """Check the territory and the precision parameters.
+
+        Raise:
+            ValueError: At least, one parameter is not good.
+        """
+        if self.precision != 0.025:
+            raise ValueError("Parameter `precision` must be 0.025")
+
+        if self.territory not in AVAILABLE_AROME_TERRITORY:
+            raise ValueError(f"Parameter `territory` must be in {AVAILABLE_AROME_TERRITORY}")
diff --git a/src/meteole/_arome_instantane.py b/src/meteole/_arome_instantane.py
@@ -71,6 +71,8 @@ class AromePIForecast(WeatherForecast):
     INDICATORS: list[str] = AROMEPI_INSTANT_INDICATORS + AROMEPI_OTHER_INDICATORS
     INSTANT_INDICATORS: list[str] = AROMEPI_INSTANT_INDICATORS
     BASE_ENTRY_POINT: str = "wcs/MF-NWP-HIGHRES-AROMEPI"
+    MODEL_TYPE: str = "DETER"
+    ENSEMBLE_NUMBERS: int = 1
     DEFAULT_TERRITORY: str = "FRANCE"
     DEFAULT_PRECISION: float = 0.01
     CLIENT_CLASS: type[BaseClient] = MeteoFranceClient
diff --git a/src/meteole/_arpege.py b/src/meteole/_arpege.py
@@ -79,6 +79,8 @@ class ArpegeForecast(WeatherForecast):
     INDICATORS: list[str] = ARPEGE_INSTANT_INDICATORS + ARPEGE_OTHER_INDICATORS
     INSTANT_INDICATORS: list[str] = ARPEGE_INSTANT_INDICATORS
     BASE_ENTRY_POINT: str = "wcs/MF-NWP-GLOBAL-ARPEGE"
+    MODEL_TYPE: str = "DETER"
+    ENSEMBLE_NUMBERS: int = 1
     DEFAULT_TERRITORY: str = "EUROPE"
     RELATION_TERRITORY_TO_PREC_ARPEGE: dict[str, float] = {"EUROPE": 0.1, "GLOBE": 0.25, "ATOURX": 0.1, "EURAT": 0.05}
     CLIENT_CLASS: type[BaseClient] = MeteoFranceClient
diff --git a/src/meteole/_piaf.py b/src/meteole/_piaf.py
@@ -38,6 +38,8 @@ class PiafForecast(WeatherForecast):
     INDICATORS: list[str] = PIAF_INSTANT_INDICATORS + PIAF_OTHER_INDICATORS
     INSTANT_INDICATORS: list[str] = PIAF_INSTANT_INDICATORS
     BASE_ENTRY_POINT: str = "wcs/MF-NWP-HIGHRES-PIAF"
+    MODEL_TYPE: str = "DETER"
+    ENSEMBLE_NUMBERS: int = 1
     DEFAULT_TERRITORY: str = "FRANCE"
     DEFAULT_PRECISION: float = 0.01
     CLIENT_CLASS: type[BaseClient] = MeteoFranceClient
diff --git a/src/meteole/forecast.py b/src/meteole/forecast.py
diff --git a/tests/test_forecasts.py b/tests/test_forecasts.py
diff --git a/tutorial/Fetch_forecasts_ensemble.ipynb b/tutorial/Fetch_forecasts_ensemble.ipynb
