docs: v3.1.0 documentation sweep (HELD — do not merge until v3.0.0 accepted)#109
Draft
ehrlinger wants to merge 16 commits into
Draft
docs: v3.1.0 documentation sweep (HELD — do not merge until v3.0.0 accepted)#109ehrlinger wants to merge 16 commits into
ehrlinger wants to merge 16 commits into
Conversation
…ion (with severity triage)
…rpro) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…-dependence framing)
…l; non-positive VIMP wording)
Remove stale yvar @return item from gg_roc — the function returns sens/spec/pct (from calc_roc), not a yvar column per observation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Deepens all prose sections of varpro.qmd with release-rules/guided-splitting framing; adds Lee:2021 bib key (AOS 49:4) cited in PBC section; adds varProtools URL in Further Reading. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Fix a misleading AUC trapezoidal-rule comment in calc_roc.R (the old text introduced Δ(FPR) but the code uses Δspec; reworded to state the equivalence plainly). Remove a stale varPro-specific note from the categorical branch of gg_partial.R (plot.variable output has no connection to varPro one-hot encoding). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #109 +/- ##
=======================================
Coverage 87.04% 87.04%
=======================================
Files 44 44
Lines 3936 3938 +2
=======================================
+ Hits 3426 3428 +2
Misses 510 510
🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
Documentation-focused sweep to deepen and tighten ggRandomForests’ v3.x docs (roxygen, vignettes, and a couple of code comments), clarifying the conceptual split between gg_vimp() (permutation/Breiman–Cutler VIMP) and the varPro “release-rule” family, while keeping the branch held at version 3.0.0 pending CRAN acceptance.
Changes:
- Deepened vignette prose (varPro + regression + survival + intro) and added cross-engine framing/links/references (incl. Lee et al. 2021 BibTeX entry).
- Expanded roxygen documentation across rfsrc/varPro-related functions and plot methods; regenerated corresponding
man/*.Rd. - Opened a
v3.1.0 (development)section inNEWS.md(without bumping the package version line).
Reviewed changes
Copilot reviewed 32 out of 42 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| vignettes/varpro.qmd | Expanded varPro vignette narrative and methodological framing. |
| vignettes/ggRandomForests.qmd | Intro vignette updated to mention varPro as a parallel engine and contrast importance methods. |
| vignettes/ggRandomForests.bib | Added Lee et al. (2021) reference entry. |
| vignettes/ggRandomForests-survival.qmd | Deepened survival vignette explanations (survival/CHF/mortality, VIMP, Brier/CRPS). |
| vignettes/ggRandomForests-regression.qmd | Added explicit gg_vimp() vs gg_varpro() contrast in regression vignette. |
| R/plot.gg_vimp.R | Roxygen expanded to explain permutation VIMP plotting and positive coloring. |
| R/plot.gg_survival.R | Roxygen expanded to explain plot behavior, CI overlays, and y-axis types. |
| R/plot.gg_rfsrc.R | Roxygen expanded to explain OOB ensemble predictions and family-specific geometries. |
| R/plot.gg_partial.R | Roxygen expanded for partial dependence plotting (incl. model overlay behavior). |
| R/plot.gg_ivarpro.R | Roxygen clarified SHAP-like visual resemblance vs release-rule contributions. |
| R/plot.gg_brier.R | Roxygen expanded to explain Brier/CRPS interpretation and envelope ribbon. |
| R/gg_vimp.R | Added @details contrasting permutation VIMP vs varPro release rules; updated @seealso. |
| R/gg_survival.R | Expanded @details describing KM baseline purpose and rfsrc/default dispatch behavior. |
| R/gg_roc.R | Corrected @return column documentation (now documents pct). |
| R/gg_rfsrc.R | Expanded roxygen describing OOB ensemble predictions and family-specific returned structure. |
| R/gg_partial.R | Expanded roxygen; removed stale inline comment about varPro factor handling. |
| R/gg_partial_varpro.R | Added @seealso cross-links to gg_varpro and gg_vimp. |
| R/gg_partial_rfsrc.R | Expanded roxygen describing marginalization, survival partial.type, and partial.time. |
| R/gg_ivarpro.R | Expanded “What this is doing” section; added cross-link to gg_vimp. |
| R/gg_brier.R | Expanded description/details explaining Brier/CRPS + IPCW and returned objects. |
| R/gg_beta_varpro.R | Expanded “What this is doing” section; added cross-link to gg_vimp. |
| R/calc_roc.R | Clarified AUC trapezoid-rule comment wording (no functional change). |
| NEWS.md | Opened v3.1.0 (development) heading while keeping version line at 3.0.0. |
| man/plot.gg_vimp.Rd | Regenerated Rd reflecting plot.gg_vimp roxygen updates. |
| man/plot.gg_survival.Rd | Regenerated Rd reflecting plot.gg_survival roxygen updates. |
| man/plot.gg_rfsrc.Rd | Regenerated Rd reflecting plot.gg_rfsrc roxygen updates. |
| man/plot.gg_partial.Rd | Regenerated Rd reflecting plot.gg_partial roxygen updates. |
| man/plot.gg_partial_rfsrc.Rd | Regenerated Rd reflecting plot.gg_partial_rfsrc roxygen updates. |
| man/plot.gg_ivarpro.Rd | Regenerated Rd reflecting plot.gg_ivarpro roxygen updates. |
| man/plot.gg_brier.Rd | Regenerated Rd reflecting plot.gg_brier roxygen updates. |
| man/gg_vimp.Rd | Regenerated Rd reflecting gg_vimp roxygen updates and @seealso links. |
| man/gg_survival.Rd | Regenerated Rd reflecting gg_survival roxygen updates. |
| man/gg_roc.rfsrc.Rd | Regenerated Rd reflecting gg_roc return-column doc fix (pct). |
| man/gg_rfsrc.rfsrc.Rd | Regenerated Rd reflecting gg_rfsrc roxygen updates. |
| man/gg_partial.Rd | Regenerated Rd reflecting gg_partial roxygen updates. |
| man/gg_partial_varpro.Rd | Regenerated Rd reflecting gg_partial_varpro @seealso updates. |
| man/gg_partial_rfsrc.Rd | Regenerated Rd reflecting gg_partial_rfsrc roxygen updates. |
| man/gg_ivarpro.Rd | Regenerated Rd reflecting gg_ivarpro roxygen updates and @seealso links. |
| man/gg_brier.Rd | Regenerated Rd reflecting gg_brier roxygen updates. |
| man/gg_beta_varpro.Rd | Regenerated Rd reflecting gg_beta_varpro roxygen updates and @seealso links. |
| dev/plans/2026-05-29-v3.1.0-doc-sweep-plan.md | Added implementation plan document for the held doc sweep. |
| dev/plans/2026-05-29-v3.1.0-doc-sweep-design.md | Added design/spec document for the held doc sweep. |
Files not reviewed (10)
- man/gg_beta_varpro.Rd: Language not supported
- man/gg_brier.Rd: Language not supported
- man/gg_ivarpro.Rd: Language not supported
- man/gg_partial.Rd: Language not supported
- man/gg_partial_rfsrc.Rd: Language not supported
- man/gg_partial_varpro.Rd: Language not supported
- man/gg_rfsrc.rfsrc.Rd: Language not supported
- man/gg_roc.rfsrc.Rd: Language not supported
- man/gg_survival.Rd: Language not supported
- man/gg_vimp.Rd: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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.
HELD DRAFT — do NOT merge until CRAN accepts v3.0.0. Version stays
3.0.0on this branch; the cut to3.1.0(DESCRIPTION + NEWS) happens at the post-acceptance RC. Perdev/plans/2026-05-29-v3.1.0-doc-sweep-design.md+...-plan.md.What this is
A documentation deepening pass against the upstream canonical sources (
varprotools.org,randomForestSRC.org), in John's voice, building on the v3.0.0 PR #92 voice audit. No user-facing behaviour change.Changes
gg_varpro/beta/ivarpro/udependent/isopro/partial_varpro) and rfsrc importance/partial/survival (gg_vimp,gg_partial(_rfsrc),gg_rfsrc,gg_survival,gg_brier). The headline clarification:gg_vimp(permutation / Breiman-Cutler VIMP) vsgg_varpro(varPro release-rule, no-synthetic-features importance), explicit and cross-@seealso'd in both.gg_roc@return(documented ayvarcolumn the function never returns).varprotools.org/randomForestSRC.orglinks +Lee:2021reference added; em-dashes trimmed to voice standard.calc_roc; stale varPro-one-hot comment ingg_partial).v3.1.0 (development)heading opened (version line unchanged).Verification
R CMD check --as-cranwith manual: 0 errors / 0 warnings / 0 notes.devtools::document()clean.On v3.0.0 acceptance
Cut version →
3.1.0, finalize NEWS +cran-comments.md, full release gate, merge tomain, submit, then forward-mergemain→dev.🤖 Generated with Claude Code