ard_compare draft #437 by malanbos · Pull Request #527 · insightsengineering/cards

malanbos · 2025-12-01T15:24:30Z

What changes are proposed in this pull request?

New function to compare two ARDs: ard_compare

Comes with top-level ard_compare function, as well as a script with ard_compare_helpers.R, and check_environment.R to modularize it.

Pre-review Checklist (if item does not apply, mark is as complete)

All GitHub Action workflows pass with a ✅
PR branch has pulled the most recent updates from master branch: usethis::pr_merge_main()
If a bug was fixed, a unit test was added.
Code coverage is suitable for any new functions/features (generally, 100% coverage for new code): devtools::test_coverage()
Request a reviewer

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

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()

When the branch is ready to be merged:

Update NEWS.md with the changes from this pull request under the heading "# cards (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).
All GitHub Action workflows pass with a ✅
Approve Pull Request
Merge the PR. Please use "Squash and merge" or "Rebase and merge".

Optional Reverse Dependency Checks:

Install checked with pak::pak("Genentech/checked") or pak::pak("checked")

# Check dev versions of `cardx`, `gtsummary`, and `tfrmt` which are in the `ddsjoberg` R Universe
Rscript -e "options(checked.check_envvars = c(NOT_CRAN = TRUE)); checked::check_rev_deps(path = '.', n = parallel::detectCores() - 2L, repos = c('https://ddsjoberg.r-universe.dev', 'https://cloud.r-project.org'))"

# Check CRAN reverse dependencies but run tests skipped on CRAN
Rscript -e "options(checked.check_envvars = c(NOT_CRAN = TRUE)); checked::check_rev_deps(path = '.', n = parallel::detectCores() - 2, repos = 'https://cloud.r-project.org')"

# Check CRAN reverse dependencies in a CRAN-like environment
Rscript -e "options(checked.check_envvars = c(NOT_CRAN = FALSE), checked.check_build_args = '--as-cran'); checked::check_rev_deps(path = '.', n = parallel::detectCores() - 2, repos = 'https://cloud.r-project.org')"

…overlapping key values, enabling mismatches to surface through the full join comparison.

ddsjoberg

Thank you @malanbos for this!

For now, let's skip env handling. I think it's more complex than we need. We can revisit in the future. Let me know if you'd like to discuss

ddsjoberg · 2025-12-11T00:26:02Z

R/ard_compare.R

+#'
+#' ard_compare(ard_base, ard_modified)$stat
+#'
+ard_compare <- function(x, y, key_columns = NULL) {


All of our functions that begin with ard_*() create new ARDs. Let's name the function compare_ard().

Renamed, and the ard_compare file is also moved to compare_ard() (as well as the test file)

ddsjoberg · 2025-12-11T00:28:14Z

R/ard_compare.R

+#'
+#' ard_compare(ard_base, ard_modified)$stat
+#'
+ard_compare <- function(x, y, key_columns = NULL) {


Let's make the default value keys = c(all_ard_groups(), all_ard_variables(), any_of(c("variable", "variable_level", "stat_name"))).

This is done as a default value in the argument

ddsjoberg · 2025-12-11T00:29:31Z

R/ard_compare.R

+#'
+#' ard_compare(ard_base, ard_modified)$stat
+#'
+ard_compare <- function(x, y, key_columns = NULL) {


Let's add an argument of the columns to compare, compare = any_of(c("stat_label", "stat", "stat_fmt")).

(Is there anything else we should compare by default?)

these 3 are added, think it's a good default

ddsjoberg · 2025-12-11T00:30:03Z

R/ard_compare.R

+  check_class(x, cls = "card")
+  check_class(y, cls = "card")
+
+  .validate_environment_metadata(x, y, call = get_cli_abort_call())


Let's remove the env checking for now. It's quite complicated.

Will remove, yes

All env checking is removed

ddsjoberg · 2025-12-11T00:37:04Z

R/ard_compare.R

+
+  .validate_environment_metadata(x, y, call = get_cli_abort_call())
+
+  primary_x <-


Here we can evaluate the keys and compare columns with

keys <- .process_keys_arg(x, y, keys = {{ keys }}) compare <- .process_compare_arg(x, y, compare = {{ compare }}) # outside the function we define these functions .process_keys_arg <- function(x, y, keys) { keys <- intersect(cards_select({{ keys }}, data = x), cards_select({{ keys }}, data = y)) .check_not_empty(keys) cli::cli_inform("The comparison {.arg keys} are {.emph {.val {keys}}}.") keys } .process_compare_arg <- function(x, y, compare) { # add checks and return evaluated compare vector... } .check_not_empty <- function(x, arg_name = rlang::caller_arg(x)) { if (rlang::is_empty()) { cli::cli_abort("The {.arg {arg_name}} argument cannot be empty.") } invisible(x) }

These were added. Please just check the "add checks and return evaluated compare vector" part if that's fine.

ddsjoberg · 2025-12-11T04:01:58Z

R/ard_compare.R

+  fmt_column <- if ("fmt_fun" %in% names(x) || "fmt_fun" %in% names(y)) {
+    "fmt_fun"
+  } else if ("fmt_fn" %in% names(x) || "fmt_fn" %in% names(y)) {
+    "fmt_fn"
+  } else {
+    "fmt_fun"
+  }


Let's just use the columns provided in the compare argument to assess which comparisons to make. We can compare all columns in the same way.

ddsjoberg · 2025-12-11T04:10:59Z

R/ard_compare.R

+    y_selected <- .ensure_column(y_selected, column)
+  }
+
+  # .check_rows_not_in_x_y(x_selected, y_selected, key_columns)


Here we can initialize an empty list of results.

results <- rlang::rep_named(c("rows_in_x_not_y", "rows_in_y_not_x"), list(NULL)) results[["compare"]] <- rlang::rep_named(compare, list(NULL))

In this example the "compare" element will also be a named list. The names are the columns that we compare.

We could then follow this up with calls to functions that will populate these parts of the list, e.g.

results[["rows_in_x_not_y"]] <- .compare_rows(x, y) # returns the results of the anti join of x and y on the key columns results[["rows_in_y_not_x"]] <- .compare_rows(y, x) # same as above, but reversed results[["compare"]] <- .compare_columns(x, y, compare) # loop through the columns we will compare and return a named list of data frames where each data frame contains the rows that are not equal between x and y. The data frame will have the key columns and the two columns compared (from x and y).

ddsjoberg · 2025-12-11T04:17:55Z

R/ard_compare.R

+
+  names(mismatch_list) <- names(comparison_targets)
+
+  mismatch_list


Lastly, the function will return the results object, and add a class onto this list.

After we get this settled, we will write a print method for class to make it nice.

Added with structure(results, class = c("ard_comparison", class(results)))

stat_name, stat_list, stat_fmt

move all helper functions to compare_are_helpers

R/compare_ard.R

Melkiades · 2026-01-26T17:35:22Z

R/compare_ard.R

+#'     (based on key columns)
+#'   - `rows_in_y_not_x`: data frame of rows present in `y` but not in `x`
+#'     (based on key columns)
+#'   - `compare`: a named list where each element is a data frame containing


maybe would call diff?

Do you mean rename the "compare" to "diff"? That's fine with me yes.

R/compare_ard.R

Melkiades · 2026-01-26T17:56:47Z

R/compare_ard.R

+#'
+#' compare_ard(ard_base, ard_modified)$compare$stat
+#'
+compare_ard <- function(x,


I really like the construction and concept of the main function. The helper functions are a bit of a Dedalus but I will take a closer look during the week ;)

Sure! And I learnt a new word here :)

Melkiades · 2026-01-26T18:03:52Z

R/compare_ard.R

+#' @examples
+#' ard_base <- ard_summary(ADSL, variables = AGE)
+#' ard_modified <- ard_summary(dplyr::mutate(ADSL, AGE = AGE + 1), variables = AGE)
+#'
+#' compare_ard(ard_base, ard_modified)$compare$stat


maybe I would make the more examples more complex (so to show groups etc)

I'll add some more complex ones.

Melkiades · 2026-01-26T18:17:29Z

R/compare_ard_helpers.R

+  # perform inner join to compare only matching rows
+  comparison <- dplyr::inner_join(
+    x_selected,
+    y_selected,
+    by = keys,
+    suffix = c(".x", ".y")
+  )


for some reason this does not drop the "card" class producing a contracted output (not showing some columns). Should we keep this behavior or should we drop the card class? maybe defining card_diff new class?

$stat {cards} data frame: 6 x 4 variable stat_name 1 AGE mean 2 AGE median 3 AGE p25 4 AGE p75 5 AGE min 6 AGE max ℹ 2 more variables: stat.x, stat.y

Good point, I accepted the below suggestion

R/compare_ard_helpers.R

Melkiades

Amazing work!! I really like it, output is very intuitive and efficient in showing differences. I added a minor comment on the final compare output that is hiding columns and I would add more examples but for me the code is almost complete. I was wondering if we could need a +- diff like testthat snapshots as an optional diff output... Dont know, for now it is pretty easy to understand the output.

I still need to test this with more complex differences (e.g. I wonder if you solve the fmt before getting into the comparison or not - we should if not), but I wait to try the additional examples ;)

Co-authored-by: Davide Garolini <dgarolini@gmail.com> Signed-off-by: Malan <64360731+malanbos@users.noreply.github.com>

Melkiades · 2026-02-09T16:30:54Z

R/compare_ard_helpers.R

+  matches <- mapply(
+    identical,


as discussed -> all.equals

malanbos added 5 commits November 11, 2025 23:46

initial ard_compare()

4a6fec3

remove unneeded check

214de0b

split out checking of environments for ard_compare

e836002

split out functions to separate helper file

ce571cb

Allowed ard_compare() to proceed without aborting when ARDs have non-…

e73c917

…overlapping key values, enabling mismatches to surface through the full join comparison.

malanbos requested a review from ddsjoberg December 1, 2025 15:24

qualify utils::head

ea53426

ddsjoberg requested changes Dec 11, 2025

View reviewed changes

ddsjoberg and others added 6 commits December 12, 2025 15:20

Merge branch 'main' into main

654f965

rename

26d1f1e

stat_name, stat_list, stat_fmt

Merge branch 'main' into main

964a16c

[skip actions] Bump version to 0.7.1.9005

1eaf3c0

rename ard_compare to compare_ard

fc432de

move all helper functions to compare_are_helpers

[skip actions] Bump version to 0.7.1.9006

cfd95e9

ddsjoberg requested review from Melkiades and ddsjoberg January 26, 2026 16:09

Melkiades reviewed Jan 26, 2026

View reviewed changes

R/compare_ard.R Show resolved Hide resolved

Melkiades reviewed Jan 26, 2026

View reviewed changes

R/compare_ard.R Outdated Show resolved Hide resolved

Melkiades reviewed Jan 26, 2026

View reviewed changes

R/compare_ard_helpers.R Outdated Show resolved Hide resolved

Melkiades reviewed Jan 26, 2026

View reviewed changes

malanbos and others added 6 commits February 9, 2026 13:51

Update R/compare_ard.R

968fd8d

Co-authored-by: Davide Garolini <dgarolini@gmail.com> Signed-off-by: Malan <64360731+malanbos@users.noreply.github.com>

[skip actions] Bump version to 0.7.1.9007

95c7302

Update R/compare_ard_helpers.R

ad07a7f

Co-authored-by: Davide Garolini <dgarolini@gmail.com> Signed-off-by: Malan <64360731+malanbos@users.noreply.github.com>

[skip actions] Bump version to 0.7.1.9008

d950774

Update R/compare_ard.R

b346f53

Co-authored-by: Davide Garolini <dgarolini@gmail.com> Signed-off-by: Malan <64360731+malanbos@users.noreply.github.com>

[skip actions] Bump version to 0.7.1.9009

7c8aebc

Melkiades reviewed Feb 9, 2026

View reviewed changes

R/compare_ard_helpers.R

Comment on lines +466 to +467

matches <- mapply(

identical,

Copy link

Contributor

Melkiades Feb 9, 2026

Choose a reason for hiding this comment

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

as discussed -> all.equals


		.validate_environment_metadata(x, y, call = get_cli_abort_call())

		primary_x <-


		names(mismatch_list) <- names(comparison_targets)

		mismatch_list

Uh oh!

Conversation

malanbos commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ddsjoberg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Melkiades left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

malanbos commented Dec 1, 2025 •

edited

Loading