Files
Support-Agent/.claude/skills/lire-les-donnees/SKILL.md
T
maximeandClaude Opus 5.5 7fb176cf0a Events-learner: the analyst writes its own tools, a tool-builder brings them into agent-tools; /aiguiser retired (D-097)
- inventaire.py: what each source contains on the window (filled or empty columns, metric names, images), names and counts only
- analyser-lot: step 0 on the data, own scripts in <lot>/outils/, section 3 "Outils"
- tool-builder (the optimiser, rewritten): after the analyst, optimises or adds reading tools, never removes; no control yet
- /aiguiser skill, reader, corrector and voir.py removed; its sessions and spec stay as history
- docs: D-097, specs, CLAUDE.md, run.md, README, plan point 56; the shared files also carry another session's pending edits (D-096 entry, plan points 57 to 67)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 17:10:17 +01:00

21 KiB

name, description
name description
lire-les-donnees Lire un dossier de données de déplacement d'une station AIMsight, courbes et images, avec les outils de lecture — ce qu'ils rendent et comment s'en servir. Suivi par l'analyste (analyser-lot) et l'agent de diagnostic ; amélioré par le tool-builder de /events-learner, d'après les outils dont l'analyste s'est servi (D-097).

Lire les données

Une caméra suit des cibles (réflecteurs) fixées sur un ouvrage ; son propre mouvement est compensé grâce à des cibles de référence, supposées fixes. Ce mouvement, la pose de la caméra (pan, tilt, rotation en degrés, scale, sigma0 du recalage, dans camera/), se lit avant les capteurs : il explique une grande part de ce qui bouge sur les courbes (D-073). Ce skill dit comment lire les données d'une station : ce que montrent les courbes et les images, moment par moment. Il ne dit pas ce qu'elles veulent dire : catégorie, event connu, hypothèse et verdict sont l'affaire de celui qui t'appelle.

À lire d'abord

  • docs/domaine/colonnes-des-deplacements.md : formats des exports et sens des colonnes (en premier) ;
  • docs/domaine/pieges-des-donnees.md.

Les outils

Lance-les depuis la racine du dépôt. Ils rendent des valeurs, jamais des verdicts : c'est toi qui juges.

Commande Ce qu'elle rend
python3 agent-tools/inventaire.py <dossier> [--debut T] [--fin T] [--fichiers] Fichiers par type (au-delà de 5 par type : le nombre, le premier et le dernier ; --fichiers pour la liste complète, à n'utiliser que pour chercher un fichier précis), ce que contient chaque source sur la fenêtre (colonnes de l'export, de la pose et de quality/, avec le nombre de lignes qui ont une valeur, « vide » sinon ; noms des métriques système de metrics/ ; images et images différentielles ; des noms et des comptes, jamais de valeurs), images (heures couvertes), poses de la caméra (nombre, période, instants de mesure sans recalage), période, cadence, mesures manquantes, capteurs (référence ou cible, seuil d'erreur, mesures rejetées) : ces comptes portent sur toute la période. Avec --debut/--fin (sur un lot : ceux du lot), une section de plus pour la fenêtre : les pas absents datés (pour tous les capteurs, ou lesquels manquent), par capteur, les mesures rejetées datées (suites de pas consécutifs), puis le nombre de références retenues par la compensation (inlier = 1) à chaque instant et les suites datées où des références ne le sont pas, lesquelles et pourquoi (r rejetée, 0 écartée par la compensation, vide). Une mesure est rejetée quand son error_value dépasse le seuil du capteur, références comprises
python3 agent-tools/resume.py <dossier> [--colonne C] [--stat median|min|max] [--pas 1h] [--niveau periode|fenetre] [--capteurs A,B] [--debut T] [--fin T] Niveau habituel de chaque capteur (médiane, MAD, min, max) sur toute la période, ou sur la fenêtre --debut/--fin avec --niveau fenetre (pour un lot : un changement de niveau dans le lot ne se compare pas à des semaines d'autres mesures), puis un tableau par pas de temps. Colonnes : error_value, corr_x, corr_y, relative_x, relative_y, x, y, sigma0, reproj_err
.venv/bin/python agent-tools/graphique.py <dossier> [--capteurs A,B] [--colonnes C1,C2] [--debut T] [--fin T] [--zone T1/T2 ...] [--sortie D] Un PNG des séries ; chaque --zone est grisée ; il imprime son chemin. Regarde-le avec Read : tu lis mieux un graphique qu'un tableau
.venv/bin/python agent-tools/ensemble.py <dossier> [--colonnes x,y,sigma0] [--colonne error_value] [--pas 15min] [--k 5] [--min 5] [--residus corr_x,corr_y,error_value] [--hors T1/T2] [--autres] [--rigide BASE [--sans A,B]] [--capteurs A,B] [--debut T] [--fin T] [--sortie D] Tous les capteurs ensemble, chacun face à sa médiane et sa MAD sur la fenêtre. Deux PNG : commun (médiane entre capteurs de x, y, sigma0 : avec la dispersion entre capteurs en bande grise ; sur les panneaux x, y, en plus, chaque référence globale à part (un trait chacune) et la médiane des cibles seules (trait noir) ; et, à chaque pas, le nombre de capteurs dont --colonne dépasse sa médiane de plus de --k MAD ; en tête, si le dossier a camera/, la pose de la caméra, valeurs brutes, un point par recalage, le trait coupé aux instants de mesure sans recalage) et multiples (un petit graphique par capteur, une échelle chacun : un palier d'un seul capteur s'y voit). Imprime aussi la table de la médiane commune (une ligne par pas de --pas : l'heure et l'écart à la médiane de la fenêtre de x, y, sigma0, puis x_cibles, y_cibles (médiane des cibles seules), puis la pose brute de la caméra, colonnes cam_pan, cam_tilt, cam_rotation, cam_scale, cam_sigma0, vides sans recalage) avec le minimum et le maximum de chaque colonne et leur instant, puis ceux de x, y de chaque référence globale (marqués (rejetée) quand la mesure l'est, avec le nombre de mesures rejetées de la référence), puis les instants de mesure sans pose (suites datées), puis les instants où au moins --min capteurs dépassent ensemble, avec leurs noms. Trois PNG de plus, residus-corr_x, residus-corr_y, residus-error_value (--residus) : un petit graphique par capteur de la colonne moins le niveau propre du capteur (sa médiane sur la fenêtre ; avec --hors T1/T2, celle du reste de la fenêtre, hors du moment lu), une échelle chacun, zéro en pointillé : un écart de quelques centièmes sur corr, caché dans les bandes parallèles de graphique.py, s'y voit ; imprime pour chaque capteur le niveau, le bruit propre (médiane des écarts entre deux mesures) et l'écart min/max par pas avec leur instant, en unités et en bruits. Avec --autres, des PNG residus-…-autres de plus : chaque capteur moins sa propre médiane et moins la médiane des autres capteurs au même instant (ce que tous partagent, le reste de la compensation d'un mouvement commun, s'annule ; ce qui est propre reste), et, par capteur, la pente et la corrélation r de ce résidu sur la médiane commune de x, y, sigma0 : un creux qui reste après --autres n'est pas un reste partagé par tous ; une pente élevée avec r proche de ±1 sur y commun dit qu'il est proportionnel au mouvement commun (gain propre au capteur), sans r ni pente il est indépendant du mouvement. Avec --rigide BASE, un PNG rigide de plus : à chaque mesure, le mouvement d'ensemble des cibles depuis l'instant BASE (translation, rotation, échelle, estimé par médianes : une cible qui saute seule ne le tire pas ; --sans A,B en retire des cibles), et, pour chaque capteur, le résidu dx, dy (position brute moins sa position à BASE transportée par ce mouvement, en px) ; panneaux : dx, dy de chaque référence globale face à la médiane et au 10e-90e centile des cibles, `
python3 agent-tools/plages.py <dossier> [--colonnes error_value,corr_x,corr_y] [--k 5] [--fusion 1h] [--min-mesures 1] [--hors T1/T2] [--capteurs A,B] [--debut T] [--fin T] Par colonne et par capteur, aux mesures (pas natif, jamais moyennées) : niveau (médiane de la fenêtre), bruit propre, plus grand saut d'une mesure à la suivante (valeur, en bruits, les deux instants) ; puis les plages où le capteur s'écarte de son niveau de plus de --k bruits : début, fin, nombre de mesures, extrême (signé, en unités et en bruits) et son instant ; deux plages du même sens à moins de --fusion n'en font qu'une, les mesures rejetées ne coupent pas une plage ; colonne rejetées : combien des mesures de la plage le sont (et extrême rejetée), (rejetée : …) après un plus grand saut dont un bout l'est. Sert à dater le début et la fin d'un moment d'un capteur sans relancer dix tableaux. Quand un épisode long fausse la médiane de la fenêtre (le capteur y passe la moitié du lot), --hors T1/T2 calcule niveau et bruit hors de l'épisode ; une plage qui touche le bord de la fenêtre est datée au bord. --min-mesures N n'imprime que les plages d'au moins N mesures (et dit combien sur le total) : sur un lot de plusieurs jours, les plages d'un pas se comptent par centaines et noient les paliers longs ; lis d'abord avec --min-mesures 6, puis sans
.venv/bin/python agent-tools/jours.py <dossier> [--colonnes corr_x,corr_y,error_value] [--nuit 20-3] [--k 5] [--jours 2] [--pas 15min] [--capteurs A,B] [--debut T] [--fin T] [--sortie D] Ce qui revient d'un jour à l'autre, sur les mesures acceptées seulement. 1. Niveau de chaque nuit (heures --nuit H1-H2 UTC, à cheval sur minuit, datée du jour où elle commence), par capteur et par colonne : médiane, MAD, nombre de mesures, et le bruit propre ; puis, d'une nuit à la suivante, la marche (différence des médianes, en unités et en bruits) et où elle se place (« entre A et B » : là où la suite des mesures de nuit des deux nuits se coupe le mieux entre les deux niveaux ; B au début de la nuit suivante : la coupure tombe de jour, entre les deux nuits). Une marche de quelques bruits, une dérive d'une nuit à l'autre, et deux colonnes qui marchent au même instant s'y lisent, même quand le capteur a plusieurs niveaux dans le lot. 2. Jours superposés : PNG parheure-, un petit graphique par capteur, en abscisse l'heure du jour, une courbe par jour, chaque mesure moins le niveau de la dernière nuit commencée (nuit grisée, cadre du 1er au 99e centile, le titre dit combien de mesures sortent du cadre) ; table : par créneau de --pas de l'heure du jour, les capteurs dont l'écart dépasse --k bruits, du même côté, au moins --jours jours, avec le nombre de jours et la médiane de ces écarts. Ce qui revient chaque jour à la même heure, sur un capteur ou plusieurs, s'y groupe, même quand cela ne dure qu'une à trois mesures. Le choix de --nuit : des heures où le cycle du jour (error_value, pose de la caméra) est retombé. Regarde les PNG avec Read
.venv/bin/python agent-tools/vignettes.py <dossier> --capteurs A,B --heures T1,T2 [--rayon 100] [--contraste [MIN,MAX]] [--fixe] [--sortie D] Une planche de vignettes à pleine résolution : une ligne par capteur, une colonne par heure, centrées sur la position brute (x, y) du capteur à chaque heure (le centre du cadre est écrit sous chaque vignette : quand x, y sautent, le cadre se déplace d'autant, et une tache qui entre dans le cadre semble apparaître) ; --fixe garde pour chaque capteur le cadre de la première heure et marque d'une croix rouge les x, y de chaque heure ; pixels non retouchés, l'éclat se compare d'une vignette à l'autre ; imprime pour chaque vignette le fond (médiane), le 99e centile et le pic (niveaux de gris 0 à 255) ; sans image à l'heure demandée, prend la plus proche et imprime l'écart (l'heure réelle est dans le titre). Une tache faible ou déformée est invisible telle quelle : --contraste MIN,MAX met toutes les vignettes en gris avec le même étirement (sans valeur : du 1er centile au maximum de la planche, écrasé par un pixel saturé ; choisis alors MIN,MAX d'après le fond et le pic imprimés, ex. 10,40), --rayon 30 à 50 grossit ; compare la forme et le pic avant, pendant et après un épisode, à la même heure de la journée. Regarde-la avec Read : une image entière lue par Read est réduite, un petit réflecteur y devient illisible
ls <dossier>/images/ | grep <AAAAMMJJ>T<HHMM>Z, puis Read sur le fichier trouvé (Read ne prend pas de motif) L'image entière de la caméra à cette heure (UTC), pour la scène (occultation, éclairage, météo)

--sortie <dossier> : là où celui qui t'appelle range tes figures ; il te le donne.

Conventions

  • Instants : 2026-01-01T00:00Z ; une heure sans fuseau est lue en UTC ; --fin inclut la minute indiquée. Sur un lot, --debut et --fin du lot.
  • Bash ne sert qu'à lancer ces outils, ls, grep et date, une commande par appel, sans boucle for (un tube vers grep est permis) : les permissions sont accordées commande par commande. Si le répertoire courant n'est pas la racine du dépôt, cd <racine> && <commande> compte pour une commande. N'écris aucun autre script. Celui qui t'appelle peut ajouter des commandes à cette liste.
  • Chaque PNG se regarde avec Read : un PNG que tu n'as pas regardé n'a rien montré.
  • Une mesure rejetée (error_value au-dessus du seuil) n'est pas une mesure : la station vide les corr d'une cible rejetée, mais laisse ceux d'une référence rejetée, souvent absurdes ; les outils les vident (corr, plages, résidus, sauts ne portent que sur les mesures acceptées). Ses x, y restent : avant de citer un saut de x, y, regarde s'il est marqué (rejetée) ; une mesure rejetée ne se cite pas comme un mouvement.

La méthode

  1. Inventaire : ce qui est disponible, ce qui manque (fichiers, ce que contient chaque source, images, poses de la caméra, période, cadence, capteurs). Une colonne remplie que les outils ne montrent pas (par exemple les six colonnes de qualité d'image, peak à snr, sur certaines stations) ou une source qu'aucun outil ne lit (metrics/, images_diff/) reste une donnée : sache qu'elle existe. Sur un lot, relance-le avec --debut/--fin du lot : les pas absents et les rejets du lot, datés ; ceux de la période entière ne disent rien du lot. Lis les rejets des références autant que ceux des cibles : un capteur rejeté aux mêmes heures chaque jour fait un moment à lui seul (dis sa part de mesures rejetées et ses heures, jour par jour) ; quand c'est une référence, dis avec combien de références la compensation tourne alors (la liste des références retenues). Quand plusieurs cibles sautent ensemble d'un pas, ou que la compensation tombe (pas de pose), regarde d'abord dans cette liste quelles références ont été perdues à cet instant.
  2. Large d'abord : ensemble.py sur le lot, d'abord ; la pose de la caméra en premier (panneaux du haut, colonnes cam_ de la table) : quand la caméra tourne (pan, tilt, rotation), change d'échelle (scale), quand son recalage se dégrade (sigma0) et quand elle n'est pas recalée (trait coupé, instants sans pose), datés au pas natif ; chaque moment des capteurs se lit ensuite face à elle : pendant un mouvement ou un trou de recalage, ou caméra immobile. La pose est calculée à partir des références globales : un changement de pose (ou une montée de sigma0) ne se lit comme un mouvement de la caméra que si les cibles bougent aussi dans l'image ; regarde, sur les panneaux x, y, les traits des références face au trait noir des cibles seules (et la colonne x_cibles, y_cibles de la table). Si seules des références bougent dans l'image et que les cibles restent immobiles, ce sont ces références qui ont bougé : la pose et les corr de toutes les cibles en sont faussés, sans mouvement brut des cibles ; dis quelles références et de combien. Si tout bouge ensemble, références et cibles, c'est la caméra ou la scène ; regarde alors si les corr reviennent. Dès que la pose tourne ou change d'échelle, l'écart à la médiane ne dit plus qui bouge seul (chaque capteur s'en écarte selon sa place dans l'image) : avant d'écrire « tout bouge ensemble », relance avec --rigide BASE, BASE un instant calme avant le premier mouvement, et lis le PNG rigide et sa table : une référence dont le résidu reste loin du 10e-90e centile des cibles, ou un reproj_err des références qui ne revient pas, veut dire que la compensation reste faussée par ces références et que les paliers de corr en viennent en partie ; dis lesquelles, de combien, jusqu'à quand ; un |résidu| des cibles qui monte dit qu'elles ne bougent pas comme un bloc. Puis la médiane de x, y (position brute, références comprises), les références une à une, les cibles seules et sigma0 disent ce qui bouge dans l'image, avant de lire corr ; lis la table imprimée (heure, valeur) pour dater le début, la fin et le retour du mouvement et pour voir un niveau qui ne revient pas, et ne les devine pas sur l'axe du PNG : un creux de corr qui suit un mouvement de la médiane brute est le reste de la compensation, pas un mouvement propre des capteurs touchés ; les petits multiples d'error_value montrent un palier durable d'un capteur, le compte les instants où beaucoup de capteurs montent ensemble. Sur tout lot, sans attendre un soupçon, regarde les PNG residus (corr_x, corr_y, error_value) : chaque capteur face à son propre niveau, c'est là que se voient un capteur seul qui monte ou descend, un corr qui dérive de quelques centièmes, un palier propre à un capteur sous un mouvement commun ; la table dit de combien (en bruits) et quand. Pour séparer, sur une cible dont corr baisse sous un mouvement commun fort, un reste de compensation d'un mouvement propre, relance avec --autres (le reste partagé disparaît, la pente sur x, y commun dit s'il est proportionnel). Sur un lot de plus de deux jours, lance ensuite jours.py (avant de lire les pas isolés de plages.py) : ce qui revient chaque jour à la même heure se lit d'abord sur ses PNG parheure et sa table par créneau, et fait un moment par heure du jour (dis quels capteurs, combien de jours sur combien, l'ampleur, ce que fait la pose de la caméra à cette heure-là), pas un moment par jour ni rien du tout parce que chaque pas est court ; puis lis sa table des niveaux de nuit, pour tout capteur qui a déjà fait un palier ou dont --hors ne suffit pas (plusieurs niveaux dans le lot) : chaque marche d'une nuit à l'autre se date par son « entre A et B », et une marche d'error_value et une de corr au même instant se relient ; une dérive lente se lit d'une nuit à l'autre. Puis graphique.py sur tous les capteurs, error_value puis corr_x, corr_y (ou relative_x, relative_y), références et cibles ; resume.py sur ces colonnes avec un pas large (6h ou 1d).
  3. Puis zoome : resume.py à 15min (--stat max pour le pic réel d'un capteur), et graphique.py sur les fenêtres et les capteurs qui bougent.
  4. Chaque capteur face à son propre niveau habituel (sa médiane et sa MAD), jamais à un seuil absolu ; sur un lot, le niveau se calcule sur le lot (--niveau fenetre, ensemble.py), pas sur la période entière.
  5. Chaque moment retenu se date et se mesure au pas natif de 15 min : début, fin et maximum lus sur la table à 15 min (ensemble.py par défaut, resume.py --pas 15min), jamais sur un tableau à l'heure ; lis aussi ensemble.py --min 1 pour les capteurs seuls, et plages.py sur le lot (d'abord avec --min-mesures 6) pour avoir, par capteur, début, fin, extrême et plus grand saut au pas natif (relance-le avec --hors autour d'un épisode long pour dater son retour au niveau, ne conclus pas « ne revient pas » sans l'avoir lu), et les tables de x, y sur les fenêtres où ils s'agitent.
  6. Les images : vignettes (avec --contraste pour une cible faible) espacées, une toutes les 2 à 3 h, plus serrées là où les courbes bougent, toujours avec un capteur témoin non touché, à une heure avant, pendant et après (à la même heure de la journée si possible) ; quand x, y d'un capteur sautent entre deux vignettes (centre du cadre écrit sous chacune), relance avec --fixe avant de dire qu'une tache apparaît ou disparaît ; l'image entière pour la scène (occultation, éclairage, météo).

Ce que la lecture rend

Une ligne par moment. Un moment : un capteur ou un groupe de capteurs qui sort de son niveau habituel pendant une fenêtre que tu peux dater.

Début Fin Capteurs Colonnes Ce que je vois Images
  • Capteurs : références ou cibles, combien, lesquels.
  • Ce que je vois : la forme (pic d'un pas, palier, montée lente, agitation), l'ampleur face au niveau habituel (en MAD ou en fois la médiane), le retour à la normale ou non, ce que font les autres capteurs, ce que fait la caméra au même moment (pose qui bouge, de combien, ou immobile ; recalage absent ; « pas de camera/ » si le dossier n'en a pas).
  • Images : ce que montrent les vignettes et l'image entière à ce moment, ou « pas d'image ».

Heures en UTC.