Skip to content

Keep calculate_icers() fully incremental; add calculate_cers_ref() for comparisons with a reference strategy (#209) - #261

Merged
feralaes merged 20 commits into
209-reference-strategy-corefrom
cers-ref
Nov 18, 2026
Merged

feralaes merged 20 commits into
209-reference-strategy-corefrom
cers-ref

Conversation

@feralaes

Copy link
Copy Markdown
Collaborator

This PR implements what we agreed at the DARTH meeting on Nov 17. It goes into the #227 branch, so #227 then carries the revised design.

What changes

calculate_icers() stays fully incremental, with no reference strategy.

  • ref_str is removed from calculate_icers(), print.icers(), plot.icers(), calculate_icers_psa() and summary.psa().
  • summary.psa() is back to its main version.
  • Kept: wtp/nhb, which add the strategies' own NMB/NHB (Add NMB and iNBM to calc_icer #200), and currency.

plot.icers(incremental = TRUE) plots the incremental cost-effectiveness plane. The first non-dominated strategy (the least costly strategy on the frontier) sits at (0, 0). The optional wtp line goes through that strategy.

New: calculate_cers_ref() and calculate_cers_ref_psa(), which compare every strategy with a reference strategy chosen by the user. Columns:

  • Inc_Cost and Inc_Effect versus the reference.
  • CER, the cost-effectiveness ratio versus the reference.
  • Status: Reference / Dominant / Dominated / More costly, more effective / Less costly, less effective / Equivalent.
  • With wtp: NMB and Inc_NMB (nhb = TRUE also adds NHB and Inc_NHB).

The reference comes first, then the other strategies by increasing cost. This answers the row-order question from the review.

The PSA version adds, with uncertainty = TRUE:

  • 95% intervals for the sample-by-sample differences.
  • Prop_NE/Prop_SE/Prop_SW/Prop_NW: the share of samples in each quadrant.
  • Prop_CE (with wtp): the share of samples that are cost-effective versus the reference.

print() and plot() methods for the new cers_ref class:

  • The plot is the "star": the reference sits at the origin, with a segment to each strategy.
    • Segments are drawn by default and left out when there are more than 20 strategies; lines = overrides this.
    • Points are colored by status.
    • An optional WTP line goes through the origin.
  • The printed table says it is not a fully incremental analysis.

Guidelines cited in the help page and in a new section of vignette("basic_cea"):

  • NICE PMG36: "Pairwise comparisons may be presented when relevant and justified…"
  • CDA-AMC, 4th ed.
  • Zorginstituut Nederland, 2024.

The vignette uses the HIV screening example to show why the reference comparison complements the incremental analysis rather than replacing it. Annual screening has a CER of $80,941/QALY versus the status quo, so it looks cost-effective at $100,000/QALY. Yet it is strongly dominated by screening every 3 years.

Kept from the earlier work:

Also updated: NEWS, a README bullet, and a new pkgdown reference group, "Comparisons with a reference strategy".

Checks

  • R CMD check --as-cran: 0 errors, 0 warnings. The only NOTE is a hidden .git file, which comes from running the check in a git worktree.
  • lintr::lint_package(): 0 lints.
  • New tests in tests/testthat/test_cers_ref.R cover:
    • hand-calculated values for each quadrant;
    • the row order;
    • a dominated reference and a most-expensive reference;
    • NMB/NHB;
    • one and two strategies, and names with spaces;
    • PSA quadrant shares and intervals;
    • that calculate_icers(), calculate_icers_psa() and summary.psa() no longer take ref_str.
  • test_reference_plots.R covers the incremental plot.icers() and the star plot.

Follow-up

#252 (examples) adds examples that use the removed ref_str arguments. I'll update it once this is merged.

🤖 Generated with Claude Code

feralaes and others added 19 commits November 13, 2026 17:01
… DESCRIPTION

DESCRIPTION declares R (>= 4.1.0), but no job ran R 4.1: oldrel-1 and the min-deps job
use current R. The min-deps job now has a matrix entry that reads the R bound from
DESCRIPTION and checks the package on that version with the minimum package versions.
…or repositories

R 4.1 on ubuntu-latest (Ubuntu 26) failed while resolving dependencies: the Bioconductor
3.14 repositories pak adds for R 4.1 are unreachable, and the package manager has no R 4.1
binaries for Ubuntu 26. dampack uses no Bioconductor packages.
The new minimum-R CI job could not install the dependencies on R 4.1.0:
'triangle: Needs R >= 4.1.3'. Raise the declared bound to what installs from CRAN,
and let the job confirm that nothing else needs a newer R.
R CMD check warns 'Dependence on R version 4.1.3 not with patchlevel 0', which CRAN
does not accept. On R 4.1.3 every other check passed.
CI: test the minimum R version declared in DESCRIPTION
…s in vignettes (#219)

R CMD check reported an installed size of 6.0 MB (data 3.5 MB, doc 2.0 MB). CRAN flags
packages over 5 MB.

- LazyDataCompression: xz. The same PSA samples are stored three times in the lazy-load
  database (cancer_psa_data, and the superseded example_psa and example_psa_obj rebuilt from
  it at install), so the compression matters: data 3.5 -> 2.8 MB. Loaded objects identical.
- Vignette figures use ragg_png (ragg in Suggests; falls back to png without it): same
  resolution, about 22% smaller PNGs. doc 2.0 -> 1.6 MB.

Installed size 6.0 -> 4.8 MB ("checking installed package size ... OK"); tarball 2.83 -> 2.51 MB.
Bring the installed size under CRAN's 5 MB limit: xz lazy data, ragg vignette figures (#219)
…e and links (#217)

- README.md is now generated from README.Rmd (devtools::build_readme()); README.Rmd is
  build-ignored, README.md and its one figure (man/figures/README-ceac-1.png, ragg, 48 KB)
  are kept for GitHub, CRAN and pkgdown.
- New sections: why dampack (statement of need), what it does, a runnable example with
  cancer_psa_data (calculate_icers_psa() output and a CEAC figure), learn more (website,
  reference, articles in reading order, news), citation, getting help and contributing
  (issues, CONTRIBUTING, code of conduct). CRAN status badge added.
- Kept: installation (now with remotes), the macOS locale tip, funding, the DARTH team.
- The team section listed David Garibay as CRAN maintainer; Fernando is maintainer since #245.
README.Rmd: statement of need, feature overview, minimal example and links (#217)
With log_y = TRUE (the default), the y breaks came from number_ticks(), which spaces
them evenly. On a log axis they bunched up at the top and left the lower curves
without labels. Use scales::breaks_log(n_y_ticks) unless ybreaks is given.
…019 paper

- 'What it does' names CEACs with the CEAF and expected loss curves (ELCs), and cites
  Alarid-Escudero et al. (2019), doi:10.1016/j.jval.2019.02.008.
- The example shows, with numbers computed from cancer_psa_data, that the strategy most
  likely to be cost-effective (Surgery at $50,000/QALY) is not the optimal one (Chemo),
  which is why the CEAC needs its frontier.
- New 'Expected loss curves' subsection and figure: foregone benefit, optimal strategy and
  EVPI in one figure. A hidden check confirms the optimal strategy's expected loss equals
  calc_evpi() at that threshold.
- The full reference is listed under Citation.
plot.exp_loss(): readable labels on the log-scale y axis
README: the acceptability frontier and expected loss curves (Alarid-Escudero et al., 2019)
…rom dampack output

- Sticker (option I): CEACs with the CEAF above the expected loss curves of cancer_psa_data,
  on one WTP axis; both frontiers switch from Radio to Chemo at $40,000 (dotted line).
  viridis option D colours (col = "access"), JetBrains Mono wordmark.
- man/figures/logo.png (240 x 278, 17 KB) in the README header and on the pkgdown home page.
- pkgdown/favicon/: favicon.svg/.ico/96px, apple-touch-icon, web manifest, from an ELC-only
  icon without text that stays legible at 16-32 px.
- logo/: make_hex.R (SVGs from ceac() and calc_exp_loss()), render.sh (PNGs, favicons),
  README.md, the SVGs and a 600 dpi print PNG. logo/ is build-ignored.
Add the dampack hex logo and site favicons
…tion EVSI

- 'What it does' credits the methods: EVPPI from regression metamodels (Strong et al. 2014;
  Jalal and Alarid-Escudero 2018) and EVSI with the Gaussian approximation approach (Jalal and
  Alarid-Escudero 2018, doi:10.1177/0272989X17715627), both from the existing PSA sample.
- New 'Value of research: EVPPI and EVSI from one PSA' section with a runnable example on
  cancer_psa_data (EVPI, EVPPI of two failure probabilities, EVSI by study size), with numbers
  computed inline and a hidden check that EVSI rises with n and EVSI < EVPPI < EVPI.
- The Gaussian approximation paper is listed under Citation.
README: regression-metamodel EVPPI and Gaussian-approximation EVSI (Jalal and Alarid-Escudero, 2018)
…r comparisons with a reference

As agreed at the DARTH meeting of Nov 17, 2026:
- Remove ref_str from calculate_icers(), print.icers(), plot.icers(),
  calculate_icers_psa() and summary.psa(). They keep wtp/nhb (NMB, NHB)
  and currency.
- plot.icers(incremental = TRUE) puts the first non-dominated strategy
  at the origin.
- New calculate_cers_ref() and calculate_cers_ref_psa(), with print()
  and plot() methods, compare every strategy with a reference strategy,
  citing the NICE, CDA-AMC and Zorginstituut Nederland guidelines.
- basic_cea vignette section, README bullet, pkgdown reference group.

Co-Authored-By: Claude <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.03922% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.92%. Comparing base (6afb4a7) to head (918da90).

Files with missing lines Patch % Lines
R/cers_ref.R 97.64% 4 Missing ⚠️
Additional details and impacted files
@@                       Coverage Diff                       @@
##           209-reference-strategy-core     #261      +/-   ##
===============================================================
+ Coverage                        93.83%   93.92%   +0.08%     
===============================================================
  Files                               18       19       +1     
  Lines                             2028     2073      +45     
===============================================================
+ Hits                              1903     1947      +44     
- Misses                             125      126       +1     
Files with missing lines Coverage Δ
R/exp_loss.R 100.00% <100.00%> (ø)
R/icers.R 97.00% <100.00%> (-0.78%) ⬇️
R/psa.R 95.85% <ø> (-1.10%) ⬇️
R/cers_ref.R 97.64% <97.64%> (ø)

... and 6 files with indirect coverage changes

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

@feralaes
feralaes requested review from krijkamp and mbkauf November 17, 2026 21:51
@mbkauf

mbkauf commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

In the future, can PR be more focused on the specific issue? This PR has far too many things going on

@mbkauf mbkauf left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Move check_ref_str() from icers.R to cers_ref.R

Co-Authored-By: Claude <noreply@anthropic.com>
@feralaes

Copy link
Copy Markdown
Collaborator Author

Thanks, @mbkauf. check_ref_str() is now in cers_ref.R (918da90). Fair point on scope. This one bundled the removal of ref_str from calculate_icers() with the new calculate_cers_ref() because the second replaces the first, but the vignette and README parts could have been a separate PR. Future PRs will each be limited to one issue.

@feralaes
feralaes merged commit 070f5b3 into 209-reference-strategy-core Nov 18, 2026
13 checks passed
@feralaes
feralaes deleted the cers-ref branch November 18, 2026 19:08
feralaes added a commit that referenced this pull request Nov 18, 2026
…to 212-examples; drop the ref_str examples

Co-Authored-By: Claude <noreply@anthropic.com>
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.

2 participants