"""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 de plusieurs cibles n'est pas gardée : un vrai mouvement agite aussi les courbes ; le décalage d'une seule cible ne retire pas la turbulence de toute la scène, et une turbulence n'absorbe que les sauts revenus qui commencent pendant elle, pas celui de la veille qui revient dans sa journée (/detector-learner Visibility, modification 1, S1 : WILDSTRUBEL) ; - 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) ; deux Target issue aussi : chaque cible à problème garde ses bornes (/detector-learner Target issue, modification 1, S3) ; 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.dirname(os.path.abspath(__file__))) # donnees.py, à côté 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"]) # un vrai mouvement n'est jamais pris pour de la turbulence ; le décalage d'une seule cible n'est pas un mouvement de la scène checks = [e for e in eps if e["label"] in DECALAGES and len(e["sensors"]) > 1] 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"] != "Heat shimmer" or h["start"] <= e["start"]) 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"] not in ("Obstruction", "Target issue") 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