Document vertical skill workflow
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.qmdpage 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
.verticalaccessor:.skill(bins=...),.mean()/.min()/.max(),.plot.profile(),.plot.hovmoller()SkillProfilereturn typecmp.sel(z=...)for slicing depth ranges or selecting a layer
- When to use
- Add the page to
docs/_quarto.ymlsidebar (next tonetwork.qmd) - Cross-link from
workflow.qmdanddata-structures.qmd
Known caveats to call out in the docs
match(max_model_gap=...)is not yet supported for vertical matching — raisesNotImplementedError(seesrc/modelskill/matching.py:421)- Default depth-bin count for
vertical.skill()is 5, same convention asgridded_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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from DHI/modelskill
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
DHI/modelskill#628 ·
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
DHI/modelskill#706 ·
-
Difficulty 5/5 Over a week Newbie friendliness 20/100
DHI/modelskill#700 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 45/100
DHI/modelskill#697 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 48/100
DHI/modelskill#689 · 1 comment ·
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100