Families: Displacement is something that moved and never came back; Perturbation, new, what comes back without another family's cause, nothing to do (spec 2026-11-18-displacement-split-design)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-11-18 10:19:02 +01:00
1 parent c89c1b9976
commit df3a7120d3
6 files changed
+394 -10

No files matched your search

@@ -0,0 +1,99 @@
# Displacement split: Displacement and Perturbation
Status: draft, to be approved by the user. Nothing applied yet (`families.md` is read live by aimsight-app).
## Why
`Displacement` today is the bin of D-074 ("À vérifier", 2026-10-27): "a lasting jump, a slow drift, and anything that changes the corrected curves without an established cause". Of its 63 labels in `auto/`, 50 say in their own text that the structure did not move, or that a movement is not established. The user: a displacement is a movement, a real one; families must stay simple.
## Goals
- `Displacement` = something moved (a jump or a drift) and never came back.
- One new family, `Perturbation`, for what changes the corrected curves, comes back, and no other family explains: cause unclear or several factors; nothing to do.
- Simple families: two keys where there was one, no family per mechanism.
Non-goals: changing the other families; reworking `Thermal displacement` (its camera labels keep it); touching `manual/`.
Anti-goal: a `Perturbation` that hides a movement. What has not come back stays `Displacement`.
## Approaches
- **A. One catch-all** (`Unexplained`) for the 50 non-movement labels. Dropped: the old bin under a new name.
- **B. By what moves** (`Displacement` targets, `Camera movement`, `Artifact` base and spikes). Dropped: three keys; the user wants simple families.
- **C. By permanence (chosen by the user).** A camera movement is usually thermal: `Thermal displacement`, as today. Otherwise, the family follows whether the movement is permanent: it stays, `Displacement`; it comes back, `Perturbation`. The same rule for a target, a reference or the camera. It is also the line the detector already draws (`displacement.py`: "back" against "lasting" / "recent").
## The families
Proposed rows for `families.md` (main table):
| Key | Detector | What happens | For the client |
|---|---|---|---|
| `Displacement` | `displacement.py` (lasting shift, jump not back yet, slow drift) | something moved, by a jump or a drift, and has not come back by the end of the range: one or more targets, a reference, or the camera outside a thermal effect; the description says what moved | check what moved: the structure (look at the images, check on site) or the camera (check its mount) |
| `Perturbation` | `displacement.py` (jump back to normal) | the corrected curves move beyond their noise and come back, and no other family explains it: a jolt of the camera, a reference or the base shifted for a while, a single point, targets that wander and come back; the cause is not established or several factors mix | nothing to do: the curves came back; ignore these points |
Varieties:
| Variety | Family | For the client |
|---|---|---|
| `Sudden jump, back to normal` | Perturbation (was Displacement) | nothing to do: it came back; ignore these points |
| `Lasting shift` | Displacement | check what moved: look at the images |
| `Jump, not back yet` | Displacement | check what moved: look at the images |
| `Slow drift` | Displacement | keep watching it |
Boundaries, in `families.md`:
- **New, Displacement or Perturbation**: decided by the return, not by the cause. What moved and has not come back by the end of the range (a target, a reference, the camera outside a thermal effect) is Displacement; what comes back, even after days, is Perturbation. A camera that moves and stays is Displacement even when the compensation absorbs it afterwards; the description says it is the camera. A partial return is not a return.
- **Thermal displacement or Displacement** (line 33): unchanged; add that what does not follow the temperature and comes back is Perturbation.
- **A jump then the return** (line 32): "Without an established cause: Displacement" becomes "Perturbation".
- **A hindered reference** (line 31): "Visibility, or Displacement without a cause" becomes "Visibility, or Perturbation without a cause; Displacement if the base stays changed".
- **Target issue or Displacement** (line 37): unchanged.
Phenomena: since the cases work of 2026-11-18 (`2026-11-18-cases-design.md`), they are the cases of `auto/cases/`, no longer a section of `families.md`. The cases of family `Displacement` that come back move to `Perturbation`; the rest is as first drafted here: the Displacement section keeps the movements that stay ("a real movement of the structure", "a target or a small group jumps and stays shifted", "a step taken during a measurement outage", "the camera tilts little by little", "a step of the camera that the compensation does not erase", when it stays); a new Perturbation section takes "targets move slowly, alone, then come back", "the base changes without a reference lost" (with its return), and adds "a jolt of the camera, back at the next measurement", "a reference measured shifted alone, then back", "a single point of one or a few targets, back at once".
`labeling-rules.md`: line 63, the list of keys gains `Perturbation`; line 86 is rewritten: a Displacement says what moved and that it has not come back, and concludes "the targets moved: to check on site, monitor" or "the camera moved and stays: check its mount"; a Perturbation says what moved, that it came back and when, and concludes "nothing to do: points to ignore". A Perturbation states its cause in the three ways of line 99, like any label; "nothing to do" rests on the return seen, not on a cause (line 102).
## The 63 labels
By the rule above (return judged on the whole range of the analysis):
**Displacement, 27** (family unchanged, description unchanged but NORDEND-250):
- targets that moved and stay: CLARIDEN-9, CLARIDEN-23, FLORIDA-46, NEBRASKA-5, NIEDERHORN-131, NIEDERHORN-167, NIEDERHORN-168, NORDEND-94, WILDSTRUBEL-89, WILDSTRUBEL-120, WILDSTRUBEL-173, WILDSTRUBEL-183;
- camera that moved and stays: BREITHORN-43, BREITHORN-39, BREITHORN-44, CLARIDEN-74, MICHIGAN-19, NEBRASKA-1, NEBRASKA-6, NORDEND-250, NORDEND-309, SNCF01-7, SNCF01-42, SNCF01-102, SNCF01-132, WILDSTRUBEL-200;
- base that stays changed: NORDEND-276.
**Perturbation, 36** (family changes):
- base or a reference shifted, then back: ALASKA-1, ALASKA-3, ALASKA-5, ALASKA-6, ALASKA-9, FLORIDA-18, FLORIDA-72, JUNGFRAU-110, JUNGFRAU-112, LENZSPITZE-105, LENZSPITZE-106, LENZSPITZE-108, MICHIGAN-8, NIEDERHORN-126, NORDEND-112, NORDEND-279, WILDSTRUBEL-136, WILDSTRUBEL-153, WYOMING-9, WYOMING-13, WYOMING-17;
- camera jolt or shift, then back: LENZSPITZE-84, NEBRASKA-3, NORDEND-80, NORDEND-243, NORDEND-278, NORDEND-310, WYOMING-11, WYOMING-16;
- single points, back at once: ALASKA-2, LENZSPITZE-98, NIEDERHORN-144, NIEDERHORN-157, NORDEND-251, NORDEND-271;
- a target that moved, then came back: NORDEND-257.
Calls made by the drafter (to check):
- A partial return is not a return: BREITHORN-39 (inside the camera drift of BREITHORN-43 and -44), NEBRASKA-5 (COLJ19 comes back only in part), NIEDERHORN-131 (three targets come back in part, two stay): Displacement.
- NORDEND-94: its text says the curves of PR17 came back neither to their level before the jump nor to the plateau, to the end of the batch: Displacement (the first draft had it as Perturbation).
- NORDEND-250: the camera keeps its step, the curves come back at the next measurement: Displacement, following "the permanent movement of the camera".
- NORDEND-276: the base stays changed to the end of the range, the targets do not move in the image: Displacement (something stays moved, possibly a reference).
- WILDSTRUBEL-120 mixes a return (PB_5) and a lasting shift (PA3_2): Displacement for the shift that stays.
- No Displacement label becomes Thermal displacement: none comes back with the housing temperature (families.md, line 33).
Descriptions to reword, their conclusion contradicting their new family: NEBRASKA-3, NORDEND-257, NORDEND-310, FLORIDA-18, WILDSTRUBEL-136 (Perturbation, but "to be monitored", "to be checked"), and NORDEND-250 (Displacement of the camera, but "point to ignore"). Only the closing sentence changes; the plan gives each.
The copies in `auto/analyses/*/labels.jsonl` follow the same change.
## What it touches
- **aimsight-labeling**: `families.md`, `labeling-rules.md`, `scripts/validate.py` (`FAMILIES`), `scripts/client.py` (its check), the 38 labels in `auto/` and their copies in the analyses; `ids.py` untouched, ids never change.
- **aimsight-detectors**: `scripts/displacement.py`, a "back" episode gets kind `Perturbation` (one line); `scripts/categories.py`, `CATEGORIES` gains `Perturbation` (greyed, nothing to do), and `host()` keeps joining a jump back to the Visibility or Obstruction around it.
- **aimsight-app**: `app/web/src/pages/Data.jsx`, `FAMILIES` gains `Perturbation` and its colour (the Category menu and the timeline follow).
- **The agents' instructions**: `aimsight-agents/agents/analyst.md` (the list of family keys); `Support-Agent/.claude/skills/support/rapport.md` (the order of the families for the client). The `etiqueteur` and `detectors-critic` of Support-Agent still speak the old format (`familles.md`, `categorie`): left as they are.
- **The detectors' docs**: "the six families" in `aimsight-detectors/CLAUDE.md` and `README.md`, and in the comment of `Data.jsx`, become seven.
- **aimsight-optimizer**: nothing in code; its benchmark reads `auto/`, so the Displacement scores change meaning from the relabel on.
- **manual/**: the expert's labels keep the old meaning of Displacement; to tell the expert, not to change.
## Open, for the user
1. **The review dates.** All 63 labels carry a `review` (2026-11-17, 2026-11-18), and any change removes it (`README.md`). Approved: keep `review` on a change of family made at the user's request, remove it on the 6 reworded descriptions.
2. **The return window of the detector.** The labels judge the return on the whole range; the detector on 24 hours (`BACK_H`): a shift back after two to six days (ALASKA-9, FLORIDA-18, NEBRASKA-3, WILDSTRUBEL-136, WILDSTRUBEL-153) is Perturbation in the labels and Displacement for the detector. Approved: leave `BACK_H` to the optimizer, which learns from the labels.
## Left to the builder
The exact wording of the phenomena lines; the colour of Perturbation in aimsight-app; the order of the commits across the three repositories (labeling first, then detectors and app, the same day: aimsight-app rejects a label whose family `validate.py` does not know).