jejjohnson / jejjohnson/xrtoolz
V5.1: EventDefinition + generic detection / labelling / matching
- Dominant language
- Python
- Stars
- 1
- Forks
- 0
- Avg merge
- 13d 21h
- Merged PRs (30d)
- 3
Description
## Summary
Foundational machinery for V5. Define the reusable event spec, the generic anomaly-object detector, the connected-component labeller, and the IoU/centroid matcher. Domain detectors (V5.2) and object metrics (V5.3) build on this.
## API target
```python
@dataclass(frozen=True)
class EventDefinition:
variable: str
threshold: float | str # absolute number or percentile string like "p90"
baseline: xr.Dataset | None = None # e.g. climatology for anomaly events
min_duration: int | None = None
min_area: float | None = None
connectivity: int = 8
anomaly: bool = True
# Generic detection / labelling
def detect_anomaly_objects(ds, definition: EventDefinition) -> xr.Dataset: ...
def label_objects(mask: xr.DataArray, *, dims=("lat", "lon"), connectivity=8) -> xr.Dataset: ...
def match_objects(objects_pred, objects_ref, *, method="iou", threshold=0.1) -> xr.Dataset: ...
class DetectAnomalyObjects(Operator): ...
class LabelObjects(Operator): ...
class MatchObjects(Operator): ...
```
## Behaviour
- `detect_anomaly_objects` is the *generic* path: build a boolean mask from `(ds, definition)`, label connected components, filter by `min_duration` / `min_area`. Domain detectors in V5.2 are presets over this.
- Output Dataset schema: `(event, time)` dims, with `lon`, `lat`, `area`, `centroid_lon`, `centroid_lat`, `intensity_max`, `intensity_mean`, `start_time`, `end_time`, `duration`. Document this; it's the contract V5.3 / V5.4 metrics consume.
- `match_objects`: IoU and centroid-distance methods at minimum. Returns matched-pair metadata as a Dataset.
## Acceptance criteria
- [ ] `EventDefinition` dataclass with frozen + JSON-serializable representation.
- [ ] `detect_anomaly_objects` + `label_objects` + `match_objects` Layer 0 + Layer 1.
- [ ] Test: synthetic Gaussian blobs above threshold are detected at the expected location and area.
- [ ] Test: IoU matching on identical inputs scores 1; on disjoint inputs scores 0.
- [ ] Object Dataset schema documented in module docstring.
- [ ] `scikit-image` lazy-imported only where used.
## Notes
- This issue locks the object schema. V5.2 / V5.3 / V5.4 / V5.5 inherit it. Discuss in this issue's review thread; do not change later without an amendment.
Contributor guide
Assessment
This issue has not been assessed yet.