jejjohnson / jejjohnson/xrtoolz

V5.1: EventDefinition + generic detection / labelling / matching

Open
#64 0 comments 1 reaction 2 assignees Claimed by @jejjohnson View on GitHub
area:code enhancement validation-framework
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.