Skip to content

Runnable examples for every exported function, and Rd fixes (#212) - #252

Open
feralaes wants to merge 4 commits into
209-reference-strategy-corefrom
212-examples
Open

feralaes wants to merge 4 commits into
209-reference-strategy-corefrom
212-examples

Conversation

@feralaes

Copy link
Copy Markdown
Collaborator

Closes #212.

@evaenns, Fernando asked me to take this on so you can focus on the vignettes (#216). Could you review it? It's mostly roxygen text, so the most useful thing to check is whether each example teaches the right workflow.

Base: this PR is built on #227 (209-reference-strategy-core), because several examples use the reference-strategy and currency features. When #227 merges, GitHub retargets this PR to main.

Examples (31 functions and methods)

I found these by comparing NAMESPACE with man/*.Rd. Afterwards, the scan finds no exported function without an Examples section.

  • Analysis functions: beta_params, calc_evppi, calc_evsi, calculate_icers_psa, create_dsa_oneway, create_dsa_twoway, metamodel, number_ticks, owsa, owsa_opt_strat, owsa_tornado, twsa, run_psa, run_owsa_det, run_twsa_det.
  • S3 methods: plot.ceac, plot.evpi, plot.evppi, plot.evsi, plot.exp_loss, plot.icers, plot.owsa, plot.psa, plot.twsa, predict.metamodel, print.icers, print.metamodel, print.sa, summary.ceac, summary.metamodel, summary.psa.

Details:

  • The examples use cancer_psa_data, psa_cdiff and hund_strat, with DARTH names (l_psa, df_ceac, l_evppi, df_owsa, l_mm, …).
  • run_psa(), run_owsa_det() and run_twsa_det() share a 6-line two-strategy model, f_model(l_params, wtp). Its optimal strategy switches within the parameter ranges, so the one-way and two-way plots show something.
  • The create_dsa_* examples use the same model with hand-built tables.
  • Only two calls are in \donttest{}: the second calc_evsi() call (n_by_param = TRUE) and the EVSI-by-WTP call in plot.evsi. Every other example runs in under 5 s. The slowest is plot.evsi at 3.3 s, and all examples together take 17.7 s.

Rd fixes from the issue

  • create_dsa_twoway: the title and description said one-way.
  • calculate_icers_psa: the two \code{link{...}} were missing the backslash, and the make_psa_object link didn't exist.
  • check_psa_object(): the error told users to run make_psa(). It now says make_psa_obj().
  • Keywords:
    • the multi-word \keyword{} entries in beta_params, dirichlet_params, gamma_params, lnorm_params, calc_evpi, ceac and the VOI plot methods are now @keywords distribution (a standard keyword) or @concept;
    • R CMD check gives no keyword NOTE.
  • plot.ceac and summary.ceac were exported but hidden with @keywords internal. They now appear in the reference index.
  • lnorm_params: the stale "True values" comment is replaced by a line checking that exp(mu + sigma^2/2) gives back the mean.
  • psa_cdiff:
    • gains a title, description, @format for all 6 list elements, @source (Rajasingham et al. 2020, as cited in the basic_cea vignette) and an example;
    • the costs are described only as costs; nothing says they are USD.

Smaller corrections:

  • number_ticks returns a function;
  • twsa returns a twsa data frame, not a ggplot;
  • twsa's sa_obj now points to create_dsa_twoway;
  • a stray comma removed from run_psa's see-also;
  • a few see-also links added.

Things a reviewer may notice

  • print.sa on psa_cdiff prints "parameters: a data frame with rows and columns" because that dataset has no parameters. It's existing behavior. I used the dataset anyway because it's the only one with more than five strategies.
  • predict.metamodel prints row names like 1...1 for one-way results. Also existing behavior.

Verification

  • devtools::run_examples(run_donttest = TRUE) passes: 73 example files in 27.6 s, with no warnings.
  • devtools::test(): 476 passed, 0 failed. lintr: 0 lints.
  • Every vignette output is identical to the base branch. The only changed existing example output is lnorm_params, whose stale comment was replaced.
  • R CMD check --as-cran: only the development-version NOTE. That includes the examples, with no keyword NOTE.

The examples call ceac() with named arguments, so they work before and after #251, which changes its argument order.

- Add @examples to the 31 exported functions and S3 methods whose help
  pages had none, using cancer_psa_data, psa_cdiff, and hund_strat, and a
  tiny self-contained model for run_psa(), run_owsa_det(), and
  run_twsa_det(). The two slowest EVSI calls are in \donttest{}.
- create_dsa_twoway(): title and description said one-way.
- calculate_icers_psa(): fix \code{link{...}} without backslash and the
  link to the non-existent make_psa_object (now make_psa_obj); the note
  about confidence intervals refers to plot.icers().
- check_psa_object() error message now points to make_psa_obj().
- Replace the split multi-word \keyword{} entries (beta_params,
  dirichlet_params, gamma_params, lnorm_params, calc_evpi, ceac, plot.evpi,
  plot.evppi, plot.evsi) with \keyword{distribution} and \concept{} entries.
- plot.ceac() and summary.ceac() are no longer tagged internal.
- Remove the stale comment in the lnorm_params() example.
- Document the format and source of psa_cdiff.
- Smaller doc corrections: number_ticks() returns a function, twsa()
  returns a twsa data frame, twsa() sa_obj points to create_dsa_twoway().
…ix and the keyword fix in lnorm_params, and both NEWS bullets

Also use effect_units = "life-years" instead of "QALE" in the plot.evpi example.
@feralaes
feralaes requested a review from evaenns November 14, 2026 01:34
@codecov

codecov Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.83%. Comparing base (6afb4a7) to head (c7a7272).

Additional details and impacted files
@@                     Coverage Diff                      @@
##           209-reference-strategy-core     #252   +/-   ##
============================================================
  Coverage                        93.83%   93.83%           
============================================================
  Files                               18       18           
  Lines                             2028     2028           
============================================================
  Hits                              1903     1903           
  Misses                             125      125           
Files with missing lines Coverage Δ
R/add_common_aes.R 88.81% <ø> (ø)
R/ceac.R 90.90% <ø> (ø)
R/create_sa.R 91.25% <ø> (ø)
R/dsa_oneway.R 100.00% <ø> (ø)
R/dsa_twoway.R 72.72% <ø> (ø)
R/evpi.R 96.15% <ø> (ø)
R/evppi.R 95.45% <ø> (ø)
R/evsi.R 87.69% <ø> (ø)
R/exp_loss.R 100.00% <ø> (ø)
R/gen_psa_samp.R 99.25% <ø> (ø)
... and 7 more
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Resolve R/ceac.R: keep #251's argument order (psa, then wtp) and this PR's @concept in
place of the multi-word @Keywords. Examples now show the documented ceac(psa, wtp) order.
…Jalal and Alarid-Escudero 2018)

?calc_evsi had no references. Add the Gaussian approximation paper and Strong et al. (2014)
for the regression metamodel step, as ?calc_evppi does.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant