Détermination objective du meilleur jour de la semaine

.env.example

@@ -5,3 +5,10 @@ INFLUXDB_BUCKET=weather
 STATION_LATITUDE=
 STATION_LONGITUDE=
 STATION_ELEVATION=
+
+# Chronos (prévision)
+# CHRONOS_MODEL=amazon/chronos-t5-small
+# CHRONOS_CONTEXT=336
+# CHRONOS_HORIZON=96
+# CHRONOS_RESAMPLE=1h
+# CHRONOS_SAMPLES=20

.gitignore

@@ -3,3 +3,5 @@
 data
 __pycache__
 .DS_Store
+blog/
+scripts/build_blog_from_docs.py

docs/01 - Installation, configuration et tests/index.md

@@ -2,7 +2,8 @@
 
 ## Installation de l'environnement de base
 
-Après avoir cloné le dépôt :
+Après avoir cloné le dépôt, on commence par préparer un environnement Python isolé pour ne pas polluer le système global et pouvoir supprimer facilement tout ce qui concerne ce projet.
+L’idée est de regrouper au même endroit le moteur [`Python`](https://www.python.org/), les bibliothèques scientifiques et le client pour la base de données [`InfluxDB`](https://www.influxdata.com/), qui stocke nos séries temporelles.
 
 ```shell
 python3 -m venv .venv
@@ -12,11 +13,11 @@ pip install -r requirements.txt
 python -c "import pandas, influxdb_client, sklearn; print('OK')"
 ```
 
-- On installe l'environnement virtuel de python
-- On entre dans cet environnement
-- On met à jour le gestionnaire de paquets pip
-- On installe les dépendances définies dans `requirements.txt`
-- On vérifie que les dépendances sont correctement installées
+- `python3 -m venv .venv` crée un environnement virtuel Python local dans le dossier `.venv`, ce qui permet d’isoler les paquets de ce projet du reste du système (voir par exemple la documentation sur les environnements virtuels [`venv`](https://docs.python.org/fr/3/library/venv.html)).
+- `source .venv/bin/activate` active cet environnement dans le shell courant ; tant qu’il est actif, la commande `python` pointera vers l’interpréteur de `.venv` et non vers celui du système.
+- `python -m pip install --upgrade pip` met à jour [`pip`](https://pip.pypa.io/), le gestionnaire de paquets de Python, afin d’éviter les bugs ou limitations des versions trop anciennes.
+- `pip install -r requirements.txt` installe toutes les dépendances nécessaires au projet (notamment [`pandas`](https://pandas.pydata.org/), le client Python pour InfluxDB et [`scikit-learn`](https://scikit-learn.org/stable/) pour les modèles prédictifs) en suivant la liste déclarée dans `requirements.txt`.
+- `python -c "import pandas, influxdb_client, sklearn; print('OK')"` vérifie que les principales bibliothèques s’importent correctement ; si la commande affiche `OK`, l’environnement de base est prêt à être utilisé.
 
 ## Configuration
 
@@ -24,23 +25,26 @@ python -c "import pandas, influxdb_client, sklearn; print('OK')"
 cp .env.example .env
 ```
 
-On copie le fichier de configuration d'exemple, puis on l'ouvre pour l'adapter à notre cas.
+On copie le fichier de configuration d'exemple, puis on l'ouvre pour l'adapter à notre cas. Ce fichier `.env` sera lu automatiquement par les scripts via [`python-dotenv`](https://github.com/theskumar/python-dotenv) (voir `meteo/config.py`), ce qui évite d’exporter les variables à la main à chaque session.
 
-- `INFLUXDB_URL` : URL de l'api du serveur InfluxDB2 (cela inclue probablement le port 8086)
-- `INFLUXDB_TOKEN` : le jeton d'authentification à créer dans votre compte InfluxDB2
-- `INFLUXDB_ORG` : l'organisation à laquelle le token est rattaché
-- `INFLUXDB_BUCKET` : le nom du bucket dans lequel les données sont stockées
-- `STATION_LATITUDE` : latitude GPS de la station météo
-- `STATION_LONGITUDE` : longitude GPS de la station météo
-- `STATION_ELEVATION` : altitude de la station météo
+- `INFLUXDB_URL` : URL de l'API du serveur InfluxDB 2.x (incluant généralement le port 8086), par exemple `http://localhost:8086` ou l’adresse de votre serveur ; c’est le point d’entrée HTTP/HTTPS vers votre base de données de séries temporelles (voir aussi l’introduction aux [bases de données de séries temporelles](https://fr.wikipedia.org/wiki/Base_de_donn%C3%A9es_de_s%C3%A9ries_temporelles)).
+- `INFLUXDB_TOKEN` : jeton d'authentification généré dans l’interface d’[`InfluxDB 2.x`](https://docs.influxdata.com/influxdb/v2/), associé à un jeu de permissions (lecture/écriture) ; sans ce token, le client Python ne peut pas interroger le serveur.
+- `INFLUXDB_ORG` : nom de l'organisation InfluxDB à laquelle le token est rattaché ; InfluxDB 2.x organise les ressources (utilisateurs, buckets, tokens) par organisation, il faut donc préciser celle que l’on souhaite utiliser.
+- `INFLUXDB_BUCKET` : nom du bucket (espace logique de stockage avec sa politique de rétention) dans lequel les données sont enregistrées ; c’est ce bucket que les scripts interrogeront pour récupérer les mesures de la station.
+- `STATION_LATITUDE` : latitude GPS de la station météo (en degrés décimaux), utilisée plus loin pour les calculs d’élévation solaire et pour enrichir les données avec des métadonnées astronomiques.
+- `STATION_LONGITUDE` : longitude GPS de la station météo (en degrés décimaux), nécessaire pour les mêmes raisons que la latitude.
+- `STATION_ELEVATION` : altitude de la station météo (en mètres au-dessus du niveau de la mer) ; cette information affine légèrement certains calculs physiques, mais reste optionnelle si l’altitude est mal connue.
 
 ## Tests de l'environnement de travail
 
+Avant d’attaquer des analyses plus lourdes, on vérifie que la connexion au serveur InfluxDB fonctionne bien et que la configuration est cohérente.
+Les scripts de test qui suivent n’écrivent rien dans la base : ils se contentent d’effectuer quelques requêtes simples pour valider l’accès.
+
 ```shell
 python "docs/01 - Installation, configuration et tests/scripts/test_influx_connection.py"
 ```
 
-```output
+```text
 Configuration InfluxDB chargée :
   URL    : http://10.0.3.2:8086
   Org    : Dern
@@ -57,13 +61,15 @@ Exemple de point :
   value     : humidity
 ```
 
+Si vous obtenez un résultat similaire (URL affichée, ping OK, requête de test qui retourne quelques enregistrements), c’est que le serveur InfluxDB est joignable, que le token est valide et que le bucket indiqué existe bien.
+
 Ensuite, on peut demander à InfluxDB de nous détailler ce qu'il stocke :
 
 ```shell
 python "docs/01 - Installation, configuration et tests/scripts/test_influx_schema.py"
 ```
 
-```output
+```text
 Bucket InfluxDB : weather
 
 Measurements disponibles :
@@ -115,13 +121,16 @@ Champs pour measurement « °C » :
   - value (type: unknown)
 ```
 
+Ce deuxième script interroge le schéma du bucket : il liste les _measurements_ (grandeurs physiques comme `%`, `°C`, `km/h`, etc.), ainsi que les champs associés à chacun.
+Dans InfluxDB, un _measurement_ correspond en gros à un type de mesure (par exemple une unité), et les _fields_ contiennent les valeurs numériques que l’on exploitera plus tard ; les metadata (comme `entity_id`) sont stockées sous forme de _tags_ (voir la documentation sur le [modèle de données InfluxDB](https://docs.influxdata.com/influxdb/v2/reference/key-concepts/data-elements/)).
+
 Mais pour obtenir les données dont on a besoin, il faut aussi connaitre les entités manipulées par Influx :
 
 ```shell
 python "docs/01 - Installation, configuration et tests/scripts/test_influx_entities.py"
 ```
 
-```output
+```text
 Bucket InfluxDB : weather
 
 Measurement « % »
@@ -202,6 +211,9 @@ Measurement « °C »
     - station_meteo_bresser_exterieur_temperature
 ```
 
-Ces informations combinées se retrouvent dans le fichier `meteo/station_config.py` et dans `meteo/variables.py`.
+Ce dernier script fait le lien avec la source des données : il dresse la liste des clés de tags et des `entity_id` possibles pour chaque _measurement_.
+Ces identifiants correspondent aux entités exposées par votre système domotique (par exemple [`Home Assistant`](https://www.home-assistant.io/)), et permettent de distinguer clairement l’humidité extérieure, la pression, la vitesse du vent, etc.
+
+Ces informations combinées se retrouvent dans le fichier `meteo/station_config.py` et dans `meteo/variables.py` : c’est là que l’on fixe, une fois pour toutes, quelles entités InfluxDB seront considérées comme « température extérieure », « pluie », « vent », et sous quels noms elles seront manipulées dans la suite de l’étude.
 
 On aurait pu se passer de ces scripts pour déterminer la structure des données stockées dans Influx, mais ils évitent de se reposer sur des intuitions : ici, on demande à Influx de nous donner les informations dont on va avoir besoin au lieu de les deviner.

docs/02 - Préparation des données/index.md

@@ -1,6 +1,7 @@
 # Préparation des données
 
-Cette étape regroupe l'export initial depuis InfluxDB ainsi que les scripts d'ajustement nécessaires pour obtenir un dataset minuté propre.
+Cette étape regroupe l'export initial depuis InfluxDB ainsi que les scripts d'ajustement nécessaires pour obtenir un dataset minuté propre, c’est‑à‑dire une [série temporelle](https://fr.wikipedia.org/wiki/S%C3%A9rie_temporelle) où chaque minute possède une observation complète pour toutes les variables utiles.
+L’objectif est de passer d’un format brut, pensé pour la domotique temps réel, à un format tabulaire lisible par les bibliothèques d’analyse comme `pandas`.
 
 ## Export des données
 
@@ -8,10 +9,13 @@ Cette étape regroupe l'export initial depuis InfluxDB ainsi que les scripts d'a
 python "docs/02 - Préparation des données/scripts/export_station_data.py"
 ```
 
+Ce script se connecte au serveur InfluxDB configuré au chapitre précédent, interroge les mesures de la station sur une fenêtre récente (par défaut les sept derniers jours) et les exporte dans un fichier CSV `data/weather_raw_7d.csv`.
+On quitte ainsi la base de données de séries temporelles pour un format beaucoup plus simple à manipuler avec `pandas`, tout en conservant l’horodatage précis.
+
 La sortie est assez longue, et inclut un certain nombre d'avertissements qui peuvent être ignorés.
 L'important est que le script se termine sur :
 
-```output
+```text
 ✔ Export terminé : /Users/richard/Documents/donnees_meteo/data/weather_raw_7d.csv
 ```
 
@@ -25,18 +29,24 @@ Vérifiez que le fichier est bien créé et qu'il contient des données.
 python "docs/02 - Préparation des données/scripts/export_station_data_full.py"
 ```
 
-Au lieu de télécharger les données des 7 derniers jours, l'ensemble des données stockées sur le serveur pour ce bucket seront téléchargées, ce qui, selon la granularité et l'ancienneté des données peut prendre un certain temps et occuper un espace disque conséquent.
+Au lieu de télécharger les données des sept derniers jours, l'ensemble des données stockées sur le serveur pour ce _bucket_ seront téléchargées, ce qui, selon la granularité et l'ancienneté des données, peut prendre un certain temps et occuper un espace disque conséquent.
 Mon fichier complet contient plus d'un million d'enregistrements et pèse 70 Mo.
 
+En pratique, il est souvent plus confortable de développer et tester les scripts suivants sur quelques jours de données (fichier `weather_raw_7d.csv`), puis de relancer le pipeline complet sur l’historique complet une fois les étapes stabilisées.
+Les deux scripts s’appuient sur l’API HTTP d’[InfluxDB 2.x](https://docs.influxdata.com/influxdb/v2/) et son langage de requête Flux (voir la documentation dédiée à [Flux](https://docs.influxdata.com/flux/v0.x/)).
+
 ## Ajustements
 
+Le CSV exporté reste très proche du format de stockage utilisé par la domotique : chaque capteur envoie une mesure à des instants légèrement différents, et InfluxDB stocke donc plusieurs lignes par seconde, chacune ne contenant qu’une seule variable renseignée.
+Pour l’analyse statistique, on cherche au contraire à obtenir une table où chaque horodatage regroupe toutes les variables de la station sur une grille temporelle régulière.
+
 Le fichier peut être rapidement inspecté avec la commande `head` :
 
 ```shell
 head data/weather_raw_full.csv
 ```
 
-```output
+```text
 time,temperature,humidity,pressure,illuminance,wind_speed,wind_direction,rain_rate
 2025-03-10 09:35:23.156646+00:00,,,996.95,,,,
 2025-03-10 09:35:23.158538+00:00,10.6,,,,,,
@@ -49,7 +59,8 @@ time,temperature,humidity,pressure,illuminance,wind_speed,wind_direction,rain_ra
 2025-03-10 09:36:22.640356+00:00,,,,,,306.0,
 ```
 
-On peut voir que HomeAssistant écrit une nouvelle entrée pour chaque capteur, alors qu'on aurait pu s'attendre à une ligne unique pour l'ensemble des capteurs.
+On peut voir que [Home Assistant](https://www.home-assistant.io/) écrit une nouvelle entrée pour chaque capteur, alors qu'on aurait pu s'attendre à une ligne unique pour l'ensemble des capteurs.
+C’est un format très pratique pour la collecte temps réel, mais moins confortable pour l’analyse : il faut d’abord tout remettre en forme.
 
 Le script suivant s'occupe de regrouper les données de capteurs dont l'enregistrement est proche :
 
@@ -57,7 +68,7 @@ Le script suivant s'occupe de regrouper les données de capteurs dont l'enregist
 python "docs/02 - Préparation des données/scripts/format_raw_csv.py"
 ```
 
-```output
+```text
 Fichier brut chargé : data/weather_raw_full.csv
   Lignes : 1570931, colonnes : ['temperature', 'humidity', 'pressure', 'illuminance', 'wind_speed', 'wind_direction', 'rain_rate']
   Type d'index : <class 'pandas.core.indexes.datetimes.DatetimeIndex'>
@@ -66,12 +77,15 @@ Après combinaison (1s) : 630171 lignes
 ```
 
 Un nouveau document CSV intermédiaire est donc créé.
+On voit que l’on passe d’environ 1,57 million de lignes à 630 000 lignes « combinées » : le script regroupe les mesures de tous les capteurs tombant dans la même seconde, en utilisant l’horodatage comme clé.
+L’index de type `DatetimeIndex` indiqué dans la sortie est l’axe temporel standard de `pandas` (voir la documentation de [`pandas.DatetimeIndex`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DatetimeIndex.html)).
+Cette étape correspond à une première forme de rééchantillonnage temporel, classique lorsqu’on prépare une série pour l’analyse.
 
 ```shell
 head data/weather_formatted_1s.csv
 ```
 
-```output
+```text
 time,temperature,humidity,pressure,illuminance,wind_speed,wind_direction,rain_rate
 2025-03-10 09:35:23+00:00,10.6,83.0,996.95,,7.4,256.0,0.0
 2025-03-10 09:35:41+00:00,,,,20551.2,,,
@@ -84,7 +98,8 @@ time,temperature,humidity,pressure,illuminance,wind_speed,wind_direction,rain_ra
 2025-03-10 09:40:22+00:00,,,,19720.8,10.0,209.0,
 ```
 
-Il reste des cellules vides : en effet, HA n'enregistre pas la valeur d'un capteur si elle n'a pas changé depuis la dernière fois.
+Il reste des cellules vides : en effet, Home Assistant n'enregistre pas la valeur d'un capteur si elle n'a pas changé depuis la dernière fois.
+On se retrouve donc avec une série temporelle à pas régulier (1 s), mais encore parsemée de trous.
 
 On fait donc :
 
@@ -92,20 +107,22 @@ On fait donc :
 python "docs/02 - Préparation des données/scripts/fill_formatted_1s.py"
 ```
 
-```output
+```text
 Fichier 1s formaté chargé : data/weather_formatted_1s.csv
   Lignes : 630171, colonnes : ['temperature', 'humidity', 'pressure', 'illuminance', 'wind_speed', 'wind_direction', 'rain_rate']
 Après propagation des dernières valeurs connues : 630171 lignes
 ✔ Fichier 1s 'complet' écrit dans : /Users/richard/Documents/donnees_meteo/data/weather_filled_1s.csv
 ```
 
+Cette seconde passe applique un remplissage par propagation de la dernière valeur connue (_forward fill_ ou `ffill` dans `pandas`) : tant qu’un capteur ne publie pas de nouvelle mesure, on considère que la précédente reste valable. C’est une hypothèse raisonnable pour des variables relativement lisses comme la température ou la pression, moins pour des phénomènes très brusques ; l’objectif ici est surtout d’obtenir un _dataset_ sans [valeurs manquantes](https://fr.wikipedia.org/wiki/Donn%C3%A9es_manquantes), ce qui simplifie grandement les analyses et les modèles dans les chapitres suivants.
+
 ## Enrichissements (saisons et position du soleil)
 
-Une fois les données nettoyées, on peut les enrichir avec des métadonnées météorologiques simples :
+Une fois les données nettoyées, on peut les enrichir avec des métadonnées météorologiques simples, qui aideront ensuite à interpréter les graphiques et à construire des modèles plus pertinents :
 
-- regrouper les points par minute,
-- ajouter la saison correspondant à chaque observation (en fonction de l'hémisphère),
-- calculer la hauteur du soleil si la latitude/longitude de la station sont configurées.
+- regrouper les points par minute, pour lisser légèrement le bruit tout en restant réactif ; ce pas de 60 secondes est un bon compromis entre fidélité au signal brut et taille raisonnable du _dataset_ ;
+- ajouter la saison correspondant à chaque observation (en fonction de l'hémisphère), ce qui permet de comparer facilement les comportements printemps/été/automne/hiver et de relier nos courbes aux notions classiques de [saisons](https://fr.wikipedia.org/wiki/Saison) en météorologie ;
+- calculer la hauteur du soleil si la latitude/longitude de la station sont configurées, afin de disposer d’une estimation de l’élévation solaire au‑dessus de l’horizon (jour/nuit, midi solaire, etc.) en s’appuyant sur la bibliothèque d’astronomie [`astral`](https://astral.readthedocs.io/).
 
 Ces opérations sont réalisées par :
 
@@ -113,26 +130,34 @@ Ces opérations sont réalisées par :
 python "docs/02 - Préparation des données/scripts/make_minutely_dataset.py"
 ```
 
-Le script produit `data/weather_minutely.csv`. Pensez à définir `STATION_LATITUDE`, `STATION_LONGITUDE` et `STATION_ELEVATION` dans votre `.env` pour permettre le calcul de la position du soleil ; sinon, seule la colonne `season` sera ajoutée.
+Le script produit `data/weather_minutely.csv`. Chaque ligne de ce fichier correspond à une minute, avec toutes les variables météo alignées (température, humidité, pression, vent, pluie, etc.) et, si les coordonnées de la station sont connues, des colonnes supplémentaires comme la saison et l’élévation du soleil.
+
+> Pensez à définir `STATION_LATITUDE`, `STATION_LONGITUDE` et `STATION_ELEVATION` dans votre `.env` pour permettre le calcul de la position du soleil ; sinon, seule la colonne `season` sera ajoutée.
+
+Ce fichier minuté est le jeu de données de référence utilisé dans la majorité des chapitres suivants.
 
 ## Pipeline simplifié
 
-Un script tout simple permet de faire automatiquement tout ce qu'on vient de voir.
+Un script tout simple permet de faire automatiquement tout ce qu'on vient de voir, dans le bon ordre, sans avoir à lancer chaque étape à la main.
 Il supprime **tous** les fichiers CSV existants : il faudra donc relancer la génération des images dans les étapes suivantes pour qu'elles intègrent les nouvelles données.
 
 ```shell
 python -m scripts.refresh_data_pipeline
 ```
 
+Ce module Python orchestre l’export depuis InfluxDB, la mise en forme à 1 seconde, le remplissage des valeurs manquantes puis la construction du dataset minuté.
+Le fait de repartir de zéro à chaque exécution garantit que `weather_minutely.csv` reflète bien l’état actuel de la base, au prix d’un temps de calcul un peu plus long.
+
 ## Vérification des données
 
-On peut s'assurer que plus aucune information n'est manquante :
+Avant d’explorer les graphiques ou de lancer des modèles, on vérifie que le dataset minuté est cohérent : pas de valeurs manquantes, des ordres de grandeur plausibles, et une grille temporelle effectivement régulière.
+On peut d’abord s'assurer que plus aucune information n'est manquante :
 
 ```shell
 python "docs/02 - Préparation des données/scripts/check_missing_values.py"
 ```
 
-```output
+```text
 Dataset chargé : data/weather_minutely.csv
   Lignes   : 321881
   Colonnes : ['temperature', 'humidity', 'pressure', 'illuminance', 'wind_speed', 'wind_direction', 'rain_rate']
@@ -156,13 +181,15 @@ Valeurs manquantes par colonne :
 ✔ Aucune valeur manquante dans le dataset minuté.
 ```
 
+Ce premier contrôle confirme que toutes les lignes de `weather_minutely.csv` sont complètes : aucune cellule n’est manquante, ce qui évitera bien des subtilités dans les analyses ultérieures.
+
 Le script suivant nous permet de vérifier rapidement si des problèmes majeurs peuvent être découverts :
 
 ```shell
 python "docs/02 - Préparation des données/scripts/describe_minutely_dataset.py"
 ```
 
-```output
+```text
 Dataset minuté chargé : data/weather_minutely.csv
   Lignes   : 321881
   Colonnes : ['temperature', 'humidity', 'pressure', 'illuminance', 'wind_speed', 'wind_direction', 'rain_rate']                              Période  : 2025-03-10 09:35:00+00:00 → 2025-11-17 00:41:00+00:00
@@ -216,13 +243,17 @@ Name: count, dtype: int64
 Nombre d'intervalles ≠ 60s : 17589
 ```
 
-Ces écarts peuvent être identifiés avec le script suivant :
+Ce deuxième script fournit un aperçu statistique classique (fonction `describe()` de `pandas`) et quelques min/max datés pour chaque variable : on y vérifie que les valeurs restent plausibles (par exemple pas de température à +80 °C ni de vent négatif) et que les extrêmes correspondent à des dates réalistes.
+La section sur les différences d’intervalle permet déjà de repérer que certains pas ne sont pas strictement de 60 secondes, ce qui est courant sur des données issues de capteurs, mais qu’il faut garder en tête pour la suite.
+Ce type de contrôle s’inscrit dans une démarche d’[analyse exploratoire de données](https://fr.wikipedia.org/wiki/Analyse_exploratoire_de_donn%C3%A9es).
+
+Ces écarts peuvent être identifiés plus finement avec le script suivant :
 
 ```shell
 python "docs/02 - Préparation des données/scripts/list_time_gaps.py"
 ```
 
-```
+```text
 Dataset minuté chargé : data/weather_minutely.csv
   Lignes   : 321881
 
@@ -243,8 +274,9 @@ Top 10 des gaps les plus longs :
 - De 2025-06-21 17:25:00+00:00 à 2025-06-21 18:10:00+00:00 (durée: 0 days 00:45:00, manquants: 44, de 2025-06-21 17:26:00+00:00 à 2025-06-21 18:09:00+00:00)
 ```
 
-Ces trous dans les données peuvent correspondre à des pannes de connexion entre la station et mon réseau, un redémarrage de mon serveur (physique ou logiciel), au redémarrage de la box ou du point d'accès sans-fil, etc.
-Ils peuvent aussi correspondre aux modifications opérées dans les scripts précédents.
+Ce troisième script ne corrige rien : il se contente de lister précisément les intervalles dans lesquels des minutes manquent dans la série, ainsi que leur durée.
+Ces trous dans les données peuvent correspondre à des pannes de connexion entre la station et mon réseau, un redémarrage de mon serveur (physique ou logiciel), au redémarrage de la box ou du point d'accès sans‑fil, etc.
+Mais ils peuvent également correspondre aux modifications opérées dans les scripts précédents !
 
 Ces scripts sont intéressants parce qu'ils mettent en évidence des facteurs indirects, contribuant à la qualité des données soumise.
 On peut prendre toutes les précautions, on peut avoir l'intuition d'avoir tout géré, et se rassurer parce qu'on utilise des outils fiables, mais il existera toujours des manques dans les données.

docs/03 - Premiers graphiques/index.md

@@ -1,17 +1,22 @@
 # Premiers graphiques
 
-On peut désormais tracer nos premiers graphiques simples et bruts.
-S'ils ne sont pas très instructifs par rapport à ce que nous fournissent Home Assistant et InfluxDB, ils nous permettent au moins de nous assurer que tout fonctionne, et que les données semblent cohérentes.
-Les fichiers CSV correspondant à chaque figure sont conservés dans `data/` dans ce dossier.
-
-Les graphiques couvrent maintenant toute la période disponible dans `data/weather_minutely.csv`.
-Une agrégation automatique réduit le nombre de points pour rester lisible (plus de courbes "peignes"), et l'axe des dates utilise un format compact qui évite tout chevauchement de labels.
-On peut au besoin restreindre la période avec `--days` ou imposer une fréquence d'agrégation avec `--resample`.
+On peut désormais tracer nos premiers graphiques simples et bruts à partir du dataset minuté construit au chapitre précédent.
+S'ils ne sont pas encore très instructifs par rapport à ce que nous fournissent déjà Home Assistant et InfluxDB, ils nous permettent au moins de nous assurer que tout fonctionne, que les données semblent cohérentes, et que la chaîne « export → préparation → visualisation » tient la route.
+Les scripts de ce chapitre s’appuient sur [`pandas`](https://pandas.pydata.org/) et sur la bibliothèque de visualisation [`Matplotlib`](https://matplotlib.org/) (via le module `meteo.plots`) pour produire des graphiques standards : séries temporelles, _heatmaps_, calendriers.
+Les fichiers CSV correspondant à chaque figure sont conservés dans le sous-dossier `data/` de ce chapitre, ce qui permet de réutiliser directement les séries pré-agrégées si besoin.
 
 ```shell
 python "docs/03 - Premiers graphiques/scripts/plot_basic_variables.py"
 ```
 
+Ce script lit `data/weather_minutely.csv`, sélectionne éventuellement une fenêtre temporelle (par exemple les derniers jours si l’on utilise l’option `--days`) puis choisit une fréquence d’agrégation adaptée pour ne pas saturer le graphique en points.
+Pour chaque variable (température, pression, humidité, pluie, vent, illuminance, élévation du soleil), il applique un style par défaut : courbe continue pour les variables lisses, diagramme en barres pour la pluie, nuage de points pour la direction du vent, etc.
+L’idée est d’obtenir une première vue d’ensemble de la [série temporelle](https://fr.wikipedia.org/wiki/S%C3%A9rie_temporelle) de chaque variable, sans prise de tête :
+
+- vérifier le cycle quotidien de la température et de l’élévation solaire ;
+- repérer les paliers ou dérives de capteurs (pression trop plate, humidité coincée, etc.) ;
+- confirmer que les unités, ranges et horodatages sont plausibles.
+
 ![](figures/temperature_overview.png)
 
 ![](figures/pressure_overview.png)
@@ -30,13 +35,18 @@ python "docs/03 - Premiers graphiques/scripts/plot_basic_variables.py"
 
 ## Vues calendrier
 
-Les vues calendrier permettent de visualiser, jour par jour, les cumuls ou moyennes quotidiennes sur la dernière année complète disponible.
-Les images générées sont stockées dans `figures/calendar/` et les CSV correspondants dans `data/calendar/`.
-
 ```shell
 python "docs/03 - Premiers graphiques/scripts/plot_calendar_overview.py"
 ```
 
+Le second script propose une vue complémentaire sous forme de _calendrier thermique_ (une [carte de chaleur](https://fr.wikipedia.org/wiki/Carte_de_chaleur) disposée en jours et mois).
+À partir du même dataset minuté, il calcule des moyennes quotidiennes (température, humidité, pression, illuminance, vent) ou des cumuls quotidiens (pluie), puis remplit une matrice « mois x jours » pour l’année la plus récente disponible.
+Ces vues servent surtout à :
+
+- repérer rapidement les saisons, épisodes pluvieux ou périodes de vent soutenu ;
+- détecter des trous dans la série (jours entièrement manquants) ;
+- avoir un aperçu global de l’année sans zoomer/dézoomer en permanence sur une longue série temporelle.
+
 ![](figures/calendar/calendar_temperature_2025.png)
 
 ![](figures/calendar/calendar_pressure_2025.png)
@@ -48,5 +58,3 @@ python "docs/03 - Premiers graphiques/scripts/plot_calendar_overview.py"
 ![](figures/calendar/calendar_illuminance_2025.png)
 
 ![](figures/calendar/calendar_wind_2025.png)
-
-Ces vues, bien que simples en principe, mettent déjà mieux en évidence les fluctuations au cours du temps.

docs/04 - Corrélations binaires/index.md

@@ -1,11 +1,22 @@
 # Corrélations binaires
 
+L’objectif de ce chapitre est d’explorer les relations entre variables deux à deux : d’abord visuellement (superposition de séries temporelles, comme ci-dessous, et [nuages de points](https://fr.wikipedia.org/wiki/Nuage_de_points), comme dans le chapitre suivant), puis numériquement via des coefficients de [corrélation](<https://fr.wikipedia.org/wiki/Corr%C3%A9lation_(statistiques)>).
+On reste volontairement dans un cadre simple : une variable « primaire » et une variable « associée », à la fois dans le temps et dans les matrices de corrélation.
+
 ## Superpositions simples
 
 ```shell
 python "docs/04 - Corrélations binaires/scripts/plot_pairwise_time_series.py"
 ```
 
+Ce script parcourt toutes les paires de variables disponibles et produit, pour chacune, un graphique superposant les deux séries sur le même axe temporel (ou sur deux axes verticaux si nécessaire).
+Les données sont ré-échantillonnées pour limiter le nombre de points et lisser légèrement le bruit, en utilisant les mêmes mécanismes que dans le chapitre 3.
+Ces superpositions servent surtout à repérer des co‑évolutions évidentes (par exemple humidité qui baisse quand la température monte) ou, au contraire, des paires qui semblent indépendantes à l’œil nu.
+
+### Température
+
+Toutes les figures de cette section ont pour variable « primaire » la température ; l’autre variable change d’un graphique à l’autre.
+
 ![](figures/pairwise_timeseries/timeseries_temperature_vs_humidity.png)
 
 ![](figures/pairwise_timeseries/timeseries_temperature_vs_pressure.png)
@@ -20,6 +31,10 @@ python "docs/04 - Corrélations binaires/scripts/plot_pairwise_time_series.py"
 
 ![](figures/pairwise_timeseries/timeseries_temperature_vs_sun_elevation.png)
 
+### Humidité relative
+
+Ici, on fixe l’humidité comme variable principale et on observe comment elle évolue en parallèle des autres variables.
+
 ![](figures/pairwise_timeseries/timeseries_humidity_vs_pressure.png)
 
 ![](figures/pairwise_timeseries/timeseries_humidity_vs_rain_rate.png)
@@ -32,6 +47,10 @@ python "docs/04 - Corrélations binaires/scripts/plot_pairwise_time_series.py"
 
 ![](figures/pairwise_timeseries/timeseries_humidity_vs_sun_elevation.png)
 
+### Pression
+
+Dans ces vues, on suit la pression atmosphérique et on la compare aux autres champs mesurés.
+
 ![](figures/pairwise_timeseries/timeseries_pressure_vs_rain_rate.png)
 
 ![](figures/pairwise_timeseries/timeseries_pressure_vs_illuminance.png)
@@ -42,92 +61,52 @@ python "docs/04 - Corrélations binaires/scripts/plot_pairwise_time_series.py"
 
 ![](figures/pairwise_timeseries/timeseries_pressure_vs_sun_elevation.png)
 
+### Pluviométrie
+
+On regarde ici comment les épisodes de pluie (taux de précipitation) se positionnent par rapport au vent et à la hauteur du soleil.
+
 ![](figures/pairwise_timeseries/timeseries_rain_rate_vs_wind_speed.png)
 
 ![](figures/pairwise_timeseries/timeseries_rain_rate_vs_wind_direction.png)
 
 ![](figures/pairwise_timeseries/timeseries_rain_rate_vs_sun_elevation.png)
 
+### Luminance
+
+Ces superpositions éclairent les liens entre lumière, vent et position du soleil.
+
 ![](figures/pairwise_timeseries/timeseries_illuminance_vs_wind_speed.png)
 
 ![](figures/pairwise_timeseries/timeseries_illuminance_vs_wind_direction.png)
 
 ![](figures/pairwise_timeseries/timeseries_illuminance_vs_sun_elevation.png)
 
+### Vent (vitesse / direction)
+
+Enfin, on se concentre sur le vent : d’abord sa vitesse en lien avec l’élévation solaire, puis la direction comparée à cette même référence.
+
 ![](figures/pairwise_timeseries/timeseries_wind_speed_vs_wind_direction.png)
 
 ![](figures/pairwise_timeseries/timeseries_wind_speed_vs_sun_elevation.png)
 
 ![](figures/pairwise_timeseries/timeseries_wind_direction_vs_sun_elevation.png)
 
-## Nuages de points
+## Matrices de corrélation (instantané, signé)
+
+Le calcul des coefficients de Pearson et de Spearman peut nous donner une indication numérique de la force et du signe des corrélations entre les différentes variables.
+On passe ainsi du visuel (superpositions, nuages de points) à un résumé compact des co‑variations, même si cela ne capture que des dépendances linéaires ou monotones simples.
+On utilise ici :
+
+- le coefficient de corrélation linéaire de Pearson (voir [corrélation linéaire](https://fr.wikipedia.org/wiki/Corr%C3%A9lation_lin%C3%A9aire)) pour mesurer à quel point deux variables varient ensemble de manière approximativement linéaire ;
+- le coefficient de Spearman (voir [corrélation de Spearman](https://fr.wikipedia.org/wiki/Corr%C3%A9lation_de_Spearman)) pour capturer des relations monotones (croissantes ou décroissantes), même si elles ne sont pas parfaitement linéaires.
 
 ```shell
-python "docs/04 - Corrélations binaires/scripts/plot_all_pairwise_scatter.py"
-```
-
-![](figures/pairwise_scatter/scatter_humidity_vs_illuminance.png)
-
-![](figures/pairwise_scatter/scatter_humidity_vs_pressure.png)
-
-![](figures/pairwise_scatter/scatter_humidity_vs_rain_rate.png)
-
-![](figures/pairwise_scatter/scatter_humidity_vs_sun_elevation.png)
-
-![](figures/pairwise_scatter/scatter_humidity_vs_wind_direction.png)
-
-![](figures/pairwise_scatter/scatter_humidity_vs_wind_speed.png)
-
-![](figures/pairwise_scatter/scatter_illuminance_vs_sun_elevation.png)
-
-![](figures/pairwise_scatter/scatter_illuminance_vs_wind_direction.png)
-
-![](figures/pairwise_scatter/scatter_illuminance_vs_wind_speed.png)
-
-![](figures/pairwise_scatter/scatter_pressure_vs_illuminance.png)
-
-![](figures/pairwise_scatter/scatter_pressure_vs_rain_rate.png)
-
-![](figures/pairwise_scatter/scatter_pressure_vs_sun_elevation.png)
-
-![](figures/pairwise_scatter/scatter_pressure_vs_wind_direction.png)
-
-![](figures/pairwise_scatter/scatter_pressure_vs_wind_speed.png)
-
-![](figures/pairwise_scatter/scatter_rain_rate_vs_illuminance.png)
-
-![](figures/pairwise_scatter/scatter_rain_rate_vs_sun_elevation.png)
-
-![](figures/pairwise_scatter/scatter_rain_rate_vs_wind_direction.png)
-
-![](figures/pairwise_scatter/scatter_rain_rate_vs_wind_speed.png)
-
-![](figures/pairwise_scatter/scatter_temperature_vs_humidity.png)
-
-![](figures/pairwise_scatter/scatter_temperature_vs_illuminance.png)
-
-![](figures/pairwise_scatter/scatter_temperature_vs_pressure.png)
-
-![](figures/pairwise_scatter/scatter_temperature_vs_rain_rate.png)
-
-![](figures/pairwise_scatter/scatter_temperature_vs_sun_elevation.png)
-
-![](figures/pairwise_scatter/scatter_temperature_vs_wind_direction.png)
-
-![](figures/pairwise_scatter/scatter_temperature_vs_wind_speed.png)
-
-![](figures/pairwise_scatter/scatter_wind_direction_vs_sun_elevation.png)
-
-![](figures/pairwise_scatter/scatter_wind_speed_vs_sun_elevation.png)
-
-![](figures/pairwise_scatter/scatter_wind_speed_vs_wind_direction.png)
-
-## Matrices de corrélation
-
-```shell
-python "docs/04 - Corrélations binaires/scripts/plot_correlation_heatmap.py"
+python "docs/04 - Corrélations binaires/scripts/plot_correlation_heatmap.py" --transform=identity --upper-only
 ```
 
 ![](figures/correlation_heatmap.png)
 
 ![](figures/correlation_heatmap_spearman.png)
+
+Le signe et l'intensité des coefficients montrent à quel point deux variables bougent ensemble au même instant (co‑mouvement linéaire pour Pearson, monotone pour Spearman).
+Cette matrice sert donc surtout de carte globale : repérer rapidement les couples très corrélés ou indiquer un lien physique évident, mettre en alerte des variables à forte corrélation qui pourraient masquer d'autres effets (saisonnalité, cycle jour/nuit), et choisir quelles paires méritent qu'on teste des décalages temporels ou des relations non linéaires dans la suite.

docs/04 - Corrélations binaires/scripts/plot_all_pairwise_scatter.py

@@ -1,52 +0,0 @@
-# scripts/plot_all_pairwise_scatter.py
-from __future__ import annotations
-
-from pathlib import Path
-import sys
-
-
-PROJECT_ROOT = Path(__file__).resolve().parents[3]
-if str(PROJECT_ROOT) not in sys.path:
-    sys.path.insert(0, str(PROJECT_ROOT))
-
-from meteo.dataset import load_raw_csv
-from meteo.variables import iter_variable_pairs
-from meteo.plots import plot_scatter_pair
-
-
-CSV_PATH = Path("data/weather_minutely.csv")
-DOC_DIR = Path(__file__).resolve().parent.parent
-OUTPUT_DIR = DOC_DIR / "figures" / "pairwise_scatter"
-
-
-def main() -> None:
-    if not CSV_PATH.exists():
-        print(f"⚠ Fichier introuvable : {CSV_PATH}")
-        return
-
-    df = load_raw_csv(CSV_PATH)
-    print(f"Dataset minuté chargé : {CSV_PATH}")
-    print(f"  Lignes   : {len(df)}")
-    print(f"  Colonnes : {list(df.columns)}")
-
-    pairs = iter_variable_pairs()
-    print(f"Nombre de paires de variables : {len(pairs)}")
-
-    for var_x, var_y in pairs:
-        filename = f"scatter_{var_x.key}_vs_{var_y.key}.png"
-        output_path = OUTPUT_DIR / filename
-
-        print(f"→ Trace {var_y.key} en fonction de {var_x.key} → {output_path}")
-        plot_scatter_pair(
-            df=df,
-            var_x=var_x,
-            var_y=var_y,
-            output_path=output_path,
-            sample_step=10,  # un point sur 10 : ≈ 32k points au lieu de 320k
-        )
-
-    print("✔ Tous les graphiques de nuages de points ont été générés.")
-
-
-if __name__ == "__main__":
-    main()

docs/04 - Corrélations binaires/scripts/plot_correlation_heatmap.py

@@ -4,6 +4,9 @@ from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path
 import sys
+import argparse
+import pandas as pd
+import numpy as np
 
 
 PROJECT_ROOT = Path(__file__).resolve().parents[3]
@@ -20,7 +23,6 @@ CSV_PATH = Path("data/weather_minutely.csv")
 DOC_DIR = Path(__file__).resolve().parent.parent
 
 CORRELATION_METHODS: tuple[str, ...] = ("pearson", "spearman")
-CORRELATION_TRANSFORM = "square"
 
 
 @dataclass(frozen=True)
@@ -36,13 +38,19 @@ class HeatmapConfig:
 HEATMAP_CONFIGS: dict[str, HeatmapConfig] = {
     "pearson": HeatmapConfig(
         filename="correlation_heatmap.png",
-        title="Corrélations R² (coef. de Pearson)",
-        colorbar_label="Coefficient de corrélation R²",
+        title="Corrélations (coef. de Pearson)",
+        colorbar_label="Coefficient de corrélation",
+        cmap="viridis",
+        vmin=0.0,
+        vmax=1.0,
     ),
     "spearman": HeatmapConfig(
         filename="correlation_heatmap_spearman.png",
-        title="Corrélations R² (coef. de Spearman)",
-        colorbar_label="Coefficient de corrélation R²",
+        title="Corrélations (coef. de Spearman)",
+        colorbar_label="Coefficient de corrélation",
+        cmap="viridis",
+        vmin=0.0,
+        vmax=1.0,
     ),
 }
 
@@ -63,36 +71,92 @@ def _get_heatmap_config(method: str) -> HeatmapConfig:
 
 
 def main() -> None:
+    parser = argparse.ArgumentParser(description="Trace des matrices de corrélation instantanées (signées, absolues ou r²).")
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=DOC_DIR / "figures",
+        help="Dossier de sortie pour les heatmaps.",
+    )
+    parser.add_argument(
+        "--transform",
+        choices=["identity", "absolute", "square"],
+        default="absolute",
+        help="Transformation de la matrice (signée, |r| ou r²). Par défaut : |r|.",
+    )
+    parser.add_argument(
+        "--upper-only",
+        action="store_true",
+        help="Masque la partie inférieure de la matrice pour alléger la lecture.",
+    )
+    args = parser.parse_args()
+
     if not CSV_PATH.exists():
         print(f"⚠ Fichier introuvable : {CSV_PATH}")
         print("   Assurez-vous d'avoir généré le dataset minuté.")
         return
 
     df = load_raw_csv(CSV_PATH)
+    df = df[[v.column for v in VARIABLES]]
     print(f"Dataset minuté chargé : {CSV_PATH}")
     print(f"  Lignes   : {len(df)}")
     print(f"  Colonnes : {list(df.columns)}")
     print()
 
+    transform = args.transform
     matrices = compute_correlation_matrices_for_methods(
         df=df,
         variables=VARIABLES,
         methods=CORRELATION_METHODS,
-        transform=CORRELATION_TRANSFORM,
+        transform=transform,
     )
 
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+
     for method, corr in matrices.items():
-        print(f"Matrice de corrélation (méthode={method}, transform={CORRELATION_TRANSFORM}) :")
+        if args.upper_only:
+            mask = np.tril(np.ones_like(corr, dtype=bool), k=-1)
+            corr = corr.mask(mask)
+
+        print(f"Matrice de corrélation (méthode={method}, transform={transform}) :")
         print(corr)
         print()
 
         config = _get_heatmap_config(method)
+        filename = config.filename
+        title = config.title
+        if transform == "absolute":
+            title = f"{title} (|r|)"
+            stem, suffix = filename.rsplit(".", 1)
+            filename = f"{stem}_abs.{suffix}"
+        elif transform == "square":
+            title = f"{title} (r²)"
+            stem, suffix = filename.rsplit(".", 1)
+            filename = f"{stem}_r2.{suffix}"
+            config = HeatmapConfig(
+                filename=filename,
+                title=title,
+                colorbar_label="Coefficient de corrélation r²",
+                cmap="viridis",
+                vmin=0.0,
+                vmax=1.0,
+            )
+        elif transform == "identity":
+            config = HeatmapConfig(
+                filename=filename,
+                title=title,
+                colorbar_label="Coefficient de corrélation r",
+                cmap="coolwarm",
+                vmin=-1.0,
+                vmax=1.0,
+            )
+
         output_path = plot_correlation_heatmap(
             corr=corr,
             variables=VARIABLES,
-            output_path=DOC_DIR / "figures" / config.filename,
+            output_path=args.output_dir / filename,
             annotate=True,
-            title=config.title,
+            title=title,
             cmap=config.cmap,
             vmin=config.vmin,
             vmax=config.vmax,