Skip to content

Harmonize the API with soft deprecation: ceac(psa, wtp), linewidth, axis limits, effect_units (#214) - #251

Merged
feralaes merged 4 commits into
209-reference-strategy-corefrom
214-api-harmonize
Nov 14, 2026
Merged

feralaes merged 4 commits into
209-reference-strategy-corefrom
214-api-harmonize

Conversation

@feralaes

@feralaes feralaes commented Nov 14, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #214.

Base: this PR is built on #227 (209-reference-strategy-core), because it changes the plot methods that #227 and #242 also change. When #227 merges, GitHub retargets this PR to main.

Nothing breaks. Every v1.0.x call still works, and the old forms give one soft deprecation warning through lifecycle::deprecate_soft().

Changes

ceac(psa, wtp)

  • ceac() now takes the psa object first, like calc_exp_loss(), calc_evpi(), calc_evppi() and calc_evsi().
  • The old positional ceac(wtp, psa) is detected because its second argument is a psa object. It's swapped, and it warns: "The wtp argument of ceac() must come after psa as of dampack 1.1.0. Use ceac(psa, wtp)…"
  • Named calls (ceac(wtp = , psa = )) work in any order without a warning. The vignettes and the df_example_psa_elc example already use them.

linewidth

  • plot.owsa(size = ) and plot.exp_loss(lsize = ) become linewidth, the name ggplot2 itself uses.
  • The old arguments still work, with a deprecation warning.

Axis limits

  • plot.owsa() and plot.twsa() gain xlim and ylim. In plot.owsa() the limits apply to every panel.
  • owsa_opt_strat() gains xlim. Its y axis is categorical, so it has no ylim.

effect_units

  • The default is now "QALYs" everywhere. Before, it was "QALYs" in plot.icers() and "QALY" elsewhere.
  • Labels that mean "per unit" use the singular through a small helper, per_unit(). That's what wtp_caption() already did.
  • All default labels are unchanged: "Effect (QALYs)", "Thousand $/QALY", "WTP = $50,000/QALY".
  • effect_units = "life-years" gives "$/life-year", and a unit already in the singular is used as given.
  • The one visible change is the y axis of EVPPI and EVSI plots for net health benefit, which now reads "EVPPI (QALYs)". That label is new in this release (Carry the currency of a psa object through to its analyses (#203) #242), so no released output changes.

API style decision record

  • New section in .github/CONTRIBUTING.md. It records:
  • It also lists the open questions for 2.0 for the group to decide (meeting decision 3):
    • calc_ versus calculate_;
    • effect versus effectiveness;
    • the column case of result tables.
  • No aliases are added in 1.1.0.

Dependencies: lifecycle added to Imports, with no version bound, like dplyr and tidyr. Current dplyr already needs lifecycle 1.0.5, so a lower pin made the minimum-dependency environment unsolvable (the CI job caught this twice). dampack only uses deprecate_soft(), deprecated() and is_present().

What I didn't add, and why

The issue listed col as missing from plot.icers(), plot.evpi() and plot.evppi(). plot.icers() tells statuses apart by shape and line type, not color, and the two VOI plots draw a single line. A col argument would have no effect, so the decision record says col exists only where strategies or groups are colored. If the group wants colored ICER plots, that would be a new feature for v1.2.

Tests

New test_api_harmonize.R, with 24 expectations:

  • the three ceac() call forms give identical results, and only the old positional one gives a deprecation (lifecycle::expect_deprecated());
  • size and lsize map to linewidth, with a deprecation;
  • the axis limits reach the scales;
  • the default labels are unchanged;
  • per_unit() handles plural and singular units.

Existing tests now use ceac(psa, wtp) and linewidth.

Verification

  • devtools::test(): 500 passed, 0 failed. The only 3 warnings are mgcv's in test_metamod.R.
  • lintr: 0 lints.
  • Every vignette and Rd example output is identical to the base branch.
  • R CMD check --as-cran: only the development-version NOTE.
  • NEWS entries under New features and Superseded.

…idth, axis limits, effect_units

- ceac() takes the psa object first, like calc_exp_loss() and calc_evpi(). The old positional
  ceac(wtp, psa) still works with lifecycle::deprecate_soft(); named calls work in any order.
- plot.owsa() and plot.exp_loss() take linewidth; size and lsize still work, deprecated.
- plot.owsa() and plot.twsa() gain xlim/ylim, owsa_opt_strat() gains xlim.
- effect_units defaults to "QALYs" in every plot; per_unit() gives the singular for
  willingness-to-pay labels, so default labels are unchanged ("$/QALY").
- lifecycle (>= 1.0.0) added to Imports.
- API style decision record in .github/CONTRIBUTING.md, including the open 2.0 questions.
@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 (785f347) to head (b7d53e9).

Additional details and impacted files
@@                       Coverage Diff                       @@
##           209-reference-strategy-core     #251      +/-   ##
===============================================================
+ Coverage                        93.69%   93.83%   +0.14%     
===============================================================
  Files                               18       18              
  Lines                             2013     2028      +15     
===============================================================
+ Hits                              1886     1903      +17     
+ Misses                             127      125       -2     
Files with missing lines Coverage Δ
R/add_common_aes.R 88.81% <100.00%> (+0.07%) ⬆️
R/ceac.R 90.90% <100.00%> (+0.43%) ⬆️
R/evpi.R 96.15% <100.00%> (ø)
R/evppi.R 95.45% <100.00%> (ø)
R/evsi.R 87.69% <100.00%> (ø)
R/exp_loss.R 100.00% <100.00%> (ø)
R/icers.R 97.78% <100.00%> (ø)
R/owsa.R 93.05% <100.00%> (+0.13%) ⬆️
R/twsa.R 93.44% <100.00%> (+0.10%) ⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

The minimum-dependency CI job could not install ggplot2@3.5.0 with lifecycle@1.0.0.
Current dplyr needs lifecycle (>= 1.0.5) and ggplot2 3.5.0 needs lifecycle (> 1.0.1), so
any lower pin makes the minimum-dependency environment unsolvable. dampack only uses
deprecate_soft(), deprecated() and is_present(), which predate lifecycle 1.0.
@feralaes
feralaes merged commit 6afb4a7 into 209-reference-strategy-core Nov 14, 2026
12 checks passed
@feralaes
feralaes deleted the 214-api-harmonize branch November 14, 2026 01:52
feralaes added a commit that referenced this pull request Nov 14, 2026
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.
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