docs: pedagogical audit of varPro wrappers (gg_partial_varpro, gg_varpro, gg_udependent)#95
Merged
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #95 +/- ##
=======================================
Coverage 87.62% 87.62%
=======================================
Files 40 40
Lines 3193 3193
=======================================
Hits 2798 2798
Misses 395 395
🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR extends the documentation for the three existing varPro wrappers (gg_varpro, gg_partial_varpro, gg_udependent) and their plot methods to include more pedagogical “what it’s doing / what’s in the output / what you use this for” (and “how to read the plot”) sections, mirroring the documentation pattern introduced for gg_isopro.
Changes:
- Add “teaching sections” to the roxygen help pages for
gg_varpro,gg_partial_varpro, andgg_udependent. - Add “Reading the … / What this tells you” sections to the corresponding plot method docs.
- Bump development version in
DESCRIPTIONandNEWS.md, and update generated.Rdfiles accordingly.
Reviewed changes
Copilot reviewed 8 out of 14 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| R/gg_varpro.R | Adds pedagogical sections explaining varPro “release rules” importance, output structure, and usage framing. |
| R/gg_partial_varpro.R | Adds pedagogical sections explaining partial dependence outputs and interpretation. |
| R/gg_udependent.R | Adds pedagogical sections explaining unsupervised dependency graph construction and usage framing. |
| R/plot.gg_varpro.R | Adds guidance on reading the importance boxplot and what conclusions to draw. |
| R/plot.gg_partial_varpro.R | Adds guidance on reading partial dependence plots and interpreting effect-type differences. |
| R/plot.gg_udependent.R | Adds guidance on reading the dependency network plot and what to do with it. |
| man/gg_varpro.Rd | Regenerated Rd reflecting new gg_varpro teaching sections. |
| man/gg_partial_varpro.Rd | Regenerated Rd reflecting new gg_partial_varpro teaching sections. |
| man/gg_udependent.Rd | Regenerated Rd reflecting new gg_udependent teaching sections. |
| man/plot.gg_varpro.Rd | Regenerated Rd reflecting new plot reading/interpretation sections. |
| man/plot.gg_partial_varpro.Rd | Regenerated Rd reflecting new plot reading/interpretation sections. |
| man/plot.gg_udependent.Rd | Regenerated Rd reflecting new plot reading/interpretation sections. |
| NEWS.md | Adds a NEWS bullet describing the pedagogical documentation pass; bumps dev version header. |
| DESCRIPTION | Bumps package version to match NEWS. |
Files not reviewed (6)
- man/gg_partial_varpro.Rd: Language not supported
- man/gg_udependent.Rd: Language not supported
- man/gg_varpro.Rd: Language not supported
- man/plot.gg_partial_varpro.Rd: Language not supported
- man/plot.gg_udependent.Rd: Language not supported
- man/plot.gg_varpro.Rd: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
ehrlinger
added a commit
that referenced
this pull request
May 26, 2026
- plot.gg_udependent: clarify that truly isolated nodes are dropped by
gg_udependent() before plotting; reword 'Isolated' as 'low-degree'.
- gg_partial_varpro: fix varpro::partialpro -> varPro::partialpro (six
instances) so \link{} renders correctly.
- plot.gg_varpro: clarify the cutoff line lives in z-units on the
default axis and in raw-importance units when type='raw'; the
numeric is the same, the scale is not.
- gg_varpro reference: complete the dangling 'arXiv 2409.' with the
full arXiv:2409.09003 identifier and an https://arxiv.org link.
Add Roxygen: list(markdown = TRUE) to DESCRIPTION so devtools::document()
auto-converts backticks / [fn()] / [pkg::fn()] in source roxygen to
\code{} / \link{} / \link[pkg]{} in the generated Rd. Existing Rd-style
markup keeps working; both styles now coexist. Saves the manual
conversion work the Copilot review on PR #94 flagged.
Two source-roxygen edits needed to keep R CMD check clean under markdown:
- R/help.R: randomForest[SRC] -> randomForestSRC (markdown read [SRC]
as an unfinished link reference, producing a missing-link warning).
- R/gg_rfsrc.R::bootstrap_survival: 95\% -> 95% (markdown over-escaped
the backslash, producing a malformed Rd with shifted section order).
Regenerates all 31 Rd files. No functional or rendered-content change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- plot.gg_udependent: clarify that truly isolated nodes are dropped by
gg_udependent() before plotting; reword 'Isolated' as 'low-degree'.
- gg_partial_varpro: fix varpro::partialpro -> varPro::partialpro (six
instances) so \link{} renders correctly.
- plot.gg_varpro: clarify the cutoff line lives in z-units on the
default axis and in raw-importance units when type='raw'; the
numeric is the same, the scale is not.
- gg_varpro reference: complete the dangling 'arXiv 2409.' with the
full arXiv:2409.09003 identifier and an https://arxiv.org link.
ehrlinger
force-pushed
the
docs/varpro-pedagogical-audit
branch
from
6c5bbd3 to
57d8c47
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Apply the same pedagogical documentation pattern used for
gg_isopro(PR #94) to the three existing varPro wrappers, so a reader new to varPro can learn the underlying method from the help page — not just the wrapper's mechanics.Each function now carries three teaching sections:
gg_varpro; parametric / nonparametric / causal partial estimators forgg_partial_varpro; beta-entropy dependency selection forgg_udependent).Plot methods get "Reading the X" and "What this tells you" sections covering how to read the figure and what action to take from it.
Scope guardrail
This is voice-only and additive. No
@param,@return,@examples, function bodies, defaults, citations, or cross-references were changed. The PR #92 lesson about over-generalization was honored — the implementer subagent explicitly flagged three places where it was tempted to assert something it could not confirm from varPro's own help text, and declined to.Test plan
devtools::check(args = "--as-cran")— 0 errors, 0 warnings, 0 notesCompanion to PR #94 (gg_isopro, Phase 4 sub-project 1).
🤖 Generated with Claude Code