jejjohnson / jejjohnson/xrtoolz
V3.3: Transport diagnostics — PairDispersion, ResidenceTime, ConnectivityMatrix, FTLE
- Dominant language
- Python
- Stars
- 1
- Forks
- 0
- Avg merge
- 13d 21h
- Merged PRs (30d)
- 3
Description
## Summary
Reusable transport diagnostics over trajectory Datasets. These are not skill scores — they produce *physical quantities* that V3.4 then compares.
## API target
```python
def pair_dispersion(trajectories, *, pairs=None) -> xr.DataArray: ...
def residence_time(trajectories, *, regions) -> xr.Dataset: ...
def connectivity_matrix(trajectories, *, source_regions, target_regions) -> xr.DataArray: ...
def ftle(ds, particles, *, integration_time, u_var="u", v_var="v") -> xr.DataArray: ...
class PairDispersion(Operator): ...
class ResidenceTime(Operator): ...
class ConnectivityMatrix(Operator): ...
class FTLE(Operator): ...
```
## Acceptance criteria
- [ ] All four implemented in `lagrangian/_src/diagnostics.py` with Layer 0 + Layer 1.
- [ ] `pair_dispersion`: monotonically increasing with time on a synthetic divergent flow.
- [ ] `residence_time`: matches analytic value for a particle confined to a known box.
- [ ] `connectivity_matrix`: row sums equal source-particle counts; sparse-region rows are zero.
- [ ] `ftle`: positive values along a known shear in the synthetic field.
- [ ] All operators consume Datasets that conform to V3.1 schema; emit informative errors otherwise.
## Notes
- `regions` accepts the same triplet that V1.2 normalizes (`regionmask.Regions` / int mask / dict-of-bool) — reuse the V1.2 normalizer if it has landed; otherwise reimplement minimally and consolidate later.
Contributor guide
Research direction
Start in lagrangian/_src/diagnostics.py and review the V3.1 Dataset schema plus the V1.2 region normalizer, if available. Define the four diagnostics and their Layer 0 and Layer 1 behavior, then validate them against synthetic divergent, confined-box, sparse-region, and shear cases. Done means all operators accept conforming Datasets, reject invalid inputs informatively, and satisfy the listed physical checks.
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