"""Journal du matin : des épisodes des détecteurs aux événements, un par famille. Un détecteur par famille des étiquettes (labeling/familles.md) : visibility.py, obstruction.py, target_issue.py, thermal_displacement.py, no_data.py, displacement.py. La catégorie d'un événement est sa famille, le champ kind de ses épisodes ; leur label en dit la sorte (Poor visibility, Heat shimmer, Brief obstruction, Slow drift…). Règles : - un saut revenu à la normale (SAUT) qui chevauche un épisode de HOTES (perte de visibilité, passage, turbulence, et en dernier l'effet thermique, s'il touche plusieurs cibles) y est absorbé : il en prend la cause et la famille ; sinon il reste Displacement, sans cause établie, à vérifier sur les images (familles.md, « Un saut puis le retour ») ; un passage (Brief obstruction, un seul instant) n'absorbe que les sauts qui commencent à son instant, pas ceux de plusieurs jours qu'il croise (/detector-learner Displacement, modification 1, S5) ; - une dérive lente ou un saut revenu dont toutes les cibles sont dans un épisode Target issue qui le chevauche y est absorbé (la courbe d'une cible à problème est à ignorer, familles.md) ; - un décalage qui dure, ou trop récent pour savoir (DECALAGES), n'est jamais absorbé ; - une turbulence qui chevauche un décalage n'est pas gardée : un vrai mouvement agite aussi les courbes ; - deux événements de même sorte à moins de MERGE n'en font qu'un ; deux Obstruction (Target obscured, Brief obstruction), seulement s'ils partagent un capteur (/detector-learner Obstruction, modification 1 : S1, des cibles différentes enchaînées en un événement de plusieurs jours ; S3, des passages de quelques minutes en une heure entière) ; un passage n'absorbe que les sauts revenus dans MERGE après son instant (S3 : pas le saut de 30 h d'une autre cible). Chaque événement reçoit sa phrase, en anglais (le site) : ce qui s'est passé et quoi en faire, comme le dit la colonne « Pour le client » de familles.md ; la cause n'est dite que si la sorte l'établit, sinon les images la montrent. Pas de fonction detect : le chargeur ne prend pas ce fichier pour un détecteur. Usage : python3 detectors/categories.py (une ligne par événement : famille, sorte, capteurs) ... [--du AAAA-MM-JJ] [--au AAAA-MM-JJ] [--tranche 3] [--historique N] (tri en lot : chaque tranche de N jours classée seule, avec les jours d'historique d'avant s'ils existent ; seuls les événements qui touchent la tranche sont montrés ; « rien » pour une tranche calme) """ import functools import importlib.util import inspect import os import sys from datetime import datetime, timedelta, timezone from pathlib import Path sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "agent-tools")) from donnees import charger, charger_camera, charger_metriques, charger_temperature, iso # noqa: E402 # Ce qu'un détecteur peut lire de la station en plus des mesures, s'il le déclare dans detect (D-124, D-134) : # temperature [(t, °C)], médiane horaire des composants ; camera [pose] (pan, tilt, rotation, scale, sigma0) ; # metriques {nom: [(t, valeur)]}, toutes les métriques numériques (sensor_CPU_deg_c, sensor_GPU_deg_c, BusVoltage…). CONTEXTE = {"temperature": charger_temperature, "camera": charger_camera, "metriques": charger_metriques} @functools.lru_cache(maxsize=None) def _contexte(dossier, cle): return CONTEXTE[cle](dossier) # Les familles de labeling/familles.md, dans l'ordre des lignes de la frise ; ignore : zone grisée (None : comme le # disent ses épisodes : une perte de visibilité totale, une turbulence forte) ; process : bouton Images, rien, ou Images # et lien vers Diagnosis. CATEGORIES = { "Visibility": {"ignore": None, "process": "images"}, "Obstruction": {"ignore": True, "process": "images"}, "Target issue": {"ignore": True, "process": "images"}, "Thermal displacement": {"ignore": False, "process": "aucun"}, "No data": {"ignore": False, "process": "aucun"}, "Displacement": {"ignore": False, "process": "verifier"}, } SAUT = "Sudden jump, back to normal" # un saut revenu : sa cause, s'il chevauche un hôte ; sinon Displacement DECALAGES = {"Lasting shift", "Jump, not back yet", "Large shift"} # à vérifier : jamais absorbés HOTES = {"Poor visibility", "Brief obstruction", "Heat shimmer", "Thermal expansion", "Thermal contraction", "Camera thermal expansion", "Camera thermal contraction", "Camera thermal movement"} # disent la cause d'un saut revenu qui les chevauche MERGE = timedelta(hours=1) # même sorte à moins d'une heure : un seul événement (règle validée, 2026-10-24) def detecteurs(): """Modules de detectors/*.py qui ont detect ; un fichier qui ne se charge pas est sauté avec un message.""" mods = [] for path in sorted(Path(__file__).resolve().parent.glob("*.py")): if path == Path(__file__).resolve(): continue try: spec = importlib.util.spec_from_file_location(f"journal_{path.stem}", path) mod = importlib.util.module_from_spec(spec) spec.loader.exec_module(mod) except Exception as e: # noqa: BLE001 (prototype : un détecteur cassé ne bloque pas la page) print(f"Journal : {path.name} sauté ({type(e).__name__}: {e})", file=sys.stderr) continue if hasattr(mod, "detect"): mods.append(mod) return mods def categorie(ep): return ep["kind"] def sorte(ep): """La sorte d'un épisode dans sa famille : les décalages ensemble, l'effet thermique sans « Camera », la perte de visibilité par niveau.""" label = "shift" if ep["label"] in DECALAGES else ep["label"].removeprefix("Camera ").capitalize() return ep["kind"], label, ep.get("level") def thermique(ep): return ep["kind"] == "Thermal displacement" def overlap(a, b): return a["start"] <= b["end"] and a["end"] >= b["start"] # heures donnees.iso : l'ordre du texte est celui du temps def targets(n): return "one target" if n == 1 else f"{n} targets" def phrase(groupe, sensors, references): """Phrase du journal d'un événement (validées par l'utilisateur le 2026-10-24), d'après la sorte de son épisode principal ; un saut absorbé ajoute qu'il a la même cause.""" n, one, ep = len(sensors), len(sensors) == 1, groupe[0] sauts = [e for e in groupe[1:] if e["label"] == SAUT] jumped = len({s for e in sauts for s in e["sensors"]}) lasting = len({s for e in groupe if e["label"] in DECALAGES for s in e.get("lasting", [])}) refs = ", including the reference targets" if references & set(sensors) else "" camera = ep["label"].startswith("Camera") large = any(e["label"] == "Large shift" for e in groupe) sort = "shift" if ep["label"] in DECALAGES else f"{ep['label']} {ep['level']}" if ep.get("level") else ep["label"] text = { "Poor visibility none": f"The camera could not see {targets(n)} clearly{refs}. " "The curves in this period are not reliable: ignore them.", "Poor visibility reduced": f"The camera saw {targets(n)} less clearly than usual{refs}. " "The data in this period are less precise: use them with care.", "Brief obstruction": f"Something passed in front of {targets(n)} for a single measurement. Ignore this point on the curves.", "Target obscured": f"{', '.join(sensors)} {'was' if one else 'were'} hidden several times while the targets around " f"{'it' if one else 'them'} stayed clear. Ignore {'its curve' if one else 'their curves'} in this period.", "Heat shimmer": "Warm air made the readings shake. The small fast wiggles are not movement.", "expansion": ("The camera support expands in the day heat; the curves are corrected for it." if camera else "The structure expands in the day heat.") + " This daily wave is normal: nothing to do.", "contraction": ("The camera support contracts as it cools down; the curves are corrected for it." if camera else "The structure contracts as it cools down.") + " This daily wave is normal: nothing to do.", SAUT: f"{targets(n).capitalize()} jumped and came back. The cause is not established: look at the images.", "shift": (f"{targets(n).capitalize()}, most of the targets, shifted together: everything moved." if large else f"{targets(n).capitalize()} shifted and {'has' if one else 'have'} not come back yet." if not lasting else f"{targets(n).capitalize()} shifted and stayed shifted." if lasting == n else f"{targets(n).capitalize()} shifted; {lasting} of them stayed shifted.") + " Check whether the structure moved: look at the images.", }.get(sort.split()[-1] if thermique(ep) else sort, ep["text"]) # No data, Target issue, Slow drift : le texte du détecteur if ep["kind"] == "Target issue": text += f" Ignore {'its curve' if one else 'their curves'} in this period and look at the images of the target." if not jumped: return text return text + (f" The jump of {targets(jumped)} in this period has the same cause." if len(sauts) == 1 else f" The jumps of {targets(jumped)} in this period have the same cause.") def evenement(groupe, references): """Épisodes d'un même événement, le principal en tête -> événement.""" cat, so = categorie(groupe[0]), sorte(groupe[0]) c = CATEGORIES.get(cat, {"ignore": None, "process": "aucun"}) sensors = [] if any(not e["sensors"] for e in groupe) else list(dict.fromkeys(s for e in groupe for s in e["sensors"])) main = [e for e in groupe if sorte(e) == so] # la durée est celle des épisodes principaux, pas des sauts absorbés return {"start": min(e["start"] for e in main), "end": max(e["end"] for e in main), "category": cat, "label": cat, "text": phrase(groupe, sensors, references), "ignore": c["ignore"] if c["ignore"] is not None else any(e["ignore"] for e in main), "sensors": sensors, "process": c["process"], "episodes": groupe} def classer(episodes, references=frozenset()): """Épisodes de tous les détecteurs -> événements triés par début (règles : docstring du module) ; references : les capteurs global_ref, pour la phrase.""" eps = sorted(episodes, key=lambda e: e["start"]) checks = [e for e in eps if e["label"] in DECALAGES] # un vrai mouvement n'est jamais pris pour de la turbulence eps = [e for e in eps if e["label"] != "Heat shimmer" or not any(overlap(e, c) for c in checks)] # la vague thermique n'absorbe qu'en dernier (un saut d'un passage ou d'une pluie va à eux), et que les sauts de # plusieurs cibles : la vague les fait bouger ensemble, une cible seule qui saute n'est pas la vague (C2 de E-003) hosts = sorted((e for e in eps if e["label"] in HOTES), key=thermique) host = {id(e): next((h for h in hosts if overlap(e, h) and (len(e["sensors"]) > 1 or not thermique(h)) and (h["label"] != "Brief obstruction" or e["start"] == h["start"] and datetime.fromisoformat(e["end"]) - datetime.fromisoformat(h["start"]) <= MERGE)), None) for e in eps if e["label"] == SAUT} # une dérive ou un saut revenu dont toutes les cibles sont dans un épisode Target issue qui le chevauche : sa courbe # est à ignorer, il en prend la famille (/detector-learner Displacement, modification 1, S6) host.update({id(e): h for e in eps if e["label"] in (SAUT, "Slow drift") and not host.get(id(e)) and (h := next((h for h in eps if h["kind"] == "Target issue" and overlap(e, h) and set(e["sensors"]) <= set(h["sensors"])), None))}) groupes = {id(e): [e] for e in eps if not host.get(id(e))} for e in eps: if host.get(id(e)): groupes[id(host[id(e)])].append(e) merged = [] for g in groupes.values(): prev = next((m for m in reversed(merged) if sorte(m[0]) == sorte(g[0]) and (g[0]["kind"] != "Obstruction" or set(g[0]["sensors"]) & {s for e in m for s in e["sensors"]})), None) end = max((e["end"] for e in prev if sorte(e) == sorte(g[0])), default=None) if prev else None if end and datetime.fromisoformat(g[0]["start"]) - datetime.fromisoformat(end) < MERGE: prev += g else: merged.append(g) return sorted((evenement(g, references) for g in merged), key=lambda v: v["start"]) def evenements(mesures, fin=None, dossier=None): """Mesures (donnees.charger) -> événements de tous les détecteurs : ce que la page reçoit dans D.journal. Un détecteur reçoit en plus ce que sa fonction detect déclare : fin, la fin de la fenêtre lue (tri en lot), pour un trou qui la touche ; une clé de CONTEXTE, lue dans le dossier de la station (une fois par dossier), vide sans dossier.""" episodes = [] for mod in detecteurs(): try: params = inspect.signature(mod.detect).parameters kw = {k: _contexte(dossier, k) if dossier else {} if k == "metriques" else [] for k in CONTEXTE if k in params} if "fin" in params: kw["fin"] = fin episodes += mod.detect(mesures, **kw) except Exception as e: # noqa: BLE001 print(f"Journal : {mod.__name__} sauté ({type(e).__name__}: {e})", file=sys.stderr) return classer(episodes, {s for s, ms in mesures.items() if ms[0]["pattern_type"] == "global_ref"}) if __name__ == "__main__": import argparse p = argparse.ArgumentParser(description="Une ligne par événement ; --tranche : chaque tranche classée seule.") p.add_argument("dossier") p.add_argument("--du", help="premier jour UTC, AAAA-MM-JJ (défaut : début des données)") p.add_argument("--au", help="dernier jour UTC exclu, AAAA-MM-JJ (défaut : fin des données)") p.add_argument("--tranche", type=int, default=0, help="jours par tranche (défaut : un seul passage)") # sans historique, une tranche qui commence juste avant un vrai saut le prend pour un saut revenu (PR17 à NORDEND, # le 08/10 à 02:30 : absorbé dans la buée) ; 3 jours le rendent ; règle de l'utilisateur (2026-10-24) : 3 jours # d'historique par défaut, dans la boucle comme dans la vraie application p.add_argument("--historique", type=int, default=3, help="jours de mesures d'avant donnés aux détecteurs (défaut 3)") a = p.parse_args() mesures = charger(a.dossier) ts = [m["t"] for ms in mesures.values() for m in ms] jour = lambda d: datetime.strptime(d[:10], "%Y-%m-%d").replace(tzinfo=timezone.utc) # noqa: E731 debut = jour(a.du) if a.du else min(ts).replace(hour=0, minute=0, second=0, microsecond=0) fin = jour(a.au) if a.au else max(ts) + timedelta(seconds=1) t = debut while t < fin: b = min(t + timedelta(days=a.tranche), fin) if a.tranche else fin h = t - timedelta(days=a.historique) tranche = {s: k for s, ms in mesures.items() if (k := [m for m in ms if h <= m["t"] < b])} evs = [v for v in evenements(tranche, b, a.dossier) if v["end"] >= iso(t)] if tranche else [] if a.tranche: print(f"== {iso(t)} → {iso(b)} : {len(evs) or 'rien'}") for v in evs: print(v["start"], "→", v["end"], f"{v['category']:<20}", "grisé" if v["ignore"] else "gardé", f"| {v['episodes'][0]['label']}", # la sorte : la règle du détecteur de la famille f"| {len(v['sensors']) or 'tous les'} capteurs", "| absorbés :", ", ".join( f"{e['label']} {e['start'][5:16]}" for e in v["episodes"][1:]) or "—") t = b