Document vertical skill workflow

Open
#645 0 comments 0 reactions 0 assignees View on GitHub

A pull request for this has already been merged.

  • #653 by @ecomodeller — merged

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Stale
Tech stack
jupyter-notebook, markdown, python
Domain
documentation

Research direction

Start with notebooks/vertical_skill.ipynb and inspect the existing sidebar in docs/_quarto.yml, then read workflow.qmd, data-structures.qmd, and ADR-011 for terminology and links. Add docs/user-guide/vertical.qmd, place it beside network.qmd, and cross-link the two guide pages. Done means the page covers the listed workflows, caveats, examples, return type, and depth selection clearly in the rendered documentation.

Written by the indexing model from the issue text.

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 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
Dominant language
Python
Stars
56
Forks
9
Avg merge
57m
Merged PRs (30d)
3

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from DHI/modelskill

All issues in DHI/modelskill

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.