From bb0dde89aa271d967c355ffd2d56cf10a274de37 Mon Sep 17 00:00:00 2001 From: Thomas BOUCHE Date: Fri, 3 Jan 2025 14:59:29 +0100 Subject: [PATCH 1/2] mkdocs update --- docs/mkdocs.yaml | 6 +- docs/pages/assets/css/mkdocs_extra.css | 4 +- docs/pages/assets/css/style.css | 16 +-- docs/pages/assets/img/svg/meteole-git.svg | 1 + docs/pages/coverage_parameters.md | 74 +++++++++++++ docs/pages/how_to.md | 128 ++++++---------------- docs/pages/index.html | 15 +-- 7 files changed, 128 insertions(+), 116 deletions(-) create mode 100644 docs/pages/assets/img/svg/meteole-git.svg create mode 100644 docs/pages/coverage_parameters.md diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml index 62c7a9d..271e661 100644 --- a/docs/mkdocs.yaml +++ b/docs/mkdocs.yaml @@ -64,7 +64,7 @@ markdown_extensions: use_pygments: true linenums: true pymdownx.inlinehilite: - pymdownx.snippets: + pymdownx.snippets: pymdownx.superfences: custom_fences: - name: mermaid @@ -74,11 +74,13 @@ plugins: - mkdocstrings - search nav: - - Home: + - Home: - Welcome: home.md - Why use Meteole?: why.md - Installation: installation.md - User Guide: - How to: how_to.md + - Advanced User Guide: + - Coverages: coverage_parameters.md extra_css: - assets/css/mkdocs_extra.css \ No newline at end of file diff --git a/docs/pages/assets/css/mkdocs_extra.css b/docs/pages/assets/css/mkdocs_extra.css index c17ef77..e501d70 100644 --- a/docs/pages/assets/css/mkdocs_extra.css +++ b/docs/pages/assets/css/mkdocs_extra.css @@ -3,11 +3,11 @@ } .md-typeset .admonition.beta, .md-typeset details.beta { - border-color: #CF363B; + border-color: #afcb37; } .md-typeset .beta > .admonition-title, .md-typeset .beta > summary { - background-color: #CF363B; + background-color: #afcb37; } .md-typeset .beta > .admonition-title::before, .md-typeset .beta > summary::before { diff --git a/docs/pages/assets/css/style.css b/docs/pages/assets/css/style.css index 9065cd9..cb36d90 100644 --- a/docs/pages/assets/css/style.css +++ b/docs/pages/assets/css/style.css @@ -4,11 +4,11 @@ body { } .otoColor { - background-color: #2596be; + background-color: #afcb37; } a { - color: #2596be; + color: #afcb37; text-decoration: underline; } @@ -62,7 +62,7 @@ a:hover { } .titleOnLine li:nth-child(even) { - color: #2596be; + color: #afcb37; } h1 { @@ -144,7 +144,7 @@ h2 { height: 100px; width: 100px; position: relative; - border: 3px solid #2596be; + border: 3px solid #afcb37; border-radius: 50%; margin: auto; margin-top: 50px; @@ -152,7 +152,7 @@ h2 { .inner-circle { position: absolute; - background: #2596be; + background: #afcb37; border-radius: 50%; height: 90px; width: 90px; @@ -171,7 +171,7 @@ h2 { } .sidebar { - background: linear-gradient(90deg, #2596be 50%, #2E3031 50%); + background: linear-gradient(90deg, #afcb37 50%, #2E3031 50%); position: fixed; top: 0; bottom: 0; @@ -250,14 +250,14 @@ h2 { flex-direction: column; } .sidebar { - background: linear-gradient(180deg, #2596be 50%, #2E3031 50%); + background: linear-gradient(180deg, #afcb37 50%, #2E3031 50%); position: inherit; } .footer-contentN2 { margin-left: 0px; margin-top: 20px; width: 100%; - background-color: #2596be; + background-color: #afcb37; } .intro { text-align: left; diff --git a/docs/pages/assets/img/svg/meteole-git.svg b/docs/pages/assets/img/svg/meteole-git.svg new file mode 100644 index 0000000..552bbfb --- /dev/null +++ b/docs/pages/assets/img/svg/meteole-git.svg @@ -0,0 +1 @@ +This attachment was removed because it contains data that could pose a security risk. \ No newline at end of file diff --git a/docs/pages/coverage_parameters.md b/docs/pages/coverage_parameters.md new file mode 100644 index 0000000..0b69fa4 --- /dev/null +++ b/docs/pages/coverage_parameters.md @@ -0,0 +1,74 @@ +Weather forecasts from Météo-France APIs are based on key parameters that vary from indicator to indicator, which can make them complex to use. + +Understanding coverages is a must to have a comprehensive usage of Météo-France forecasting models like AROME or ARPEGE. + +## Coverage_id + +### Introduction +A coverage_id looks like that: + +> WIND_SPEED__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND___2024-01-16T09.00.00Z + +It contains several information in a single string: + +- WIND_SPEED: Indicates that the data pertains to wind speed. +- SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND: Specifies that the measurement is taken at a particular height above the ground. +- 2024-01-16T09.00.00Z: Represents the date and time of the measurement, in ISO 8601 format (January 16, 2024, at 09:00 UTC). + +if you want to display valid coverage_id, you can use `get_capabilities`: + +```python +from meteole import AromeForecast + +arome = AromeForecast(application_id=application_id) + +arome.get_capabilities() +``` + +### Time-series coverages + +Some coverages can contain an additional suffix named `interval`: + +> TEMPERATURE__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND___2024-01-16T09.00.00Z_PT1H + +`PT1H` Specifies the interval, meaning the data is provided at 1-hour intervals. + +When no interval is specified, it means coverage returns a single datapoint instead of a timeseries. + +## Others parameters +### Forecast_horizons +The time of day to which the prediction corresponds must be specified. For example, for a run of 12:00, in 1 hour's time, we have the weather indicator prediction of 13:00. +The `get_coverage method` takes as parameter the list of forecast hours, named `forecast_horizons`. + +To get the list of available `forecast_horizons`, use the function `get_coverage_description` as described in the example below. + +```python +from meteole import arome + +arome_client = arome.AromeForecast(application_id=APPLICATION_ID) + +# Create coverage_id +capabilities = arome_client.get_capabilities() +indicator = 'V_COMPONENT_OF_WIND_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND' +coverage_id = capabilities[capabilities['indicator'] == indicator]['id'].iloc[0] + +# get the description of the coverage +coverage_axis = arome.get_coverage_description(coverage_id) + +# retrieve the available forecast_horizons +coverage_axis['forecast_horizons'] +``` + +### Heights and Pressures + +Atmospheric parameters can be measured at various heights and pressure levels, providing comprehensive data for weather analysis and forecasting. In consequence, some coverages must be queried with a `height` or `pressure` parameter. + +To get the list of available `height` or `pressure` parameters, use the function `get_coverage_description` like `forecast_horizons`. + +```python +coverage_axis['heights'] +coverage_axis['pressures'] +``` + +### Geographical Coverage +The geographical coverage of forecasts can be customized using the `lat` and `long` parameters. By default, Meteole retrieves data for the entire metropolitan France. diff --git a/docs/pages/how_to.md b/docs/pages/how_to.md index 8b4ff52..338a220 100644 --- a/docs/pages/how_to.md +++ b/docs/pages/how_to.md @@ -1,25 +1,19 @@ -## Installation - -Ensure that you have correctly installed **Meteole** before (check [Installation page](installation.md) for details) - -```python -pip install meteole -``` +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 1. Create an account on [the Météo-France API portal](https://portail-api.meteofrance.fr/). 2. Subscribe to the desired services (Arome, Arpege, etc.). -3. Retrieve the API token (or key) by going to “Mes APIs” and then Générer token”. +3. Retrieve the API token (or key) by going to "Mes APIs" and then "Générer token". > 💡 -> +> > Using an APPLICATION_ID allows for token auto-refresh. It avoids re-generating a token or an API key when it is expired. > -> Find your APPLICATION_ID in your [API dashboard](https://portail-api.meteofrance.fr/web/fr/dashboard) > "Générer Token". -> -> Then checkout the `curl` field at the bottom of the page that looks like that: -> ```bash +> Find your APPLICATION_ID in your [API dashboard](https://portail-api.meteofrance.fr/web/fr/dashboard) > "Générer Token". +> +> Then checkout the `curl` field at the bottom of the page that looks like that: +> ```bash > curl -k -X POST https://portail-api.meteofrance.fr/token -d "grant_type=client_credentials" -H "Authorization: Basic ktDvFBDP8w6jGfKuK4yB1nS6oLOK4bfoFwEqmANOIvNMF8vG6B51tgJeZQcOO1d3qYyK" > ``` > @@ -35,15 +29,15 @@ For data usage, access the predicted phenomena to trigger modeling based on the from meteole import Vigilance # application_id: obtain it on the Météo-France API portal -client = Vigilance(application_id=APPLICATION_ID) +client = Vigilance(application_id=APPLICATION_ID) -df_phenomenon, df_timelaps = client.get_phenomenon() +df_phenomenon, df_timelaps = client.get_phenomenon() # Fetch vigilance bulletins -textes_vigilance = client.get_vigilance_bulletin() +textes_vigilance = client.get_vigilance_bulletin() # Display the vigilance vignette -client.get_vignette() +client.get_vignette() ``` ![bulletin vigilance](./assets/img/png/vignette_exemple.png) @@ -52,7 +46,7 @@ client.get_vignette() ## Get AROME or ARPEGE data -The flagship weather forecasting models of Météo-France are accessible via the Météo-France APIs. +Meteole allows you to retrieve forecasts for a wide range of weather indicators. Here's how to get started with AROME and ARPEGE: | Characteristics | AROME | ARPEGE | |------------------|----------------------|----------------------| @@ -61,84 +55,24 @@ The flagship weather forecasting models of Météo-France are accessible via the | Forecast Range | Up to 51 hours | Up to 114 hours | ```python -from meteole import arome - -arome_client = arome.AromeForecast(application_id=APPLICATION_ID) # api_key found on portail.meteo-france.Fr - -# get all available coverages -# coverage: a string containing indicator + run -capabilities = arome_client.get_capabilities() - -# fetch a valid coverage_id for WIND_GUST -indicator = 'V_COMPONENT_OF_WIND_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND' -coverage_id = capabilities[capabilities['indicator'] == indicator]['id'].iloc[0] - -# get the data -# (params heights and forecast_horizons default to their first allowed value) -df_arome = arome_client.get_coverage(coverage_id) +from meteole import AromeForecast + +# Initialize the AROME forecast client +arome_client = AromeForecast(application_id=APPLICATION_ID) # APPLICATION_ID found on portail.meteo-france.Fr + +# Check indicators available +print(arome_client.indicators) + +# Fetch weather data +df_arome = arome_client.get_coverage( + indicator="V_COMPONENT_OF_WIND_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND", # Optional: if not, you have to fill coverage_id + run="2025-01-10T00:00:00Z", # Optional: forecast start time + interval=None, # Optional: time range for predictions + forecast_horizons=[0, 1, 2], # Optional: prediction times (in hours) + heights=[10], # Optional: height above ground level + pressures=None, # Optional: pressure level + coverage_id=None # Optional: an alternative to indicator/run/interval +) ``` -## Advanced guide: coverages - -### Introduction - -Understanding coverages is a must to have a comprehensive usage of Météo-France forecasting models like AROME or ARPEGE. - -A coverageid looks like that: - -> WIND_SPEED__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND___2024-01-16T09.00.00Z - -It contains several information in a single string: - -- WIND_SPEED: Indicates that the data pertains to wind speed. -- SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND: Specifies that the measurement is taken at a particular height above the ground. -- 2024-01-16T09.00.00Z: Represents the date and time of the measurement, in ISO 8601 format (January 16, 2024, at 09:00 UTC). - -### Time-series coverages - -Some coverages can contain an additional suffix: - -> TEMPERATURE__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND___2024-01-16T09.00.00Z_PT1H - -`PT1H` Specifies the interval, meaning the data is provided at 1-hour intervals. - -When no interval is specified, it means coverage returns a single datapoint instead of a timeseries. - -### Height - -Atmospheric parameters can be measured at various heights and pressure levels, providing comprehensive data for weather analysis and forecasting. In consequence, some coverages must be queried with a `height` parameter. - -To get the list of available `height` parameters, use the function `get_coverage_description` as described in the example below. - -```python -from meteole import arome - -arome_client = arome.AromeForecast(application_id=APPLICATION_ID) # api_key found on portail.meteo-france.Fr - -# get all available coverage ids with `get_capabilities` -capabilities = arome_client.get_capabilities() - -# fetch a valid coverage_id for WIND_GUST -indicator = 'V_COMPONENT_OF_WIND_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND' -coverage_id = capabilities[capabilities['indicator'] == indicator]['id'].iloc[0] - -# get the description of the coverage -coverage_axis = arome.get_coverage_description(random_coverage_id) - -# retrieve the available heights -coverage_axis['heights'] -``` - -Similarly, the AROME and ARPEGE can have different time step forecast prediction depending on the indicator. - -For example: - -- `TODO` is defined every horu for the next 114 hours. -- `TODO` is defined every hour for the next 51 hours, and then every 3 hours. - -Get the list of the available `forecast_horizons` using, once again, `get_coverage_description`. - -```python -# retrieve the available times -coverage_axis['times'] -``` +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). \ No newline at end of file diff --git a/docs/pages/index.html b/docs/pages/index.html index 54eab70..2d3298a 100644 --- a/docs/pages/index.html +++ b/docs/pages/index.html @@ -48,19 +48,20 @@

- Meteole provides a python wrapper around Météo-France APIs to facilitate models exploration and data retrieval. + Meteole is a Python client library for weather forecast model APIs (e.g., Météo-France).

Features

    -
  • Météo-France API token management
    • -
  • Arome/Arpege forecasts
    • -
  • Vigilance bulletins
    • +
  • Automated token management: Simplify authentication with a single `application_id`.
    • +
  • Unified model usage: AROME and ARPEGE forecasts with a consistent interface.
    • +
  • User-friendly parameter handling: Intuitive management of key weather forecasting parameters.
    • +
  • Seamless data integration: Directly export forecasts as Pandas DataFrames.
    • +
  • Vigilance bulletins: Retrieve real-time weather warnings across France.
@@ -83,7 +84,7 @@

high adaptability

- +

DOC

From 10721b9e587969b14d9b62be6c538ed317db13e5 Mon Sep 17 00:00:00 2001 From: GratienDSX <11066079+GratienDSX@users.noreply.github.com> Date: Mon, 6 Jan 2025 11:41:11 +0100 Subject: [PATCH 2/2] Update coverage_parameters.md Signed-off-by: GratienDSX <11066079+GratienDSX@users.noreply.github.com> --- docs/pages/coverage_parameters.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/coverage_parameters.md b/docs/pages/coverage_parameters.md index 0b69fa4..68588c7 100644 --- a/docs/pages/coverage_parameters.md +++ b/docs/pages/coverage_parameters.md @@ -1,4 +1,4 @@ -Weather forecasts from Météo-France APIs are based on key parameters that vary from indicator to indicator, which can make them complex to use. +Weather forecasts from Météo-France APIs are based on key parameters that vary from indicator to indicator, which makes them complex to use. Understanding coverages is a must to have a comprehensive usage of Météo-France forecasting models like AROME or ARPEGE. @@ -15,7 +15,7 @@ It contains several information in a single string: - SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND: Specifies that the measurement is taken at a particular height above the ground. - 2024-01-16T09.00.00Z: Represents the date and time of the measurement, in ISO 8601 format (January 16, 2024, at 09:00 UTC). -if you want to display valid coverage_id, you can use `get_capabilities`: +if you want to display all valid coverage_ids, you can use `get_capabilities`: ```python from meteole import AromeForecast @@ -38,7 +38,7 @@ When no interval is specified, it means coverage returns a single datapoint inst ## Others parameters ### Forecast_horizons The time of day to which the prediction corresponds must be specified. For example, for a run of 12:00, in 1 hour's time, we have the weather indicator prediction of 13:00. -The `get_coverage method` takes as parameter the list of forecast hours, named `forecast_horizons`. +The `get_coverage method` takes as (optional) parameter the list of desired forecast hours, named `forecast_horizons`. To get the list of available `forecast_horizons`, use the function `get_coverage_description` as described in the example below.