Improve analyze/summarize function documentation

[edelarua]

Pull Request

Fixes #1130

Adds a short, informative paragraph at the beginning of analyze/summarize function documentation pages to (hopefully) answer the most common questions about how each function works.

[github-actions]

Unit Tests Summary

    1 files     83 suites   1m 10s ⏱️
  850 tests   838 ✅  12 💤 0 ❌
1 828 runs  1 150 ✅ 678 💤 0 ❌

Results for commit a83862a.

♻️ 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$
analyze_vars_in_cols	💔	$2.38$	$+3.08$	$+17$	$-7$	$0$	$0$
count_occurrences	💔	$0.72$	$+1.54$	$+10$	$-8$	$0$	$0$
summarize_coxreg	💔	$3.11$	$+2.80$	$+13$	$-13$	$0$	$0$
summarize_num_patients	💔	$1.07$	$+1.21$	$+18$	$-16$	$0$	$0$

Additional test case details

Test Suite	$Status$	Time on main	$±Time$	Test Case
analyze_vars_in_cols	💔	$0.46$	$+1.42$	summarize_works_with_nested_analyze
summarize_coxreg	💔	$0.43$	$+1.30$	summarize_coxreg_adds_the_multivariate_Cox_regression_layer_to_rtables

Results for commit c23f5b6

♻️ This comment has been updated with latest results.

[github-actions]

Code Coverage Summary

Filename                                   Stmts    Miss  Cover    Missing
---------------------------------------  -------  ------  -------  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
R/abnormal_by_baseline.R                      65       0  100.00%
R/abnormal_by_marked.R                        55       5  90.91%   92-96
R/abnormal_by_worst_grade_worsen.R           116       3  97.41%   262-264
R/abnormal_by_worst_grade.R                   60       0  100.00%
R/abnormal.R                                  43       0  100.00%
R/analyze_variables.R                        162       3  98.15%   488, 512, 628
R/analyze_vars_in_cols.R                     176      33  81.25%   178, 201-206, 221, 235-236, 244-252, 258-264, 343-349
R/bland_altman.R                              92       1  98.91%   43
R/combination_function.R                       9       0  100.00%
R/compare_variables.R                         84       5  94.05%   139-143, 255, 314
R/control_incidence_rate.R                    10       0  100.00%
R/control_logistic.R                           7       0  100.00%
R/control_step.R                              23       1  95.65%   58
R/control_survival.R                          15       0  100.00%
R/count_cumulative.R                          50       1  98.00%   73
R/count_missed_doses.R                        34       0  100.00%
R/count_occurrences_by_grade.R               113       5  95.58%   111, 161-163, 166
R/count_occurrences.R                        115       1  99.13%   115
R/count_patients_events_in_cols.R             67       1  98.51%   59
R/count_patients_with_event.R                 47       0  100.00%
R/count_patients_with_flags.R                 58       4  93.10%   63-64, 69-70
R/count_values.R                              27       0  100.00%
R/cox_regression_inter.R                     154       0  100.00%
R/cox_regression.R                           161       0  100.00%
R/coxph.R                                    167       7  95.81%   191-195, 238, 253, 261, 267-268
R/d_pkparam.R                                406       0  100.00%
R/decorate_grob.R                            113       0  100.00%
R/desctools_binom_diff.R                     621      64  89.69%   53, 88-89, 125-126, 129, 199, 223-232, 264, 266, 286, 290, 294, 298, 353, 356, 359, 362, 422, 430, 439, 444-447, 454, 457, 466, 469, 516-517, 519-520, 522-523, 525-526, 593, 604-616, 620, 663, 676, 680
R/df_explicit_na.R                            30       0  100.00%
R/estimate_multinomial_rsp.R                  50       1  98.00%   64
R/estimate_proportion.R                      205      12  94.15%   82-89, 93, 98, 319, 485, 591
R/fit_rsp_step.R                              36       0  100.00%
R/fit_survival_step.R                         36       0  100.00%
R/formatting_functions.R                     183       2  98.91%   143, 278
R/g_forest.R                                 585      60  89.74%   241, 253-256, 261-262, 276, 278, 288-291, 336-339, 346, 415, 502, 515, 519-520, 525-526, 539, 555, 602, 633, 708, 717, 723, 742, 797-817, 820, 831, 850, 905, 908, 1043-1048
R/g_ipp.R                                    133       0  100.00%
R/g_km.R                                     350      57  83.71%   286-289, 308-310, 364-367, 401, 429, 433-476, 483-487
R/g_lineplot.R                               249      23  90.76%   196, 370-377, 416-426, 518, 524, 526
R/g_step.R                                    68       1  98.53%   109
R/g_waterfall.R                               47       0  100.00%
R/h_adsl_adlb_merge_using_worst_flag.R        73       0  100.00%
R/h_biomarkers_subgroups.R                    46       0  100.00%
R/h_cox_regression.R                         110       0  100.00%
R/h_km.R                                     508      41  91.93%   137, 189-194, 287, 378, 380-381, 392-394, 413, 420-421, 423-425, 433-435, 460, 465-468, 651-654, 1108-1119
R/h_logistic_regression.R                    468       3  99.36%   203-204, 273
R/h_map_for_count_abnormal.R                  54       0  100.00%
R/h_pkparam_sort.R                            15       0  100.00%
R/h_response_biomarkers_subgroups.R           90      12  86.67%   50-55, 107-112
R/h_response_subgroups.R                     178      18  89.89%   257-270, 329-334
R/h_stack_by_baskets.R                        64       1  98.44%   89
R/h_step.R                                   180       0  100.00%
R/h_survival_biomarkers_subgroups.R           88       6  93.18%   111-116
R/h_survival_duration_subgroups.R            207      18  91.30%   259-271, 336-341
R/imputation_rule.R                           17       2  88.24%   54-55
R/incidence_rate.R                           100       7  93.00%   47-54
R/logistic_regression.R                      102       0  100.00%
R/missing_data.R                              21       3  85.71%   32, 66, 76
R/odds_ratio.R                               109       0  100.00%
R/prop_diff_test.R                            91       0  100.00%
R/prop_diff.R                                265      16  93.96%   69-72, 104, 289-296, 439, 499, 604
R/prune_occurrences.R                         57      10  82.46%   138-142, 188-192
R/response_biomarkers_subgroups.R             69       6  91.30%   196-201
R/response_subgroups.R                       213      12  94.37%   100-105, 260-261, 336, 387-389
R/riskdiff.R                                  65       7  89.23%   102-105, 114, 124-125
R/rtables_access.R                            38       4  89.47%   159-162
R/score_occurrences.R                         20       1  95.00%   124
R/split_cols_by_groups.R                      49       0  100.00%
R/stat.R                                      59       3  94.92%   73-74, 129
R/summarize_ancova.R                         106       2  98.11%   182, 187
R/summarize_change.R                          30       0  100.00%
R/summarize_colvars.R                         10       0  100.00%
R/summarize_coxreg.R                         172       2  98.84%   203, 430
R/summarize_glm_count.R                      209      27  87.08%   192-193, 307, 463-495
R/summarize_num_patients.R                    94       5  94.68%   116-118, 264-265
R/summarize_patients_exposure_in_cols.R       96       1  98.96%   55
R/survival_biomarkers_subgroups.R             78       6  92.31%   117-122
R/survival_coxph_pairwise.R                   79      11  86.08%   50-51, 63-71
R/survival_duration_subgroups.R              211       6  97.16%   124-129
R/survival_time.R                             79       0  100.00%
R/survival_timepoint.R                       113       7  93.81%   124-130
R/utils_checkmate.R                           68       0  100.00%
R/utils_default_stats_formats_labels.R       124       1  99.19%   72
R/utils_factor.R                             109       2  98.17%   84, 302
R/utils_ggplot.R                             110       0  100.00%
R/utils_grid.R                               126       5  96.03%   164, 279-286
R/utils_rtables.R                            100       9  91.00%   39, 46, 51, 58-62, 403-404
R/utils_split_funs.R                          52       2  96.15%   82, 94
R/utils.R                                    141       7  95.04%   118, 121, 124, 128, 137-138, 332
TOTAL                                      10485     553  94.73%

Diff against main

Filename                      Stmts    Miss  Cover
--------------------------  -------  ------  --------
R/h_km.R                         -1       0  -0.02%
R/summarize_num_patients.R       +1       0  +0.06%
TOTAL                             0       0  +100.00%

Results for commit: a83862a

Minimum allowed coverage is 80%

♻️ This comment has been updated with latest results

[ayogasekaram]

Excellent clarity @edelarua!! lgtm :)