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..68588c7 --- /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 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. + +## 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 all valid coverage_ids, 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 (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. + +```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

@@ -83,7 +84,7 @@

high adaptability

- +

DOC

diff --git a/docs/pages/why.md b/docs/pages/why.md index a3f1457..0ac472b 100644 --- a/docs/pages/why.md +++ b/docs/pages/why.md @@ -4,20 +4,21 @@ There is one reason for using **Meteole**: ## Before Meteole :cloud_with_rain: -Accessing weather data from Météo-France via Python can be a bit cumbersome and time-consuming. +Accessing weather data from Météo-France via Python could be quite challenging and time-consuming. -It involves: +It involved: -* diving into Météo-France documentation -* handling expiring tokens -* managing XML responses -* explore specificities for every indicator -* parse responses to get a clean dataframe +* Diving into Météo-France documentation +* Handling expiring tokens manually +* Managing XML responses +* Dealing with the specificities of each weather indicator +* Parsing responses to get a clean dataframe ## After Meteole :sunny: -**Meteole** allows to quickly fetch tidy pandas dataframes full of weather-rich data: +**Meteole** simplifies the process, allowing you to quickly fetch tidy pandas dataframes full of weather-rich data: -* By handling the API boilerplate; -* By providing simple and well-documented function; -* By using heuristics when necessary parameters are not provided ; +* By handling the API boilerplate +* By providing simple and well-documented function +* By using heuristics when necessary parameters are not provided +* By providing options to use individual parameters or a coverage_id for weather indicators