jejjohnson / jejjohnson/xrtoolz

V3.3: Transport diagnostics — PairDispersion, ResidenceTime, ConnectivityMatrix, FTLE

Open
#52 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
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.