Present the CEA against a user-selected reference strategy (`ref_str`)

Start with calculate_icers() in R/icers.R and the existing plot.psa(ref_str) implementation in R/psa.R; review the listed dependencies (#208, #183, and #178) before changing these entry points. Add tests for the hand-calculated cases, default-output snapshot, and strategy-count edge cases described in the acceptance criteria. Done means reference comparisons and optional net benefits work across the listed functions while default sequential results remain unchanged, and basic_cea documents the feature.

Suggested owners: Fernando Alarid-Escudero and Eline Krijkamp (methods), with Matthew Kaufmann (who built plot.psa(ref_str)) · Plan: Phase 3, steps 1–6

Goal

Let users report results against a fixed comparator, e.g. "Standard of care", alongside the default frontier-based analysis. Many HTA reports and journals ask for this.

The sequential frontier ICERs stay the default and remain the decision-relevant result. When ref_str = NULL, output is identical to v1.0.x.

History:

• #72 (closed 2019) removed an earlier ref_strat argument from calculate_icers(). The roxygen still describes it: R/icers.R:17-18, "With the default (NULL), there is no reference strategy…". That stale text is also part of #178.
• Why the 2019 version was removed matters for this design. It (commit e7eef8e, removed in 6649b66) moved the reference strategy to the top of the cost-sorted table before the dominance loop, and relabeled its status as "ref". The dominance loop assumes strategies are sorted by ascending cost. So whenever the reference was not the cheapest strategy, it could mislabel dominated and extendedly dominated strategies. The new design avoids this by never changing the frontier calculation: the comparisons against the reference are separate columns computed after the frontier.
• #188 (closed Sep 2026) added ref_str to plot.psa() only.

Depends on: #208, #183, #178. Delivers: #200 (NMB/iNMB) and #202 (WTP line).

Scope

1. calculate_icers(cost, effect, strategies, ref_str = NULL, wtp = NULL, nhb = FALSE, currency = "$") (R/icers.R:59):
   • Keep Status, Inc_Cost, Inc_Effect and ICER unchanged. With the default ref_str = NULL and wtp = NULL, the output is identical to v1.0.x.
   • Reference columns are added only when ref_str is given; otherwise they are irrelevant and left out. Check that ref_str is one of strategies.
     • Inc_Cost_ref, Inc_Effect_ref: cost and effect of each strategy minus those of the reference.
     • ICER_ref: numeric. NA where a ratio is not meaningful: for the reference itself, and for strategies that dominate or are dominated by the reference.
     • Status_ref: a categorical description of each strategy versus the reference. Proposed labels:
       • "Reference"
       • "Dominant": less costly and at least as effective
       • "Dominated": more costly and no more effective
       • "More costly, more effective"
       • "Less costly, less effective"
   • Net benefit when wtp is given:
     • NMB by default (most commonly used), plus iNMB_ref when ref_str is set. This closes #200.
     • NHB (and iNHB_ref with ref_str) only as an option, for example nhb = TRUE, since it is less commonly used.
   • Store attr(x, "ref_str"), attr(x, "wtp") and the currency on the object.
2. print.icers(x, ref = c("sequential", "reference", "both"), ...) (R/icers.R:411): uses the object's currency and effect_units.
3. plot.icers(x, ref_str = , wtp = ): incremental CE plane with the origin at the reference, and an optional WTP line (#202).
4. calculate_icers_psa(psa, ref_str = , wtp = ) and summary.psa(psa, ref_str = ): mean incremental cost, effect and iNMB versus the reference, with uncertainty intervals.
5. plot.psa(ref_str = ) (R/psa.R:150-290):
   • Fix the 2-strategy bug at R/psa.R:244: df[, !(names(df) %in% ref_str)] drops to a vector without drop = FALSE. Reproduced: plot(psa_2strat, ref_str = "A") warns "STATS is longer than the extent of 'dim(x)[MARGIN]'" and the incremental values are wrong.
   • Add the optional WTP line (#202) and a quadrant summary.
6. One internal check_ref_str() helper and a shared @param ref_str roxygen template, used through @inheritParams.

Decided (Eline Krijkamp, Nov 12, 2026):

• Reference columns appear only when ref_str is given.
• ICER_ref stays numeric, with NA where it is not meaningful.
• A categorical Status_ref column describes each strategy versus the reference.
• With wtp, NMB/iNMB_ref by default; NHB/iNHB_ref only as an option.

Also confirmed (DARTH group, Nov 12, 2026):

• The Status_ref labels above.
• The NHB option is named nhb = TRUE.
• print.icers() shows the sequential table by default when ref_str is set, with ref = "reference" or "both" to show the comparison.

Acceptance

• Without ref_str, no reference columns are present; without wtp, no net-benefit columns are present.
• Hand-calculated values match for hund_strat and for a 3-strategy toy case in three situations: reference on the frontier, reference dominated, and reference the most expensive strategy.
• ref_str = NULL output is identical to a v1.0.x golden snapshot.
• 2-strategy and single-strategy edge cases pass.
• Names with spaces work (#208).
• basic_cea gets a section "Presenting results against a reference strategy" with references.