Merge branch 'main' into docs/update_readme

MAIF · Jan 6, 2025 · 228ec4c · 228ec4c
2 parents 4435bd2 + 03bb9c1
commit 228ec4c
Show file tree

Hide file tree

Showing 8 changed files with 140 additions and 127 deletions.
diff --git 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
diff --git 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
@@ -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,15 +144,15 @@ h2 {
   height: 100px;
   width: 100px;
   position: relative;
-  border: 3px solid #2596be;
+  border: 3px solid #afcb37;
   border-radius: 50%;
   margin: auto;
   margin-top: 50px;
 }
 
 .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
diff --git a/docs/pages/coverage_parameters.md 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
@@ -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).
diff --git a/docs/pages/index.html b/docs/pages/index.html
@@ -48,19 +48,20 @@
           <div class="col-md-6 col-xs-12 colDashRight">
             <ul class="titleOnLine">
               <li>Easy access</li>
-              <li>to Météo-France</li>
-              <li>weather models</li>
+              <li>to weather models</li>
               <li>and data</li>
             </ul>
             <p class="intro">
-              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).
             </p>
             <div class="details">
               <h1>Features</h1>
               <ul>
-                <li>Météo-France API token management</li>
-                <li>Arome/Arpege forecasts</li>
-                <li>Vigilance bulletins</li>
+                <li><strong>Automated token management:</strong> Simplify authentication with a single `application_id`.</li>
+                <li><strong>Unified model usage:</strong> AROME and ARPEGE forecasts with a consistent interface.</li>
+                <li><strong>User-friendly parameter handling:</strong> Intuitive management of key weather forecasting parameters.</li>
+                <li><strong>Seamless data integration:</strong> Directly export forecasts as Pandas DataFrames.</li>
+                <li><strong>Vigilance bulletins:</strong> Retrieve real-time weather warnings across France.</li>
               </ul>
             </div>
           </div>
@@ -83,7 +84,7 @@ <h2>high adaptability</h2>
                 </a>
               </div>
               <div class="col-md-12 col-xs-4">
-                <a href="https://meteole.readthedocs.io/en/latest/">
+                <a href="./home/">
                   <div class="outer-circle">
                     <div class="inner-circle">
                       <p>DOC</p>