Reformulations

2025-11-26 17:22:57 +01:00
parent 8b26c0bf17
commit f4bdbe2c7f
13 changed files with 460 additions and 171 deletions
--- a/données/index.md
+++ b/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.
-Mon fichier complet contient plus d'un million d'enregistrements et pèse 70Mo.
+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.