DHI / DHI/modelskill

Document vertical skill workflow

Open
#645 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
56
Forks
9
Avg merge
57m
Merged PRs (30d)
3

Description

Vertical skill landed in #585 but has no user-facing documentation. The `notebooks/vertical_skill.ipynb` is a useful starting point but not part of the rendered docs.

## Scope

- Add a `docs/user-guide/vertical.qmd` page covering:
- When to use `VerticalObservation` / `VerticalModelResult` (sigma/sigma-z columns, fixed (x, y))
- Reading observations from dfs0 / DataFrame / xarray (z_item, item, aux_items)
- The "pre-extracted column" requirement — link to [ADR-011](../adr/011-vertical-pre-extracted-columns.md) and show the mikeio extraction snippet users need to run before constructing a `VerticalModelResult`
- Matching: nearest-time + linear interp on depth, default tolerance = half median model dt
- `.vertical` accessor: `.skill(bins=...)`, `.mean()`/`.min()`/`.max()`, `.plot.profile()`, `.plot.hovmoller()`
- `SkillProfile` return type
- `cmp.sel(z=...)` for slicing depth ranges or selecting a layer
- Add the page to `docs/_quarto.yml` sidebar (next to `network.qmd`)
- Cross-link from `workflow.qmd` and `data-structures.qmd`

## Known caveats to call out in the docs

- `match(max_model_gap=...)` is not yet supported for vertical matching — raises `NotImplementedError` (see `src/modelskill/matching.py:421`)
- Default depth-bin count for `vertical.skill()` is 5, same convention as `gridded_skill`
- No spatial check between obs (x, y) and model column (x, y) — see ADR-011

## Reference material

- `notebooks/vertical_skill.ipynb` — has plots and example flows worth lifting
- Survey results in #585 PR description (~40 responses) — informs what users actually want documented

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.