Add levels argument to add_difference() (tbl_summary + tbl_svysummary) to compare two groups (#2151)

[ddsjoberg]

What changes are proposed in this pull request?

Added a levels argument to add_difference.tbl_summary() and add_difference.tbl_svysummary() to select which two by groups to compare. This makes add_difference() usable when by= has more than two levels, and lets users flip the direction of the difference for two-level by variables. (#2151)

The difference is computed as levels[1] minus levels[2]. When supplied, the data is subset to the two selected levels with the by factor re-leveled, while all summary statistic columns are retained. A footnote names the compared pair and direction.

# data frame
trial |>
  tbl_summary(by = grade, include = c(age, marker), missing = "no") |>
  add_difference(levels = c("I", "III"))   # difference = I - III

# survey design
survey::svydesign(~1, data = trial, weights = ~1) |>
  tbl_svysummary(by = grade, include = c(age, marker), missing = "no") |>
  add_difference(levels = c("I", "III"))   # difference = I - III

• New levels argument (default NULL), a length-2 vector of by-level values matched by value.
• Required when by has 3+ levels; the previous "exactly two levels" error now points users to levels.
• Optional for two-level by, where reversing the pair flips the sign.
• Validation: length-2, distinct, non-missing, and both values must be existing by levels (error lists valid levels).
• Both methods share one private helper (.process_difference_levels()) for validation and subsetting. The helper is survey-aware: for tbl_svysummary() it subsets and re-levels the survey.design (via survey::subset()), restoring column labels that subsetting strips.

If there is an GitHub issue associated with this pull request, please provide link.

Closes #2151

---

Reviewer Checklist (if item does not apply, mark is as complete)

• PR branch has pulled the most recent updates from main branch.
• If a bug was fixed, a unit test was added.
• Run pkgdown::build_site(). Check the R console for errors, and review the rendered website.
• Code coverage is suitable for any new functions/features: devtools::test_coverage()
• usethis::use_spell_check() runs with no spelling errors in documentation
• All GitHub Action workflows pass with a ✅

When the branch is ready to be merged into master:

• Update NEWS.md with the changes from this pull request under the heading "# gtsummary (development version)". If there is an issue associated with the pull request, reference it in parentheses at the end update (see NEWS.md for examples).
• Increment the version number using usethis::use_version(which = "dev")
• Run usethis::use_spell_check() again
• Approve Pull Request
• Merge the PR. Please use "Squash and merge".

[ddsjoberg]

Hi @larmarange , hope you've been well. Do you want to take a look at this? You were interested in this functionality to reverse the difference calculation for your before-after tables.

[larmarange]

Thanks a lot @ddsjoberg

Everything looks right to me

[ddsjoberg]

Thank you @larmarange !