Document vertical skill workflow
- 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
Assessment
This issue has not been assessed yet.