Add functionality to sort & filter ard_stack_hierarchical() results

[edelarua]

What changes are proposed in this pull request?

• Added the sort and filter arguments to ard_stack_hierarchical() to support sorting & filtering of ARD results. (Do we need functions for working with our hierarchical results? #301)

Closes #301

---

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')"

[github-actions]

Unit Tests Summary

  1 files  205 suites   58s ⏱️
202 tests 202 ✅ 0 💤 0 ❌
515 runs  515 ✅ 0 💤 0 ❌

Results for commit c387697.

♻️ This comment has been updated with latest results.

[github-actions]

Unit Test Performance Difference

Test Suite	$Status$	Time on main	$±Time$	$±Tests$	$±Skipped$	$±Failures$	$±Errors$
filter_ard_hierarchical	👶		$+0.00$	$+3$	$0$	$0$	$0$
sort_ard_hierarchical	👶		$+0.00$	$+3$	$0$	$0$	$0$

Additional test case details

Test Suite	$Status$	Time on main	$±Time$	Test Case
ard_continuous	💔	$0.40$	$+2.01$	ard_continuous_works
filter_ard_hierarchical	👶		$+0.00$	filter_ard_hierarchical_error_messaging_works
filter_ard_hierarchical	👶		$+0.01$	filter_ard_hierarchical_returns_only_summary_rows_when_all_rows_filtered_out
filter_ard_hierarchical	👶		$+0.23$	filter_ard_hierarchical_works
filter_ard_hierarchical	👶		$+0.00$	filter_ard_hierarchical_works_when_some_variables_not_included_in_x
filter_ard_hierarchical	👶		$+0.01$	filter_ard_hierarchical_works_with_non_standard_filters
filter_ard_hierarchical	👶		$+0.00$	filter_ard_hierarchical_works_with_only_one_variable_in_x
filter_ard_hierarchical	👶		$+0.00$	filter_ard_hierarchical_works_with_overall_data
sort_ard_hierarchical	👶		$+0.00$	sort_ard_hierarchical_error_messaging_works
sort_ard_hierarchical	👶		$+0.00$	sort_ard_hierarchical_sort_alphanumeric_works
sort_ard_hierarchical	👶		$+0.00$	sort_ard_hierarchical_sort_descending_works
sort_ard_hierarchical	👶		$+1.81$	sort_ard_hierarchical_works
sort_ard_hierarchical	👶		$+0.00$	sort_ard_hierarchical_works_when_some_variables_not_included_in_x
sort_ard_hierarchical	👶		$+0.00$	sort_ard_hierarchical_works_when_sorting_using_p_instead_of_n
sort_ard_hierarchical	👶		$+0.01$	sort_ard_hierarchical_works_when_there_is_no_overall_row_in_x
sort_ard_hierarchical	👶		$+0.00$	sort_ard_hierarchical_works_with_only_one_variable_in_x
sort_ard_hierarchical	👶		$+0.00$	sort_ard_hierarchical_works_with_overall_data

Results for commit 36571b8

♻️ This comment has been updated with latest results.

[github-actions]

Code Coverage Summary

Filename                       Stmts    Miss  Cover    Missing
---------------------------  -------  ------  -------  -------------------------------
R/add_calculated_row.R            46       0  100.00%
R/apply_fmt_fn.R                 116       0  100.00%
R/ard_attributes.R                46       1  97.83%   57
R/ard_categorical.R              393      10  97.46%   248, 461-465, 472-473, 650, 684
R/ard_complex.R                   36       1  97.22%   82
R/ard_continuous.R               187       3  98.40%   208-209, 308
R/ard_dichotomous.R               80       1  98.75%   62
R/ard_hierarchical.R              71       0  100.00%
R/ard_missing.R                   58       1  98.28%   50
R/ard_pairwise.R                  46       0  100.00%
R/ard_stack_hierarchical.R       233       1  99.57%   452
R/ard_stack.R                     90       1  98.89%   117
R/ard_strata.R                    33       0  100.00%
R/ard_total_n.R                   10       0  100.00%
R/as_card_fn.R                     8       0  100.00%
R/as_card.R                        5       0  100.00%
R/as_nested_list.R                41       0  100.00%
R/bind_ard.R                      47      11  76.60%   74-85
R/check_ard_structure.R           39       6  84.62%   31, 55-59
R/default_stat_labels.R           20       0  100.00%
R/deprecated.R                     6       6  0.00%    15-21
R/eval_capture_conditions.R       30       0  100.00%
R/filter_ard_hierarchical.R       52       0  100.00%
R/get_ard_statistics.R            16       0  100.00%
R/mock.R                         137       2  98.54%   116, 244
R/nest_for_ard.R                  71       1  98.59%   60
R/print_ard_conditions.R          83       0  100.00%
R/print.R                         80       0  100.00%
R/process_selectors.R            126       1  99.21%   337
R/rename_ard_groups.R             60       0  100.00%
R/replace_null_statistic.R        11       0  100.00%
R/round5.R                         1       0  100.00%
R/selectors.R                     23       0  100.00%
R/shift_ard_columns.R            102       1  99.02%   185
R/shuffle_ard.R                  129       0  100.00%
R/sort_ard_hierarchical.R        130       5  96.15%   186-190
R/summary_functions.R             25       1  96.00%   59
R/tidy_ard_order.R                34       0  100.00%
R/tidy_as_ard.R                   40       0  100.00%
R/update_ard.R                    53       0  100.00%
R/utils.R                         24       0  100.00%
TOTAL                           2838      53  98.13%

Diff against main

Filename                       Stmts    Miss  Cover
---------------------------  -------  ------  --------
R/ard_stack_hierarchical.R        +1       0  +0.00%
R/filter_ard_hierarchical.R      +52       0  +100.00%
R/sort_ard_hierarchical.R       +130      +5  +96.15%
TOTAL                           +183      +5  -0.06%

Results for commit: c387697

Minimum allowed coverage is 80%

♻️ This comment has been updated with latest results

[ddsjoberg]

Hi @edelarua , is this ready for review? Thanks!

[edelarua]

Hi @edelarua , is this ready for review? Thanks!

Hi @ddsjoberg, yes I think this should be ready now! I've also updated the corresponding PR in gtsummary (ddsjoberg/gtsummary#2097) to work with the updated version

[ddsjoberg]

@edelarua this API for the filter function looks amazing!! 🤩

I haven't had a chance to review the sorting function, but have some initial comments on filtering. Thank you for this amazing work!

[ddsjoberg]

"For each entry that does not meet the filtering requirement, all statistics corresponding to that entry will be removed from the ARD."

I think this would be more clear if it was something like, "if any of the AEs in the by groups meet the criteria, all AEs within that group are retained" ? What do you think? Also, for this details section, maybe if we started with an example of AE+SOC, it would be clearer to talk about?