jejjohnson / jejjohnson/xrtoolz

V5.2: Domain detectors — DetectMarineHeatwaves, DetectEddies, DetectFronts

Open
#65 0 comments 0 reactions 0 assignees 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
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.