Add ard_event_rates()

[edelarua]

What changes are proposed in this pull request?

• Added function ard_event_rates() to calculate event rates. (Add ARD function for counting patients #240)

Closes #240

---

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.
• If a new ard_*() function was added, it passes the ARD structural checks from cards::check_ard_structure().
• If a new ard_*() function was added, set_cli_abort_call() has been set.
• If a new ard_*() function was added and it depends on another package (such as, broom), is_pkg_installed("broom") has been set in the function call and the following added to the roxygen comments: @examplesIf do.call(asNamespace("cardx")$is_pkg_installed, list(pkg = "broom""))
• Code coverage is suitable for any new functions/features (generally, 100% coverage for new code): devtools::test_coverage()

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

• If a bug was fixed, a unit test was added.
• 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 "# cardx (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".

[github-actions]

Unit Tests Summary

  1 files  163 suites   1m 7s ⏱️
161 tests 161 ✅ 0 💤 0 ❌
678 runs  678 ✅ 0 💤 0 ❌

Results for commit c023a1a.

♻️ 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$
ard_event_rates	👶		$+0.00$	$+1$	$0$	$0$	$0$

Additional test case details

Test Suite	$Status$	Time on main	$±Time$	Test Case
ard_continuous.survey.design	💚	$13.95$	$-2.60$	unstratified_ard_continuous.survey.design_works
ard_event_rates	👶		$+0.00$	ard_event_rates_errors_with_incomplete_factor_columns
ard_event_rates	👶		$+0.00$	ard_event_rates_follows_ard_structure
ard_event_rates	👶		$+0.01$	ard_event_rates_ordered_works
ard_event_rates	👶		$+0.00$	ard_event_rates_statistic_works
ard_event_rates	👶		$+2.87$	ard_event_rates_works_with_default_settings
ard_event_rates	👶		$+0.00$	ard_event_rates_works_without_any_variables
ard_event_rates	👶		$+0.00$	ard_hierarchical_count_works_with_by_variable_not_present_in_denominator_

Results for commit aadbd6f

♻️ This comment has been updated with latest results.

[github-actions]

Code Coverage Summary

Filename                                Stmts    Miss  Cover    Missing
------------------------------------  -------  ------  -------  -----------------------------------
R/add_total_n.survey.design.R              12       0  100.00%
R/ard_aod_wald_test.R                      77       8  89.61%   38-43, 93, 96
R/ard_attributes.survey.design.R            2       0  100.00%
R/ard_car_anova.R                          45       2  95.56%   62, 65
R/ard_car_vif.R                            62       1  98.39%   87
R/ard_categorical_ci.R                     96       1  98.96%   83
R/ard_categorical_ci.survey.design.R      129       1  99.22%   180
R/ard_categorical.survey.design.R         392       8  97.96%   77, 227-230, 274, 516, 530
R/ard_continuous_ci.R                      28       1  96.43%   38
R/ard_continuous_ci.survey.design.R       138       0  100.00%
R/ard_continuous.survey.design.R          274      14  94.89%   86, 177, 187, 338, 369-370, 418-426
R/ard_dichotomous.survey.design.R          73       3  95.89%   51, 156, 161
R/ard_effectsize_cohens_d.R               103       2  98.06%   69, 122
R/ard_effectsize_hedges_g.R                91       2  97.80%   68, 120
R/ard_emmeans_mean_difference.R            70       0  100.00%
R/ard_event_rates.R                        76      16  78.95%   72-75, 81, 113-116, 127-133
R/ard_missing.survey.design.R              79       1  98.73%   52
R/ard_regression_basic.R                   16       1  93.75%   46
R/ard_regression.R                         73       0  100.00%
R/ard_smd_smd.R                            69       5  92.75%   57, 83-86
R/ard_stats_anova.R                        95       0  100.00%
R/ard_stats_aov.R                          46       0  100.00%
R/ard_stats_chisq_test.R                   40       1  97.50%   39
R/ard_stats_fisher_test.R                  43       1  97.67%   42
R/ard_stats_kruskal_test.R                 36       1  97.22%   38
R/ard_stats_mcnemar_test.R                 80       2  97.50%   63, 106
R/ard_stats_mood_test.R                    49       1  97.96%   45
R/ard_stats_oneway_test.R                  39       0  100.00%
R/ard_stats_poisson_test.R                 76       1  98.68%   59
R/ard_stats_prop_test.R                    85       1  98.82%   43
R/ard_stats_t_test_onesample.R             41       0  100.00%
R/ard_stats_t_test.R                      112       2  98.21%   65, 111
R/ard_stats_wilcox_test_onesample.R        42       0  100.00%
R/ard_stats_wilcox_test.R                  99       2  97.98%   65, 117
R/ard_survey_svychisq.R                    38       1  97.37%   44
R/ard_survey_svyranktest.R                 54       1  98.15%   44
R/ard_survey_svyttest.R                    53       1  98.11%   42
R/ard_survival_survdiff.R                  89       0  100.00%
R/ard_survival_survfit_diff.R              76       0  100.00%
R/ard_survival_survfit.R                  197       5  97.46%   211-215
R/construction_helpers.R                  106      10  90.57%   160-175, 189, 248
R/proportion_ci.R                         195       1  99.49%   454
TOTAL                                    3596      97  97.30%

Diff against main

Filename               Stmts    Miss  Cover
-------------------  -------  ------  -------
R/ard_event_rates.R      +76     +16  +78.95%
TOTAL                    +76     +16  -0.40%

Results for commit: c023a1a

Minimum allowed coverage is 80%

♻️ This comment has been updated with latest results

[ddsjoberg]

Thanks @edelarua ! Can you help me understand the differences between this and the hierarchical function? Also, when we refer to ordered, does that mean ordered factors?

[edelarua]

Thanks @edelarua ! Can you help me understand the differences between this and the hierarchical function? Also, when we refer to ordered, does that mean ordered factors?

This performs similarly to the hierarchical function but doesn't use hierarchies, so calculates event rates for flat tables. The ordered argument is used to count "ordered" variables by highest level (i.e. grade/severity) which the hierarchy function is not able to do unless there is more than one level in the hierarchy since it has to use a workaround that moves the analysis variable to by right now.

For example, the grade rows in this table could be calculated with ard_event_rates(variables = AESEV, ordered = TRUE) but not ard_hierarchical(): https://insightsengineering.github.io/tlg-catalog/stable/tables/adverse-events/aet01_aesi.html#output

Honestly, we could probably simplify the hierarchical functions by implementing this upstream in cards (or internally) but there are several common tables where this would be useful.

[ddsjoberg]

Hmmm, before we merge this in, can we brainstorm together a bit? Either today or next week?

[ddsjoberg]

Would another way to calculate these quantities be:

ADAE |> 
  dplyr::slice_max(AESEV, n = 1, with_ties = FALSE, by = USUBJID) |> 
  cards::ard_categorical(
    by = TRTA, 
    variables = AESEV,
    denominator = ADSL |> dplyr::select(USUBJID, TRTA = ARM)
  )