jejjohnson / jejjohnson/xrtoolz
V5.2: Domain detectors — DetectMarineHeatwaves, DetectEddies, DetectFronts
- Dominant language
- Python
- Stars
- 1
- Forks
- 0
- Avg merge
- 13d 21h
- Merged PRs (30d)
- 3
Description
## Summary
Concrete domain detectors built as presets over V5.1. Each ships with sensible defaults and tunable thresholds.
## API target
```python
def detect_marine_heatwaves(
ds, *, sst_var="sst", climatology=None, percentile=90, min_duration=5
) -> xr.Dataset: ...
def detect_eddies(
ds, *, ssh_var="ssh", method="closed_contour", min_radius=None, min_lifetime=None
) -> xr.Dataset: ...
def detect_fronts(
ds, *, variable, gradient_threshold=None, min_length=None
) -> xr.Dataset: ...
class DetectMarineHeatwaves(Operator): ...
class DetectEddies(Operator): ...
class DetectFronts(Operator): ...
```
## Detection methods
- **MHW**: Hobday et al. 2016 — anomalies above an N-th percentile of climatology, persisting ≥ `min_duration` days. Anomaly path uses existing `xr_toolz.geo.detrend` climatology helpers.
- **Eddies (`closed_contour`)**: SSH closed-contour method (Chelton et al. 2011 family). Identify local extrema → grow until contour breaks. Document the choice.
- **Fronts**: gradient-magnitude threshold + length filter. Variable can be SST, salinity, density.
## Acceptance criteria
- [ ] All three operators in `phenomena/_src/{mhw,eddies,fronts}.py`.
- [ ] MHW detection on a synthetic seasonal cycle + injected heatwave matches the heatwave window.
- [ ] Eddies: a synthetic Gaussian SSH bump is detected with correct centroid + radius.
- [ ] Fronts: a synthetic linear gradient is detected with correct orientation.
- [ ] All three emit Datasets that conform to the V5.1 object schema.
- [ ] Optional methods documented as future extension points (e.g. SLA-based eddies, OpenEddy, AMEDA).
Contributor guide
Research direction
Start by reading the V5.1 object schema, the Operator base, and the existing xr_toolz.geo.detrend climatology helpers. Implement the three operators in phenomena/_src/{mhw,eddies,fronts}.py, then validate them against synthetic seasonal, Gaussian SSH, and linear-gradient cases. Done means each detector matches its expected result, emits a V5.1-conforming Dataset, and documents future method extensions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- data
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100