We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
-
Our Standards
+
Our Standards
+
Examples of behavior that contributes to a positive environment for our community include:
-
Demonstrating empathy and kindness toward other people
+
+
Demonstrating empathy and kindness toward other people
Being respectful of differing opinions, viewpoints, and experiences
Giving and gracefully accepting constructive feedback
Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
Focusing on what is best not just for us as individuals, but for the overall community
-
Examples of unacceptable behavior include:
-
The use of sexualized language or imagery, and sexual attention or advances of any kind
+
+
Examples of unacceptable behavior include:
+
+
The use of sexualized language or imagery, and sexual attention or advances of any kind
Trolling, insulting or derogatory comments, and personal or political attacks
Public or private harassment
Publishing others’ private information, such as a physical or email address, without their explicit permission
Other conduct which could reasonably be considered inappropriate in a professional setting
-
+
+
-
Enforcement Responsibilities
+
Enforcement Responsibilities
+
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
-
Scope
+
Scope
+
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
-
Enforcement
+
Enforcement
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [INSERT CONTACT METHOD]. All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
-
Enforcement Guidelines
+
Enforcement Guidelines
+
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
-
1. Correction
+
1. Correction
+
Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
-
2. Warning
+
2. Warning
+
Community Impact: A violation through a single incident or series of actions.
Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
-
3. Temporary Ban
+
3. Temporary Ban
+
Community Impact: A serious violation of community standards, including sustained inappropriate behavior.
Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
-
4. Permanent Ban
+
4. Permanent Ban
+
Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
Consequence: A permanent ban from any sort of public interaction within the community.
Please refer the project documentation for a brief introduction. Please also see other articles within the project documentation for additional information.
-
Code of Conduct
+
Code of Conduct
+
A Code of Conduct governs this project. Participants and contributors are expected to follow the rules outlined therein.
-
License
+
License
+
All your contributions will be covered by this project’s license.
-
Issues
+
Issues
+
We use GitHub to track issues, feature requests, and bugs. Before submitting a new issue, please check if the issue has already been reported. If the issue already exists, please upvote the existing issue 👍.
For new feature requests, please elaborate on the context and the benefit the feature will have for users, developers, or other relevant personas.
-
Pull requests
+
Pull requests
+
-
GitHub Flow
+
GitHub Flow
+
This repository uses the GitHub Flow model for collaboration. To submit a pull request:
-
+
+
Create a branch
Please see the branch naming convention below. If you don’t have write access to this repository, please fork it.
Make changes
Make sure your code
-
passes all checks imposed by GitHub Actions
+
+
passes all checks imposed by GitHub Actions
is well documented
is well tested with unit tests sufficiently covering the changes introduced
-
+
+
Create a pull request (PR)
In the pull request description, please link the relevant issue (if any), provide a detailed description of the change, and include any assumptions.
Suppose your changes are related to a current issue in the current project; please name your branch as follows: <issue_id>_<short_description>. Please use underscore (_) as a delimiter for word separation. For example, 420_fix_ui_bug would be a suitable branch name if your change is resolving and UI-related bug reported in issue number 420 in the current project.
If your change affects multiple repositories, please name your branches as follows: <issue_id>_<issue_repo>_<short description>. For example, 69_awesomeproject_fix_spelling_error would reference issue 69 reported in project awesomeproject and aims to resolve one or more spelling errors in multiple (likely related) repositories.
monorepo and staged.dependencies
-
+
+
Sometimes you might need to change upstream dependent package(s) to be able to submit a meaningful change. We are using staged.dependencies functionality to simulate a monorepo behavior. The dependency configuration is already specified in this project’s staged_dependencies.yaml file. You need to name the feature branches appropriately. This is the only exception from the branch naming convention described above.
This repository follows some unified processes and standards adopted by its maintainers to ensure software development is carried out consistently within teams and cohesively across other repositories.
-
Style guide
+
Style guide
+
This repository follows the standard tidyverse style guide and uses lintr for lint checks. Customized lint configurations are available in this repository’s .lintr file.
-
Dependency management
+
Dependency management
+
Lightweight is the right weight. This repository follows tinyverse recommedations of limiting dependencies to minimum.
-
Dependency version management
+
Dependency version management
+
If the code is not compatible with all (!) historical versions of a given dependenct package, it is required to specify minimal version in the DESCRIPTION file. In particular: if the development version requires (imports) the development version of another package - it is required to put abc (>= 1.2.3.9000).
-
Recommended development environment & tools
+
Recommended development environment & tools
+
-
R & package versions
+
R & package versions
+
We continuously test our packages against the newest R version along with the most recent dependencies from CRAN and BioConductor. We recommend that your working environment is also set up in the same way. You can find the details about the R version and packages used in the R CMD check GitHub Action execution log - there is a step that prints out the R sessionInfo().
If you discover bugs on older R versions or with an older set of dependencies, please create the relevant bug reports.
-
pre-commit
+
+pre-commit
+
We highly recommend that you use the pre-commit tool combined with R hooks for pre-commit to execute some of the checks before committing and pushing your changes.
Pre-commit hooks are already available in this repository’s .pre-commit-config.yaml file.
-
Recognition model
+
Recognition model
+
As mentioned previously, all contributions are deeply valued and appreciated. While all contribution data is available as part of the repository insights, to recognize a significant contribution and hence add the contributor to the package authors list, the following rules are enforced:
-
Minimum 5% of lines of code authored* (determined by git blame query) OR
+
+
Minimum 5% of lines of code authored* (determined by git blame query) OR
Being at the top 5 contributors in terms of number of commits OR lines added OR lines removed*
-
*Excluding auto-generated code, including but not limited to roxygen comments or renv.lock files.
+
+
*Excluding auto-generated code, including but not limited to roxygen comments or renv.lock files.
The package maintainer also reserves the right to adjust the criteria to recognize contributions.
-
Questions
+
Questions
+
If you have further questions regarding the contribution guidelines, please contact the package/repository maintainer.
If you believe you have found a security vulnerability in any of the repositories in this organization, please report it to us through coordinated disclosure.
Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.
Instead, please send an email to vulnerability.management[@]roche.com.
Please include as much of the information listed below as you can to help us better understand and resolve the issue:
-
The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting)
+
+
The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting)
Full paths of source file(s) related to the manifestation of the issue
The location of the affected source code (tag/branch/commit or direct URL)
Any special configuration required to reproduce the issue
Step-by-step instructions to reproduce the issue
Proof-of-concept or exploit code (if possible)
Impact of the issue, including how an attacker might exploit the issue
-
This information will help us triage your report more quickly.
+
+
This information will help us triage your report more quickly.
-
Data Security Standards (DSS)
+
Data Security Standards (DSS)
+
Please make sure that while reporting issues in the form a bug, feature, or pull request, all sensitive information such as PII, PHI, and PCI is completely removed from any text and attachments, including pictures and videos.
Added rel_height_plot parameter to g_lineplot() to control the line plot height relative to annotation table height.
@@ -57,22 +121,33 @@
Enhancementsg_lineplot() to allow users to return the line plot and annotation table elements as a list instead of stacked for more complex customization.
Improved summarize_glm_count() documentation and all its associated functions to better describe the results and the functions’ purpose.
Added method argument to s_odds_ratio() and estimate_odds_ratio() to control whether exact or approximate conditional likelihood calculations are used.
-
+
+
-
Bug Fixes
-
Added defaults for d_count_cumulative parameters as described in the documentation.
+
Bug Fixes
+
+
+
Added defaults for d_count_cumulative parameters as described in the documentation.
Fixed a bug of empty levels on g_lineplot x-axis were not shown in either plots.
Fixed a bug in a_surv_time that threw an error when split only has "is_event".
Fixed disappearing line in g_lineplot when using only one group or strata level.
Began deprecation of the confusing functions summary_formats and summary_labels.
+
Miscellaneous
+
+
+
Began deprecation of the confusing functions summary_formats and summary_labels.
Enhanced general descriptions of analyze and summarize functions throughout package documentation.
Finalized deprecation of the strata and cohort_id arguments to g_lineplot.
Moved incidence rate helper functions into a separate h_incidence_rate.R file.
-
+
+
-
tern 0.9.5
CRAN release: 2024-06-21
-
-
Enhancements
-
Added facet_var to g_lineplot to allow plot faceting by a factor variable.
+
tern 0.9.5
+
+
CRAN release: 2024-06-21
+
+
Enhancements
+
+
+
Added facet_var to g_lineplot to allow plot faceting by a factor variable.
Added examples and tests for label_all parameter to extract_survival_biomarkers and extract_survival_subgroups.
Added the xticks, xlim, and ylim arguments to g_lineplot to allow for customization of the x and y axes.
Updated g_lineplot legend to follow factor levels set by users.
-
+
+
-
Bug Fixes
-
Fixed a bug in s_ancova that prevented statistics from being printed when arm levels include special characters.
+
Bug Fixes
+
+
+
Fixed a bug in s_ancova that prevented statistics from being printed when arm levels include special characters.
Fixed a bug in decorate_grob that prevented the right margins to be respected when adding title and footers decorations.
-
+
+
-
Miscellaneous
-
Began deprecation of the unused label_all parameter to tabulate_survival_biomarkers and tabulate_survival_subgroups, with redirection to the same parameter in their associated extract_* functions.
-
+
Miscellaneous
+
+
+
Began deprecation of the unused label_all parameter to tabulate_survival_biomarkers and tabulate_survival_subgroups, with redirection to the same parameter in their associated extract_* functions.
+
+
-
tern 0.9.4
CRAN release: 2024-04-17
-
-
New Features
-
Added h_glm_negbin to h_glm_count to enable count data analysis using a negative binomial model.
+
tern 0.9.4
+
+
CRAN release: 2024-04-17
+
+
New Features
+
+
+
Added h_glm_negbin to h_glm_count to enable count data analysis using a negative binomial model.
Added argument grade_groups_only to count_occurrences_by_grade to allow users to only display rows for specified grade groups.
Added internal function df2gg that converts data.frame objects to ggplot objects.
Added functions control_surv_med_annot and control_coxph_annot to configure g_km annotation table sizes/positions.
Refactored g_km to output a ggplot object instead of a grob object.
Refactored g_forest to output a ggplot object instead of a grob object.
-
+
+
-
Enhancements
-
Default format for mean p-values (mean_pval) updated from "xx.xx" to "x.xxxx | (<0.0001)".
-
+
Enhancements
+
+
+
Default format for mean p-values (mean_pval) updated from "xx.xx" to "x.xxxx | (<0.0001)".
+
+
-
Bug Fixes
-
Fixed nested column split label overlay issue in rtable2gg to clean up appearance of text labels.
+
Bug Fixes
+
+
+
Fixed nested column split label overlay issue in rtable2gg to clean up appearance of text labels.
Fixed bug in s_ancova causing incorrect difference calculations for arm variables with irregular levels.
Fixed bug in format_count_fraction_fixed_dp that did not have the same print when the fraction was 1 (100%).
Fixed bug in g_lineplot causing default labels not to update according to specified control settings.
Fixed bug causing an error when automatic value formatting was applied to NA values.
-
+
+
-
Miscellaneous
-
Added function expect_snapshot_ggplot to test setup file to process plot snapshot tests and allow plot dimensions to be set.
+
Miscellaneous
+
+
+
Added function expect_snapshot_ggplot to test setup file to process plot snapshot tests and allow plot dimensions to be set.
Adapted to argument renames introduced in ggplot2 3.5.0.
Renamed individual_patient_plot.R to g_ipp.R.
Removed all instances of deprecated parameters time_unit_input, time_unit_output, na_level and indent_mod.
Added ref_group_coxph parameter to g_km to specify the reference group used for pairwise Cox-PH calculations when annot_coxph = TRUE.
+
Enhancements
+
+
+
Added ref_group_coxph parameter to g_km to specify the reference group used for pairwise Cox-PH calculations when annot_coxph = TRUE.
Added annot_coxph_ref_lbls parameter to g_km to enable printing the reference group in table labels when annot_coxph = TRUE.
Added x_lab parameter to g_lineplot to customize x-axis label.
Remove 25% padding of y-axis in g_lineplot.
Added support for creating multiple risk difference columns, each comparing to a single comparison group. Multiple comparison groups can be specified as a vector via the arm_y argument.
Allowed numeric vector as count_by input in analyze_num_patients and summarize_num_patients.
Aligned plot and table vertically in g_lineplot.
-
+
+
-
Bug Fixes
-
Fixed bug in decorate_grob preventing text wrapping from accounting for font size.
+
Bug Fixes
+
+
+
Fixed bug in decorate_grob preventing text wrapping from accounting for font size.
Fixed implementation of na_str argument in all column-wise analysis and tabulation functions.
-
+
+
-
Miscellaneous
-
Specified minimal version of package dependencies.
+
Miscellaneous
+
+
+
Specified minimal version of package dependencies.
Upgraded to_string_matrix to take into account widths and other printing parameters.
Added formatting function format_count_fraction_lt10 for formatting count_fraction with special consideration when count is less than 10.
+
Enhancements
+
+
+
Added formatting function format_count_fraction_lt10 for formatting count_fraction with special consideration when count is less than 10.
Updated s_summary.logical output for count_fraction when denominator is zero to display as NA instead of 0 in tables.
Updated analyze_vars_in_cols to allow character input to indicate whether nominal time point is post-dose or pre-dose when applying the 1/3 imputation rule.
-
+
+
-
Bug Fixes
-
Fixed bug in g_km causing an error when converting certain annotation width units.
-
+
Bug Fixes
+
+
+
Fixed bug in g_km causing an error when converting certain annotation width units.
+
+
-
Miscellaneous
-
Began deprecation of na_level argument in s_count_abnormal_by_baseline, a_summary, analyze_vars, analyze_vars_in_cols, compare_vars, h_map_for_count_abnormal, h_stack_by_baskets, summarize_colvars, a_coxreg, and summarize_coxreg and replaced it with the na_str argument.
+
Miscellaneous
+
+
+
Began deprecation of na_level argument in s_count_abnormal_by_baseline, a_summary, analyze_vars, analyze_vars_in_cols, compare_vars, h_map_for_count_abnormal, h_stack_by_baskets, summarize_colvars, a_coxreg, and summarize_coxreg and replaced it with the na_str argument.
strata and cohort_id parameters renamed to group_var and subject_var respectively in g_lineplot and control_lineplot_vars .
-
+
+
-
tern 0.9.1
+
tern 0.9.1
+
-
New Features
-
Added imputation_rule function to apply imputation rule to data.
+
New Features
+
+
+
Added imputation_rule function to apply imputation rule to data.
Added new format function format_sigfig to allow for numeric value formatting by a specified number of significant figures.
Added vectors containing default statistic formats and labels as tern_default_formats and tern_default_labels, respectively.
Added function get_stats to return methods from given statistical method groups.
Added function get_formats_from_stats to return formats and get_labels_from_stats to return labels for a given set of statistics.
Added "auto" option for .formats. It uses format_auto to determine automatically the number of digits.
Added title argument to h_grob_tbl_at_risk and annot_at_risk_title argument to g_km and h_km_layout which allows user to add “Patients at Risk” title to Kaplan-Meier at risk annotation table.
-
+
+
-
Enhancements
-
Refactored tabulate_rsp_subgroups to pass sanitation checks by preventing creation of degenerate subtables.
+
Enhancements
+
+
+
Refactored tabulate_rsp_subgroups to pass sanitation checks by preventing creation of degenerate subtables.
Updated analyze_vars_in_cols to use caching, allow implementation of imputation rule via the imp_rule argument, and allow user to specify cell alignment via the .aligns argument.
Updated add_rowcounts to allow addition of row counts from alt_counts_df using the alt_counts argument.
Added gp argument to g_forest to control graphical parameters such as font size.
-
+
+
-
Miscellaneous
-
Grouped functions relating to valid method names and their default formats and labels into new source file utils_defaults_handling.R.
+
Miscellaneous
+
+
+
Grouped functions relating to valid method names and their default formats and labels into new source file utils_defaults_handling.R.
Started deprecation of summary_custom() and a_summary() as a S3 method.
Renamed statistical method for p-value in the discrete case to pval_counts.
Removed a_summary_internal() in favor of only one main a_summary().
-
+
+
-
tern 0.9.0
CRAN release: 2023-09-01
-
-
New Features
-
Added stat_propdiff_ci function to calculate proportion/risk difference and CI.
+
tern 0.9.0
+
+
CRAN release: 2023-09-01
+
+
New Features
+
+
+
Added stat_propdiff_ci function to calculate proportion/risk difference and CI.
Added risk difference column functionality via the riskdiff argument to functions count_occurrences, count_occurrences_by_grade, count_patients_with_event, count_patients_with_flags, analyze_num_patients, and summarize_num_patients.
-
+
+
-
Enhancements
-
Refactored the function a_summary to no longer use the helper function create_afun_summary.
+
Enhancements
+
+
+
Refactored the function a_summary to no longer use the helper function create_afun_summary.
Refactored functions summarize_vars and compare_vars to use the refactored a_summary function.
Created new internal helper functions ungroup_stats to ungroup statistics calculated for factor variables, and a_summary_internal to perform calculations for a_summary.
-
+
+
-
Bug Fixes
-
Fixed bug in s_count_occurrences_by_grade so that “missing” grade always appears as the final level.
+
Bug Fixes
+
+
+
Fixed bug in s_count_occurrences_by_grade so that “missing” grade always appears as the final level.
Fixed bug in analyze_vars_in_cols when categorical data was used.
Fixed bug in s_count_occurrences_by_grade so that levels are not relabeled when reordering to account for “missing” grades.
-
+
+
-
Miscellaneous
-
Fixed swapped descriptions for the .N_row and .N_col parameters.
+
Miscellaneous
+
+
+
Fixed swapped descriptions for the .N_row and .N_col parameters.
Removed internal calls to df_explicit_na. Changes in NA values should happen externally to tern functions, depending on users’ needs.
Reinstated correct soft deprecation for create_afun_summary and create_afun_compare.
-
+
+
-
tern 0.8.5
+
tern 0.8.5
+
-
Enhancements
-
Added ylim argument to g_km to allow the user to set custom limits for the y-axis.
+
Enhancements
+
+
+
Added ylim argument to g_km to allow the user to set custom limits for the y-axis.
Added assertion to g_km which checks whether there is one arm present in the data when annot_coxph is true.
Added flag_labels argument to s_count_patients_with_flags to enable more label handling options in count_patients_by_flags.
Started deprecation cycle for summarize_vars and control_summarize_vars. Renamed into analyze_vars and control_analyze_vars to reflect underlying rtables machinery while keeping backward compatibility with aliases.
-
+
Miscellaneous
+
+
+
Started deprecation cycle for summarize_vars and control_summarize_vars. Renamed into analyze_vars and control_analyze_vars to reflect underlying rtables machinery while keeping backward compatibility with aliases.
+
+
-
tern 0.8.4
CRAN release: 2023-06-27
-
-
Enhancements
-
Added method for character class to h_coxreg_inter_effect enabling character covariates in summarize_coxreg.
-
+
tern 0.8.4
+
+
CRAN release: 2023-06-27
+
+
Enhancements
+
+
+
Added method for character class to h_coxreg_inter_effect enabling character covariates in summarize_coxreg.
+
+
-
Miscellaneous
-
Began deprecation of time_unit_input and time_unit_output arguments and replaced them with the input_time_unit and num_pt_year, respectively, in control_incidence_rate.
+
Miscellaneous
+
+
+
Began deprecation of time_unit_input and time_unit_output arguments and replaced them with the input_time_unit and num_pt_year, respectively, in control_incidence_rate.
Removed deprecated pairwise function.
Deprecated a_compare and replaced it with a_summary with argument compare = TRUE.
Deprecated helper functions create_afun_summary and create_afun_compare which are no longer used by a_summary and a_compare respectively.
-
+
+
-
Bug Fixes
-
Fixed long double assertion check in sum(weights) for M1mac installation.
-
+
Bug Fixes
+
+
+
Fixed long double assertion check in sum(weights) for M1mac installation.
+
+
-
tern 0.8.3
CRAN release: 2023-06-19
-
-
Enhancements
-
Added explicit zero counts to g_km plot “at risk” annotation tables.
+
tern 0.8.3
+
+
CRAN release: 2023-06-19
+
+
Enhancements
+
+
+
Added explicit zero counts to g_km plot “at risk” annotation tables.
Added a flag for total level split in analyze_patients_exposure_in_cols.
Implemented .indent_mods argument in functions h_tab_one_biomarker, h_tab_rsp_one_biomarker, h_tab_surv_one_biomarker, summarize_logistic, logistic_summary_by_flag, tabulate_rsp_biomarkers, a_coxreg, summarize_coxreg, tabulate_survival_biomarkers, surv_time, surv_timepoint, and cfun_by_flag.
Updated summarize_coxreg to print covariates in data rows for univariate Cox regression with no interactions and content rows otherwise.
Removed “baseline status” text from d_count_abnormal_by_baseline labels.
Improved default sizing of annotation tables in g_km and added dynamic scaling of the surv_med and coxph annotation tables, with customization via the width_annots argument.
-
+
+
-
Bug Fixes
-
Fixed bug in split_text_grob preventing titles and footnotes from being properly formatted and printed by decorate_grob.
+
Bug Fixes
+
+
+
Fixed bug in split_text_grob preventing titles and footnotes from being properly formatted and printed by decorate_grob.
Fixed bug in g_lineplot preventing the addition of lines to the plot when midpoint statistic calculations result in NA value(s).
Fixed tern:::tidy.glm formals to respect broom:::tidy.default formals.
-
+
+
-
Miscellaneous
-
Updated README to include installation instructions for CRAN.
+
Miscellaneous
+
+
+
Updated README to include installation instructions for CRAN.
Fixed bug causing incorrect ordering of numeric grade levels when missing grades are present in s_count_occurrences_by_grade.
+
Bug Fixes
+
+
+
Fixed bug causing incorrect ordering of numeric grade levels when missing grades are present in s_count_occurrences_by_grade.
Refactored summarize_vars_in_cols to work with pagination machinery.
Fixed bug to allow passing of conf_level argument to emmeans::contrast() in s_ancova.
Fixed bugs in rtables_access.R caused by not checking for specific combinations (also the standard values that were never used) of column indices and names.
Replaced with standard assertions from checkmate the following functions: all_elements_in_ref, is_df_with_nlevels_factor, is_df_with_no_na_level, is_proportion_vector, is_quantiles_vector, is_character_or_factor, is_nonnegative_count, is_valid_character, assert_character_or_factor, assert_equal_length and has_tabletree_colnames.
Modified is_proportion, is_equal_length, is_df_with_no_na_level, is_df_with_nlevels_factor, is_variables, is_df_with_variables, is_df_with_factors, is_valid_factor to use assertion logic.
Added more verbose warnings from as_factor_keep_attributes.
Made assert_df_with_factors and assert_proportion_value internal functions.
Renamed assertthat.R and test-assertthat.R to utils_checkmate.R and test-utils_checkmate.R.
-
+
+
-
Documentation and NAMESPACE Polishing
-
Added stable badges for:
-
+
Documentation and NAMESPACE Polishing
+
+
+
Added stable badges for:
+
+
count_abnormal_by_marked (reference to abnormal_by_marked), count_abnormal_lab_worsen_by_baseline and h_adlb_worsen (reference to abnormal_by_worst_grade_worsen_from_baseline), count_abnormal_by_worst_grade (reference to abnormal_by_worst_grade), to_string_matrix, tidy.summary.coxph, tidy.step, surv_timepoint, (reference to survival_timepoint), surv_time (reference to survival_time), coxph_pairwise (reference to survival_coxph_pairwise), extract_survival_subgroups and tabulate_survival_subgroups (reference to survival_duration_subgroups), extract_survival_biomarkers and tabulate_survival_biomarkers (reference to survival_biomarkers_subgroups), control_summarize_vars, s_summary and a_summary (reference to summarize_variables) and kept the S3 method tree.
summarize_patients_exposure_in_cols, summarize_num_patients with s_num_patients, s_num_patients_content, summarize_num_patients.
Internal keywords added, export removed, _pkgdown.yml updated, and tern::: added for tests/examples/vignettes where present for the following functions:
-
(chain functions, reference to abnormal_by_marked) s_count_abnormal_by_marked, a_count_abnormal_by_marked.
+
+
(chain functions, reference to abnormal_by_marked) s_count_abnormal_by_marked, a_count_abnormal_by_marked.
(chain functions, reference to abnormal_by_worst_grade_worsen_from_baseline) a_count_abnormal_lab_worsen_by_baseline, s_count_abnormal_lab_worsen_by_baseline.
(chain functions, reference to abnormal_by_worst_grade) s_count_abnormal_by_worst_grade, a_count_abnormal_by_worst_grade.
(chain functions, reference to survival_timepoint) s_surv_timepoint, s_surv_timepoint_diff, a_surv_timepoint, a_surv_timepoint_diff.
h_split_by_subgroups documentation warning fix for wrong placing of example block
-
+
+
-
Documentation and NAMESPACE polishing
-
Adopting the standard of badges for @description instead of every @descriptionIn function. Corrected accordingly summarize_variables_in_cols
+
Documentation and NAMESPACE polishing
+
+
+
Adopting the standard of badges for @description instead of every @descriptionIn function. Corrected accordingly summarize_variables_in_cols
Added stable badge for g_lineplot, g_step, g_waterfall, cox_regression, score_occurrences, add_rowcounts, odds_ratio, count_occurrences, count_occurrences_by_grade, explicit_na, df_explicit_na, count_patients_with_event, decorate_grob, combine_groups, append_varlabels, univariate, stack_grobs, count_abnormal (reference to abnormal), count_abnormal_by_baseline (reference to abnormal_by_baseline).
Internal keywords added, export removed, _pkgdown.yml polished and tern::: for tests, examples, and vignettes when present for the following functions:
-
Deprecated s_cox_univariate function has now deprecated badge.
-
+
+
-
Enhancements
-
Enhanced g_lineplot with table to automatically scale the table height and return a ggplot object.
+
Enhancements
+
+
+
Enhanced g_lineplot with table to automatically scale the table height and return a ggplot object.
Enhanced g_ipp with caption argument and adjust the position.
Enhanced prop_diff, tern function and related functions to be able to apply a continuity correction in the Newcombe method.
Enhanced summarize_numeric_in_columns and summarize_variables to allow factor/character summary and to be able to summarize the number of BLQs in AVALC from ADPC dataset.
Added h_pkparam_sort to order PK PARAM value based on the order of the dataset generated by d_pkparam().
+
New features
+
+
+
Added h_pkparam_sort to order PK PARAM value based on the order of the dataset generated by d_pkparam().
Added d_pkparam to generate PK parameter map for sorting.
-
+
+
-
Enhancements
-
Changed the nudge_y argument of h_g_ipp to be dependent on the data, fixing an issue whereby the baseline labels were offset incorrectly.
+
Enhancements
+
+
+
Changed the nudge_y argument of h_g_ipp to be dependent on the data, fixing an issue whereby the baseline labels were offset incorrectly.
Enhanced stat_mean_ci and s_summary.numeric to calculate the geometric mean with its confidence intervals.
-
+
+
-
Miscellaneous
-
Updated dependencies and internal adjustments after the rtables package refactor.
+
Miscellaneous
+
+
+
Updated dependencies and internal adjustments after the rtables package refactor.
Removed with_label, var_labels, and var_labels<- to resolve conflict with the formatters package, a new dependency.
Added new “Introduction to tern” and “tern tabulation” vignettes.
-
+
+
-
tern 0.7.6
+
tern 0.7.6
+
-
New features
-
Added h_map_for_count_abnormal to create the map used in trim_levels_to_map split function by calling this helper function. It supports two methods: one with all observed mapping, one with at least low limit above zero and at least one non missing high limit.
+
New features
+
+
+
Added h_map_for_count_abnormal to create the map used in trim_levels_to_map split function by calling this helper function. It supports two methods: one with all observed mapping, one with at least low limit above zero and at least one non missing high limit.
Added s_summary_numeric_in_cols and summarize_vars_numeric_in_cols functions to generate summary statistics in columns, mainly used for PK datasets.
Added five statistics to s_summary.numeric to use in s_summary_numeric_in_cols.
-
+
+
-
Enhancements
-
Enhanced functions tabulate_survival_subgroups and tabulate_rsp_subgroups (Survival Duration and Best Response analyses) to calculate N-s based on the records considered to create the model.
+
Enhancements
+
+
+
Enhanced functions tabulate_survival_subgroups and tabulate_rsp_subgroups (Survival Duration and Best Response analyses) to calculate N-s based on the records considered to create the model.
Enhanced the function estimate_proportion and related functions to be able to apply a continuity correction in the Wilson method.
Refactored count_abnormal_by_marked and related statistics and formatting functions to use a more efficient layout with .spl_context argument used for determining denominators and with trim_levels_to_map split function under split_rows_by to show the desired levels in the table. This is a breaking change.
Refactored count_abnormal_by_worst_grade and related statistics and formatting functions to use a more efficient layout with .spl_context argument used for determining denominators and with trim_levels_to_map split function under split_rows_by to show the desired levels in the table. This is a breaking change.
Refactored count_abnormal function and related statistics and formatting functions to use a more efficient layout with trim_levels_to_map split function under split_rows_by to show the desired levels in the table. Also updated abnormal argument to be able to consider more than one level for each direction. This is a breaking change.
Enhanced the function estimate_incidence_rate and related functions to consider the week as time unit for data input.
-
+
+
-
Bug fixes
-
Fixed bug in assertthat functions that output wrong data frame names and limited length of failure message outputs.
-
+
Bug fixes
+
+
+
Fixed bug in assertthat functions that output wrong data frame names and limited length of failure message outputs.
+
+
-
Miscellaneous
-
Removed dependency on utils.nest by using the checkmate and purrr packages for validation and moved get_free_cores and skip_if_too_deep functions from utils.nest into tern.
-
+
Miscellaneous
+
+
+
Removed dependency on utils.nest by using the checkmate and purrr packages for validation and moved get_free_cores and skip_if_too_deep functions from utils.nest into tern.
+
+
-
tern 0.7.5
+
tern 0.7.5
+
-
New features
-
Added functions to estimate continuous biomarker effects across subgroups for survival and binary response endpoints, used to produce corresponding forest plots, see survival_biomarkers_subgroups and response_biomarkers_subgroups.
+
New features
+
+
+
Added functions to estimate continuous biomarker effects across subgroups for survival and binary response endpoints, used to produce corresponding forest plots, see survival_biomarkers_subgroups and response_biomarkers_subgroups.
Added g_lineplot plot function, including new h_format_row helper function and control_lineplot_vars function. Removed g_summary_by.
Added new safety helper function h_stack_by_baskets to stack events in SMQ and/or CQ basket flag in ADAE data set.
-
+
+
-
Enhancements
-
Added a couple of new statistics to s_summary.numeric. Added names attribute to each element of the final list returned by the s_summary.numeric function. Added summary_formats and summary_labels helper functions.
+
Enhancements
+
+
+
Added a couple of new statistics to s_summary.numeric. Added names attribute to each element of the final list returned by the s_summary.numeric function. Added summary_formats and summary_labels helper functions.
Added option to also convert logical variables to factor variables in df_explicit_na.
Refactored h_append_grade_groups to improve its flexibility, robustness and clearness, and to make sure the result is ordering according to the order of grade_groups. Also, added remove_single argument which controls whether the elements of one-element grade groups are in the output or removed.
Added var_labels and show_labels arguments to count_occurrences and count_patients_with_flags to allow for creation of a title row.
Added na_level argument to count_abnormal_by_baseline.
Updated h_append_grade_groups to no longer fill-in empty grade groups with zeros.
-
+
+
-
Bug Fixes
-
Fixed prop_diff_cmh to handle edge case of no FALSE (or TRUE) responses.
+
Bug Fixes
+
+
+
Fixed prop_diff_cmh to handle edge case of no FALSE (or TRUE) responses.
Enhanced g_mmrm_diagnostic to improve error handling when data is not amenable to the Locally Weighted Scatterplot Smoothing.
Fixes in g_km:
-
Plot can now display any combination of the annotation tables for number of patients at risk, median survival time, and Cox-PH summary.
+
+
Plot can now display any combination of the annotation tables for number of patients at risk, median survival time, and Cox-PH summary.
Function will return a warning instead of an error if the arm variable includes a single level and annot_coxph = TRUE.
Lines in the plot now start at time 0 and probability 1.
Category labels can include the equals sign.
-
-
+
+
+
+
-
Miscellaneous
-
Fixed day2month and month2day to work with NA data.
+
Miscellaneous
+
+
+
Fixed day2month and month2day to work with NA data.
Added parameters for stat_mean_ci and stat_median_ci so that they may return different outputs.
Added functionality in h_row_counts to handle analysis rows with NULL cells.
Updated LICENCE and README with new package references.
summarize_patients_exposure_in_cols tabulates patient counts and sum of exposure across all patients.
-
-
+
+
+
+
-
Enhancements
-
Enhanced MMRM-related functions for fitting models without arm variable.
+
Enhancements
+
+
+
Enhanced MMRM-related functions for fitting models without arm variable.
Updated cox_regression to work without covariates. Also in case of interaction model summary, p-values for main effect coefficients are no longer displayed.
Descriptive statistics returned by summarize_vars now include quantiles. summarize_vars now accepts the control function control_summarize_vars to specify details about confidence level for mean and median and quantile details. The control argument replaces conf_level.
Added var_labels and show_labels arguments to count_occurrences_by_grade.
Changed indent argument in append_varlabels to accept non-negative integer to represent the indent space defined by user. Previous calls with Boolean indent will do an integer conversion and produce a warning.
-
+
+
-
Bug Fixes
-
Corrected tabulate_survival_subgroups and related survival forest plot functions to use total number of events, instead of observations, as default for scaling the symbol sizes in the plot. (The user might still use total number of observations manually if they wish to do so.)
+
Bug Fixes
+
+
+
Corrected tabulate_survival_subgroups and related survival forest plot functions to use total number of events, instead of observations, as default for scaling the symbol sizes in the plot. (The user might still use total number of observations manually if they wish to do so.)
Helper function h_adsl_adlb_merge_using_worst_flag will now impute BTOXGR for missing visits.
-
+
+
-
Miscellaneous
-
Deleted count_abnormal_by_worst_grade_by_baseline and its related statistic and analysis functions as a simpler design will create lab abnormality tables.
+
Miscellaneous
+
+
+
Deleted count_abnormal_by_worst_grade_by_baseline and its related statistic and analysis functions as a simpler design will create lab abnormality tables.
Switched data in examples to use scda instead of random.cdisc.data package.
-
+
+
-
tern 0.7.3
+
tern 0.7.3
+
-
New Features
-
Added Subgroup Treatment Effect Pattern (STEP) model fitting functions fit_rsp_step and fit_survival_step, the corresponding tidy method tidy.step as well as the graph function g_step.
+
New Features
+
+
+
Added Subgroup Treatment Effect Pattern (STEP) model fitting functions fit_rsp_step and fit_survival_step, the corresponding tidy method tidy.step as well as the graph function g_step.
Added new layout function compare_vars which compares variables of different types between columns and produces a p-value for the comparison to the reference column. Function built on top of the summarize_vars functionality.
Added utility functions:
-
+
+
cut_quantile_bins cuts a numeric vector into quantile bins.
fct_collapse_only collapses levels of a factor and keeps those in the order provided.
range_noinf is a kind of a wrapper function of base::range. It returns c(NA, NA) instead of c(-Inf, Inf) for zero-length data.
-
-
+
+
+
+
-
Enhancements
-
Cox regression via fit_coxreg_univar and fit_coxreg_multivar is now also possible without treatment arm. In the univariate case this means that it fits separate univariate models for the provided covariates and tabulation of corresponding effect estimates can later occur.
+
Enhancements
+
+
+
Cox regression via fit_coxreg_univar and fit_coxreg_multivar is now also possible without treatment arm. In the univariate case this means that it fits separate univariate models for the provided covariates and tabulation of corresponding effect estimates can later occur.
Added fraction in result returned by s_count_occurrences. It contains a list of numerators and denominators with one element per occurrence.
Updated sum_num_patients and count_occurrences for the result unique and count_fraction to return (0, 0) when input is empty.
Added a new argument groups_lists to extract_survival_subgroups, extract_rsp_subgroups and associated helper functions which allows to group factor levels of subgroup variables into manually defined groups, enhancing the flexibility of the resulting forest graphs.
Forest graph function g_forest now extracts default arguments from attributes of the input table produced by tabulate_rsp_subgroups and tabulate_survival_subgroups so that the user does not have to do this manually anymore.
In g_km:
-
Remove arm variable name from arm labels in plot legend and annotation tables.
+
+
Remove arm variable name from arm labels in plot legend and annotation tables.
Show symbol used to mark censored cases and match order of arm variable factor levels in the legend.
Display hazard ratio and its confidence interval to two decimal places.
Updated default position of hazard ratio table to stay on the left bottom corner but above x-axis.
Use arm value as strata name in when treatment arm variable has a single level.
-
+
+
Updated s_surv_time function to use a newly created function range_noinf instead of base::range.
New argument no_fillin_visits added to h_adsl_adlb_merge_using_worst_flag to specify excluded visits from the post-baseline worst toxicity grade output. Improved h_adsl_adlb_merge_using_worst_flag to include variables shared between adsl and adlb, along with PARAM, PARAMCD, ATOXGR, BTOXGR and optionally AVISIT, AVISITN when by_visit = TRUE. Prior output contained USUBJID, ARMCD, PARAMCD, ATOXGR, and BTOXGR.
-
+
+
-
Bug Fixes
-
Fix bug in s_surv_timepoint for cases when there are zero patients at risk.
+
Bug Fixes
+
+
+
Fix bug in s_surv_timepoint for cases when there are zero patients at risk.
Modified stat_median_ci function so that when passing empty var with empty name, no row names contain missing values error would show.
-
+
+
-
Miscellaneous
-
Deprecated s_cox_univariate function, use fit_coxreg_univar function instead.
+
Miscellaneous
+
+
+
Deprecated s_cox_univariate function, use fit_coxreg_univar function instead.
Updated default formats of hr and hr_ci in a_coxph_pairwise and median in s_surv_time to align with STREAM.
Updated the pre-processing code in the files test-table_ttet01.R and test-table_dort01.R to make sure the analysis variable EVNT1 has both levels of the factor defined.
Improved error message when number of levels in a factor variable in a data frame is not as expected.
-
+
+
-
tern 0.7.2
-
Fixed column label internal test errors.
-
+
tern 0.7.2
+
+
+
Fixed column label internal test errors.
+
+
-
tern 0.7.1
-
New argument position_surv_med added to g_km to move position of the annotation table with median survival times.
+
tern 0.7.1
+
+
+
New argument position_surv_med added to g_km to move position of the annotation table with median survival times.
Fixed bug in g_km related to the ignored arguments pch and size which were not passed on to helper function h_ggkm.
Updated xticks and max_time arguments in g_km for greater functionality. max_time added as an argument in h_xticks to allow this.
Fixed bug in prop_diff_cmh that led to NaN weighted proportion difference estimates and missing confidence intervals. Before this change, when including no patients from one treatment arm for at least one stratum the estimation did not lead to numeric results.
This version of tern introduces a major rewriting of tern due to the change to layout based tabulation in rtables. tern now does not build tables directly anymore, instead it provides analysis functions to build tables, see the examples. * Counting patients with abnormal values post-baseline with count_abnormal. * Counting patients with graded abnormal values with count_abnormal_by_worst_grade. * Counting patients with abnormal values by baseline status with count_abnormal_by_baseline. * Counting patients with missed doses with s_count_missed_doses and count_missed_doses. * Counting patients with event flags with count_patients_with_event and count_patients_with_flags. * Summarizing variables with summarize_vars (supports numeric, factor, character and logical variables). Note that factors need to have NAs converted to na_level before use. * Summarizing change from baseline with summarize_change. * Summarizing variables in columns with summarize_colvars. * Estimating difference for responder proportions with estimate_proportion_diff. * Estimating difference for Odds Ratio with estimate_odds_ratio. * Testing the difference in responder proportions with test_proportion_diff. * Estimating the responder proportion for the level of a factor with estimate_multinomial_response. * Fitting and tabulating the results of Cox regressions with fit_coxreg_univar, fit_coxreg_multivar and summarize_coxreg, respectively. * Pruning occurrence tables (or tables with counts and fractions) with flexible rules, see ?prune_occurrences for details. * Sorting occurrence tables using different options, see ?score_occurrences for details. * Fitting and tabulating MMRM models with fit_mmrm and as.rtable and summarize_lsmeans, see ?tabulate_mmrm for details. * Counting the number of unique and non-unique patients with summarize_num_patients. * Counting occurrences with count_occurrences. * Counting occurrences by grade with summarize_occurrences_by_grade and count_occurrences_by_grade. * Counting patients and events in columns with summarize_patients_events_in_cols. * Tabulating the binary outcome response by subgroup with extract_rsp_subgroups and tabulate_rsp_subgroups. * Tabulating the survival duration by subgroup with extract_survival_subgroups and tabulate_survival_subgroups.
-
tern 0.6.9
-
Removing not used imports.
-
+
tern 0.6.9
+
+
+
Removing not used imports.
+
+
-
tern 0.6.8
-
Improved handling of missing data in aggregation functions: a_mean_sd, a_median, a_n_true_and_freq, a_count, a_q1q3, a_iqr, a_range.
+
tern 0.6.8
+
+
+
Improved handling of missing data in aggregation functions: a_mean_sd, a_median, a_n_true_and_freq, a_count, a_q1q3, a_iqr, a_range.
New default p-value method in s_test_proportion_diff: Chi-Squared Test with Schouten Correction.
Add new function t_contingency for contingency tables.
Renamed the class splitText to dynamicSplitText to resolve the name conflict with the package ggpubr.
For functions with row_by argument, inputs no longer require use of nested_by.
+
tern 0.6.7
+
+
+
For functions with row_by argument, inputs no longer require use of nested_by.
Add stat_mean_ci and stat_median_ci for error bars in ggplot2.
Add new tern function t_coxreg as single interface for diverse cox regression types.
Add compound table for binary endpoint: t_binary_endpoint and elementary functions: t_el_proportion, t_el_proportion_diff and t_el_test_proportion_diff. The supporting summary functions added are: s_proportion, s_adj_proportion_diff, s_proportion_diff and s_test_proportion_diff.
+
+
@@ -81,13 +144,17 @@
id (defaults to USUBJID), a variable to indicate unique subject identifiers, and baseline
(defaults to BNRIND), a variable to indicate baseline reference ranges.
For each direction specified via the abnormal parameter (e.g. High or Low), a fraction of
-patient counts is returned, with numerator and denominator calculated as follows:
num: The number of patients with this abnormality recorded while on treatment.
+patient counts is returned, with numerator and denominator calculated as follows:
+
+
num: The number of patients with this abnormality recorded while on treatment.
denom: The total number of patients with at least one post-baseline assessment.
-
This function assumes that df has been filtered to only include post-baseline records.
+
+
This function assumes that df has been filtered to only include post-baseline records.
-
Usage
+
Usage
+
count_abnormal(lyt,var,
@@ -122,106 +189,139 @@
Usage
-
Arguments
+
Arguments
+
-
lyt
+
+
lyt
+
(PreDataTableLayouts) layout that analyses will be added to.
-
abnormal
+
abnormal
+
(named list) list identifying the abnormal range level(s) in var. Defaults to
list(Low = "LOW", High = "HIGH") but you can also group different levels into the named list,
for example, abnormal = list(Low = c("LOW", "LOW LOW"), High = c("HIGH", "HIGH HIGH")).
-
variables
+
variables
+
(named list of string) list of additional analysis variables.
-
exclude_base_abn
+
exclude_base_abn
+
(flag) whether to exclude subjects with baseline abnormality
from numerator and denominator.
-
na_str
+
na_str
+
(string) string used to replace all NA or empty values in the output.
-
nested
+
nested
+
(flag) whether this layout instruction should be applied within the existing layout structure _if
possible (TRUE, the default) or as a new top-level element (FALSE). Ignored if it would nest a split.
underneath analyses, which is not allowed.
-
...
+
...
+
additional arguments for the lower level functions.
-
table_names
+
table_names
+
(character) this can be customized in the case that the same vars are analyzed multiple
times, to avoid warnings from rtables.
-
.stats
-
(character) statistics to select for the table.
-
Options are: 'fraction'
+
.stats
+
+
+
(character) statistics to select for the table.
+
Options are: 'fraction'
+
-
.formats
+
.formats
+
(named character or list) formats for the statistics. See Details in analyze_vars for more
information on the "auto" setting.
-
.labels
+
.labels
+
(named character) labels for the statistics (without indent).
-
.indent_mods
+
.indent_mods
+
(named integer) indent modifiers for the labels. Defaults to 0, which corresponds to the
unmodified default behavior. Can be negative.
-
df
+
df
+
(data.frame) data set containing all analysis variables.
-
.var, var
+
.var, var
+
(string) single variable name that is passed by rtables when requested
by a statistics function.
-
+
+
-
Value
+
Value
+
-
count_abnormal() returns a layout object suitable for passing to further layouting functions,
+
+
count_abnormal() returns a layout object suitable for passing to further layouting functions,
or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing
the statistics from s_count_abnormal() to the table layout.
-
s_count_abnormal() returns the statistic fraction which is a vector with num and denom counts of patients.
-
a_count_abnormal() returns the corresponding list with formatted rtables::CellValue().
-
+
+
+
s_count_abnormal() returns the statistic fraction which is a vector with num and denom counts of patients.
+
+
+
a_count_abnormal() returns the corresponding list with formatted rtables::CellValue().
+
+
-
Functions
+
Functions
+
-
count_abnormal(): Layout-creating function which can take statistics function arguments
+
+
count_abnormal(): Layout-creating function which can take statistics function arguments
and additional format arguments. This function is a wrapper for rtables::analyze().
s_count_abnormal(): Statistics function which counts patients with abnormal range values
for a single abnormal level.
a_count_abnormal(): Formatted analysis function which is used as afun in count_abnormal().
-
+
+
-
Note
+
Note
+
-
count_abnormal() only considers a single variable that contains multiple abnormal levels.
+
+
count_abnormal() only considers a single variable that contains multiple abnormal levels.
df should be filtered to only include post-baseline records.
The denominator includes patients that may have other abnormal levels at baseline,
and patients missing baseline records. Patients with these abnormalities at
baseline can be optionally excluded from numerator and denominator via the
exclude_base_abn parameter.
For each direction specified via the abnormal parameter (e.g. High or Low), we condition on baseline
range result and count patients in the numerator and denominator as follows for each of the following
-categories:
Not <abnormality>
num: The number of patients without abnormality at baseline (excluding those with missing baseline)
+categories:
+
+
+
Not <abnormality>
+
+
num: The number of patients without abnormality at baseline (excluding those with missing baseline)
and with at least one abnormality post-baseline.
denom: The number of patients without abnormality at baseline (excluding those with missing baseline).
-
-
<Abnormality>
num: The number of patients with abnormality as baseline and at least one abnormality post-baseline.
+
+
+
+
<Abnormality>
+
+
num: The number of patients with abnormality as baseline and at least one abnormality post-baseline.
denom: The number of patients with abnormality at baseline.
-
-
Total
num: The number of patients with at least one post-baseline record and at least one abnormality
+
+
+
+
Total
+
+
num: The number of patients with at least one post-baseline record and at least one abnormality
post-baseline.
denom: The number of patients with at least one post-baseline record.
-
-
This function assumes that df has been filtered to only include post-baseline records.
+
+
+
+
This function assumes that df has been filtered to only include post-baseline records.
(PreDataTableLayouts) layout that analyses will be added to.
-
abnormal
+
abnormal
+
(character) values identifying the abnormal range level(s) in .var.
-
variables
+
variables
+
(named list of string) list of additional analysis variables.
-
na_str
+
na_str
+
(string) the explicit na_level argument you used in the pre-processing steps (maybe with
df_explicit_na()). The default is "<Missing>".
-
nested
+
nested
+
(flag) whether this layout instruction should be applied within the existing layout structure _if
possible (TRUE, the default) or as a new top-level element (FALSE). Ignored if it would nest a split.
underneath analyses, which is not allowed.
-
...
+
...
+
additional arguments for the lower level functions.
-
table_names
+
table_names
+
(character) this can be customized in the case that the same vars are analyzed multiple
times, to avoid warnings from rtables.
-
.stats
-
(character) statistics to select for the table.
-
Options are: 'fraction'
+
.stats
+
+
+
(character) statistics to select for the table.
+
Options are: 'fraction'
+
-
.formats
+
.formats
+
(named character or list) formats for the statistics. See Details in analyze_vars for more
information on the "auto" setting.
-
.labels
+
.labels
+
(named character) labels for the statistics (without indent).
-
.indent_mods
+
.indent_mods
+
(named integer) indent modifiers for the labels. Defaults to 0, which corresponds to the
unmodified default behavior. Can be negative.
-
df
+
df
+
(data.frame) data set containing all analysis variables.
-
.var, var
+
.var, var
+
(string) single variable name that is passed by rtables when requested
by a statistics function.
-
+
+
-
Value
+
Value
+
-
count_abnormal_by_baseline() returns a layout object suitable for passing to further layouting functions,
+
+
count_abnormal_by_baseline() returns a layout object suitable for passing to further layouting functions,
or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing
the statistics from s_count_abnormal_by_baseline() to the table layout.
-
s_count_abnormal_by_baseline() returns statistic fraction which is a named list with 3 labeled elements:
+
+
+
s_count_abnormal_by_baseline() returns statistic fraction which is a named list with 3 labeled elements:
not_abnormal, abnormal, and total. Each element contains a vector with num and denom patient counts.
-
a_count_abnormal_by_baseline() returns the corresponding list with formatted rtables::CellValue().
-
+
+
+
a_count_abnormal_by_baseline() returns the corresponding list with formatted rtables::CellValue().
+
+
-
Functions
+
Functions
+
-
count_abnormal_by_baseline(): Layout-creating function which can take statistics function arguments
+
+
count_abnormal_by_baseline(): Layout-creating function which can take statistics function arguments
and additional format arguments. This function is a wrapper for rtables::analyze().
s_count_abnormal_by_baseline(): Statistics function for a single abnormal level.
a_count_abnormal_by_baseline(): Formatted analysis function which is used as afun
in count_abnormal_by_baseline().
-
+
+
-
Note
+
Note
+
-
df should be filtered to include only post-baseline records.
+
+
df should be filtered to include only post-baseline records.
If the baseline variable or analysis variable contains NA records, it is expected that df has been
pre-processed using df_explicit_na() or explicit_na().
+
+
@@ -98,17 +161,21 @@
variable to indicate parameter values, and direction (defaults to abn_dir), a variable to indicate
abnormality directions.
For each combination of param and direction levels, marked lab abnormality counts are calculated
-as follows:
Single, not last & Last or replicated: The number of patients with Single, not last
+as follows:
+
+
Single, not last & Last or replicated: The number of patients with Single, not last
and Last or replicated values, respectively.
Any: The number of patients with either single or replicated marked abnormalities.
-
Fractions are calculated by dividing the above counts by the number of patients with at least one
+
+
Fractions are calculated by dividing the above counts by the number of patients with at least one
valid measurement recorded during the analysis.
Prior to using this function in your table layout you must use rtables::split_rows_by() to create two
row splits, one on variable param and one on variable direction.
(PreDataTableLayouts) layout that analyses will be added to.
-
category
+
category
+
(list) a list with different marked category names for single
and last or replicated.
-
variables
+
variables
+
(named list of string) list of additional analysis variables.
-
na_str
+
na_str
+
(string) string used to replace all NA or empty values in the output.
-
nested
+
nested
+
(flag) whether this layout instruction should be applied within the existing layout structure _if
possible (TRUE, the default) or as a new top-level element (FALSE). Ignored if it would nest a split.
underneath analyses, which is not allowed.
-
...
+
...
+
additional arguments for the lower level functions.
(named character or list) formats for the statistics. See Details in analyze_vars for more
information on the "auto" setting.
-
.labels
+
.labels
+
(named character) labels for the statistics (without indent).
-
.indent_mods
+
.indent_mods
+
(named integer) indent modifiers for the labels. Defaults to 0, which corresponds to the
unmodified default behavior. Can be negative.
-
df
+
df
+
(data.frame) data set containing all analysis variables.
-
.var, var
+
.var, var
+
(string) single variable name that is passed by rtables when requested
by a statistics function.
-
.spl_context
+
.spl_context
+
(data.frame) gives information about ancestor split states
that is passed by rtables.
-
+
+
-
Value
+
Value
+
-
count_abnormal_by_marked() returns a layout object suitable for passing to further layouting functions,
+
+
count_abnormal_by_marked() returns a layout object suitable for passing to further layouting functions,
or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing
the statistics from s_count_abnormal_by_marked() to the table layout.
-
s_count_abnormal_by_marked() returns statistic count_fraction with Single, not last,
+
+
+
s_count_abnormal_by_marked() returns statistic count_fraction with Single, not last,
Last or replicated, and Any results.
-
a_count_abnormal_by_marked() returns the corresponding list with formatted rtables::CellValue().
-
+
+
+
a_count_abnormal_by_marked() returns the corresponding list with formatted rtables::CellValue().
+
+
-
Functions
+
Functions
+
-
count_abnormal_by_marked(): Layout-creating function which can take statistics function arguments
+
+
count_abnormal_by_marked(): Layout-creating function which can take statistics function arguments
and additional format arguments. This function is a wrapper for rtables::analyze().
s_count_abnormal_by_marked(): Statistics function for patients with marked lab abnormalities.
a_count_abnormal_by_marked(): Formatted analysis function which is used as afun
in count_abnormal_by_marked().
-
+
+
-
Note
+
Note
+
Single, not last and Last or replicated levels are mutually exclusive. If a patient has
abnormalities that meet both the Single, not last and Last or replicated criteria, then the
patient will be counted only under the Last or replicated category.
+
+
@@ -96,9 +159,12 @@
to indicate parameter values, and grade_dir (defaults to GRADE_DIR), a variable to indicate directions
(e.g. High or Low) for each toxicity grade supplied in var.
For each combination of param and grade_dir levels, patient counts by worst
-grade are calculated as follows:
1 to 4: The number of patients with worst grades 1-4, respectively.
+grade are calculated as follows:
+
+
1 to 4: The number of patients with worst grades 1-4, respectively.
Any: The number of patients with at least one abnormality (i.e. grade is not 0).
-
Fractions are calculated by dividing the above counts by the number of patients with at least one
+
+
Fractions are calculated by dividing the above counts by the number of patients with at least one
valid measurement recorded during treatment.
Pre-processing is crucial when using this function and can be done automatically using the
h_adlb_abnormal_by_worst_grade() helper function. See the description of this function for details on the
@@ -108,7 +174,8 @@
(PreDataTableLayouts) layout that analyses will be added to.
-
variables
+
variables
+
(named list of string) list of additional analysis variables.
-
na_str
+
na_str
+
(string) string used to replace all NA or empty values in the output.
-
nested
+
nested
+
(flag) whether this layout instruction should be applied within the existing layout structure _if
possible (TRUE, the default) or as a new top-level element (FALSE). Ignored if it would nest a split.
underneath analyses, which is not allowed.
-
...
+
...
+
additional arguments for the lower level functions.
(named character or list) formats for the statistics. See Details in analyze_vars for more
information on the "auto" setting.
-
.labels
+
.labels
+
(named character) labels for the statistics (without indent).
-
.indent_mods
+
.indent_mods
+
(named integer) indent modifiers for the labels. Defaults to 0, which corresponds to the
unmodified default behavior. Can be negative.
-
df
+
df
+
(data.frame) data set containing all analysis variables.
-
.var, var
+
.var, var
+
(string) single variable name that is passed by rtables when requested
by a statistics function.
-
.spl_context
+
.spl_context
+
(data.frame) gives information about ancestor split states
that is passed by rtables.
-
+
+
-
Value
+
Value
+
-
count_abnormal_by_worst_grade() returns a layout object suitable for passing to further layouting functions,
+
+
count_abnormal_by_worst_grade() returns a layout object suitable for passing to further layouting functions,
or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing
the statistics from s_count_abnormal_by_worst_grade() to the table layout.
-
s_count_abnormal_by_worst_grade() returns the single statistic count_fraction with grades 1 to 4 and
+
+
+
s_count_abnormal_by_worst_grade() returns the single statistic count_fraction with grades 1 to 4 and
"Any" results.
-
a_count_abnormal_by_worst_grade() returns the corresponding list with formatted rtables::CellValue().
-
+
+
+
a_count_abnormal_by_worst_grade() returns the corresponding list with formatted rtables::CellValue().
+
+
-
Functions
+
Functions
+
-
count_abnormal_by_worst_grade(): Layout-creating function which can take statistics function arguments
+
+
count_abnormal_by_worst_grade(): Layout-creating function which can take statistics function arguments
and additional format arguments. This function is a wrapper for rtables::analyze().
s_count_abnormal_by_worst_grade(): Statistics function which counts patients by worst grade.
a_count_abnormal_by_worst_grade(): Formatted analysis function which is used as afun
in count_abnormal_by_worst_grade().
+
+
@@ -92,17 +155,21 @@
baseline toxicity grades, and direction_var (defaults to GRADDIR), a variable to indicate toxicity grade
directions of interest to include (e.g. "H" (high), "L" (low), or "B" (both)).
For the direction(s) specified in direction_var, patient counts by worst grade for patients who have
-worsened from baseline are calculated as follows:
1 to 4: The number of patients who have worsened from their baseline grades with worst
+worsened from baseline are calculated as follows:
+
+
1 to 4: The number of patients who have worsened from their baseline grades with worst
grades 1-4, respectively.
Any: The total number of patients who have worsened from their baseline grades.
-
Fractions are calculated by dividing the above counts by the number of patients who's analysis toxicity grades
+
+
Fractions are calculated by dividing the above counts by the number of patients who's analysis toxicity grades
have worsened from baseline toxicity grades during treatment.
Prior to using this function in your table layout you must use rtables::split_rows_by() to create a row
split on variable direction_var.
(PreDataTableLayouts) layout that analyses will be added to.
-
variables
-
(named list of string) list of additional analysis variables including:
id (string) subject variable name.
+
variables
+
+
+
(named list of string) list of additional analysis variables including:
+
+
id (string) subject variable name.
baseline_var (string) name of the data column containing baseline toxicity variable.
direction_var (string) see direction_var for more details.
-
+
+
-
na_str
+
na_str
+
(string) string used to replace all NA or empty values in the output.
-
nested
+
nested
+
(flag) whether this layout instruction should be applied within the existing layout structure _if
possible (TRUE, the default) or as a new top-level element (FALSE). Ignored if it would nest a split.
underneath analyses, which is not allowed.
-
...
+
...
+
additional arguments for the lower level functions.
-
table_names
+
table_names
+
(character) this can be customized in the case that the same vars are analyzed multiple
times, to avoid warnings from rtables.
-
.stats
-
(character) statistics to select for the table.
-
Options are: 'fraction'
+
.stats
+
+
+
(character) statistics to select for the table.
+
Options are: 'fraction'
+
-
.formats
+
.formats
+
(named character or list) formats for the statistics. See Details in analyze_vars for more
information on the "auto" setting.
-
.labels
+
.labels
+
(named character) labels for the statistics (without indent).
-
.indent_mods
+
.indent_mods
+
(named integer) indent modifiers for the labels. Defaults to 0, which corresponds to the
unmodified default behavior. Can be negative.
-
df
+
df
+
(data.frame) data set containing all analysis variables.
-
.var, var
+
.var, var
+
(string) single variable name that is passed by rtables when requested
by a statistics function.
-
+
+
-
Value
+
Value
+
-
count_abnormal_lab_worsen_by_baseline() returns a layout object suitable for passing to further layouting
+
+
count_abnormal_lab_worsen_by_baseline() returns a layout object suitable for passing to further layouting
functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted
rows containing the statistics from s_count_abnormal_lab_worsen_by_baseline() to the table layout.
-
s_count_abnormal_lab_worsen_by_baseline() returns the counts and fraction of patients whose worst
+
+
+
s_count_abnormal_lab_worsen_by_baseline() returns the counts and fraction of patients whose worst
post-baseline lab grades are worse than their baseline grades, for post-baseline worst grades
"1", "2", "3", "4" and "Any".
-
a_count_abnormal_lab_worsen_by_baseline() returns the corresponding list with
+
+
+
a_count_abnormal_lab_worsen_by_baseline() returns the corresponding list with
formatted rtables::CellValue().
-
+
+
-
Functions
+
Functions
+
-
count_abnormal_lab_worsen_by_baseline(): Layout-creating function which can take statistics function
+
+
count_abnormal_lab_worsen_by_baseline(): Layout-creating function which can take statistics function
arguments and additional format arguments. This function is a wrapper for rtables::analyze().
s_count_abnormal_lab_worsen_by_baseline(): Statistics function for patients whose worst post-baseline
lab grades are worse than their baseline grades.
a_count_abnormal_lab_worsen_by_baseline(): Formatted analysis function which is used as afun
in count_abnormal_lab_worsen_by_baseline().
-
+
+
-
See also
+
See also
+
Relevant helper functions h_adlb_worsen() and h_worsen_counter() which are used within
s_count_abnormal_lab_worsen_by_baseline() to process input data.
-
Examples
+
Examples
+
library(dplyr)# The direction variable, GRADDR, is based on metadata
@@ -291,17 +391,19 @@
Examples
+
+
-
+
+
-
+
+
diff --git a/main/reference/add_riskdiff.html b/main/reference/add_riskdiff.html
index 002e828c14..e392cb7965 100644
--- a/main/reference/add_riskdiff.html
+++ b/main/reference/add_riskdiff.html
@@ -1,13 +1,36 @@
-
-Split function to configure risk difference column — add_riskdiff • tern
+
+
+
+
+
+Split function to configure risk difference column — add_riskdiff • tern
+
+
+
+
+
+
+
+
+
+
+
+
+
+riskdiff to TRUE in all following analyze function calls.">
+
+
+
+
+
Skip to contents
@@ -23,26 +46,66 @@
(string) name of reference arm to use in risk difference calculations.
-
arm_y
+
arm_y
+
(character) names of one or more arms to compare to reference arm in risk difference
calculations. A new column will be added for each value of arm_y.
-
col_label
+
col_label
+
(character) labels to use when rendering the risk difference column within the table.
If more than one comparison arm is specified in arm_y, default labels will specify which two arms are
being compared (reference arm vs. comparison arm).
-
pct
+
pct
+
(flag) whether output should be returned as percentages. Defaults to TRUE.
-
+
+
-
Value
+
Value
+
A closure suitable for use as a split function (split_fun) within rtables::split_cols_by()
when creating a table layout.
(data.frame) data set containing all analysis variables.
-
labelstr
+
labelstr
+
(string) label of the level of the parent split currently being summarized
(must be present as second argument in Content Row Functions). See rtables::summarize_row_groups()
for more information.
-
.var
+
.var
+
(string) single variable name that is passed by rtables when requested
by a statistics function.
-
.N_col
+
.N_col
+
(integer(1)) column-wise N (column count) for the full column being analyzed that is typically
passed by rtables.
-
.N_row
+
.N_row
+
(integer(1)) row-wise N (row group count) for the group of observations being analyzed
(i.e. with no column-based subsetting) that is typically passed by rtables.
-
.df_row
+
.df_row
+
(data.frame) data frame across all of the columns for the given row split.
-
.spl_context
+
.spl_context
+
(data.frame) gives information about ancestor split states
that is passed by rtables.
-
.all_col_counts
+
.all_col_counts
+
(integer) vector where each value represents a global count for a column. Values are
taken from alt_counts_df if specified (see rtables::build_table()).
-
.stats
+
.stats
+
(character) statistics to select for the table.
-
.formats
+
.formats
+
(named character or list) formats for the statistics. See Details in analyze_vars for more
information on the "auto" setting.
-
.labels
+
.labels
+
(named character) labels for the statistics (without indent).
-
.indent_mods
+
.indent_mods
+
(named integer) indent modifiers for the labels. Defaults to 0, which corresponds to the
unmodified default behavior. Can be negative.
-
na_str
+
na_str
+
(string) string used to replace all NA or empty values in the output.
-
afun
+
afun
+
(named list) a named list containing one name-value pair where the name corresponds to
the name of the statistics function that should be used in calculations and the value is the corresponding
analysis function.
-
s_args
+
s_args
+
(named list) additional arguments to be passed to the statistics function and analysis
function supplied in afun.
Split function add_riskdiff() which, when used as split_fun within rtables::split_cols_by() with
riskdiff argument set to TRUE in subsequent analyze functions calls, adds a risk difference column
to a table layout.
These functions are wrappers of rtables::analyze_colvars() which apply corresponding tern
statistics functions to add an analysis to a given table layout. In particular, these functions
-where designed to have the analysis methods split into different columns.
analyze_vars_in_cols(): fundamental tabulation of analysis methods onto columns.
+where designed to have the analysis methods split into different columns.
+
+
analyze_vars_in_cols(): fundamental tabulation of analysis methods onto columns.
In other words, the analysis methods are defined in the column space, i.e. they become
column labels. By changing the variable vector, the list of functions can be applied on
different variables, with the caveat of having the same number of statistical functions.
@@ -105,28 +170,34 @@
similarly to tabulate_* functions described above as it is designed to provide
specific standard tables that may contain nested structure with a combination of
summarize_row_groups() and rtables::analyze_colvars().
(PreDataTableLayouts) layout that analyses will be added to.
-
vars
+
vars
+
(character) variable names for the primary analysis variable to be iterated over.
-
var_labels
+
var_labels
+
(character) variable labels.
-
na_str
+
na_str
+
(string) string used to replace all NA or empty values in the output.
-
nested
+
nested
+
(flag) whether this layout instruction should be applied within the existing layout structure _if
possible (TRUE, the default) or as a new top-level element (FALSE). Ignored if it would nest a split.
underneath analyses, which is not allowed.
-
...
+
...
+
arguments passed to s_summary().
-
na.rm
+
na.rm
+
(flag) whether NA values should be removed from x prior to analysis.
-
show_labels
+
show_labels
+
(string) label visibility: one of "default", "visible" and "hidden".
-
table_names
+
table_names
+
(character) this can be customized in the case that the same vars are analyzed multiple
times, to avoid warnings from rtables.
-
section_div
+
section_div
+
(string) string which should be repeated as a section divider after each group
defined by this split instruction, or NA_character_ (the default) for no section divider.
(named character or list) formats for the statistics. See Details in analyze_vars for more
information on the "auto" setting.
-
.labels
+
.labels
+
(named character) labels for the statistics (without indent).
-
.indent_mods
+
.indent_mods
+
(named integer) indent modifiers for the labels. Each element of the vector
should be a name-value pair with name corresponding to a statistic specified in .stats and value the indentation
for that statistic's row label.
-
x
+
x
+
(numeric) vector of numbers we want to analyze.
-
denom
-
(string) choice of denominator for proportion. Options are:
n: number of values in this row and column intersection.
+
denom
+
+
+
(string) choice of denominator for proportion. Options are:
+
+
n: number of values in this row and column intersection.
N_row: total number of values in this row across columns.
N_col: total number of values in this column across rows.
-
+
+
-
.N_row
+
.N_row
+
(integer(1)) row-wise N (row group count) for the group of observations being analyzed
(i.e. with no column-based subsetting) that is typically passed by rtables.
-
.N_col
+
.N_col
+
(integer(1)) column-wise N (column count) for the full column being analyzed that is typically
passed by rtables.
-
.var
+
.var
+
(string) single variable name that is passed by rtables when requested
by a statistics function.
-
control
-
(list) parameters for descriptive statistics details, specified by using
-the helper function control_analyze_vars(). Some possible parameter options are:
conf_level (proportion) confidence level of the interval for mean and median.
+
control
+
+
+
(list) parameters for descriptive statistics details, specified by using
+the helper function control_analyze_vars(). Some possible parameter options are:
+
+
conf_level (proportion) confidence level of the interval for mean and median.
quantiles (numeric(2)) vector of length two to specify the quantiles.
quantile_type (numeric(1)) between 1 and 9 selecting quantile algorithms to be used.
See more about type in stats::quantile().
test_mean (numeric(1)) value to test against the mean under the null hypothesis when calculating p-value.
-
+
+
-
verbose
+
verbose
+
(flag) defaults to TRUE, which prints out warnings and messages. It is mainly used
to print out information about factor casting.
-
.df_row
+
.df_row
+
(data.frame) data frame across all of the columns for the given row split.
-
.ref_group
+
.ref_group
+
(data.frame or vector) the data corresponding to the reference group.
-
.in_ref_col
+
.in_ref_col
+
(flag) TRUE when working with the reference level, FALSE otherwise.
-
compare
+
compare
+
(flag) whether comparison statistics should be analyzed instead of summary statistics
(compare = TRUE adds pval statistic comparing against reference group).
-
+
+
-
Value
+
Value
+
-
analyze_vars() returns a layout object suitable for passing to further layouting functions,
+
+
analyze_vars() returns a layout object suitable for passing to further layouting functions,
or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing
the statistics from s_summary() to the table layout.
-
s_summary() returns different statistics depending on the class of x.
-
If x is of class numeric, returns a list with the following named numeric items:
count: A list with the number of cases for each level of the factor x.
count_fraction: Similar to count but also includes the proportion of cases for each level of the
factor x relative to the denominator, or NA if the denominator is zero.
-
-
If x is of class logical, returns a list with named numeric items:
n: The length() of x (possibly after removing NAs).
+
+
+
+
+
+
If x is of class logical, returns a list with named numeric items:
+
+
n: The length() of x (possibly after removing NAs).
count: Count of TRUE in x.
count_fraction: Count and proportion of TRUE in x relative to the denominator, or NA if the
denominator is zero. Note that NAs in x are never counted or leading to NA here.
Automatic digit formatting: The number of digits to display can be automatically determined from the analyzed
variable(s) (vars) for certain statistics by setting the statistic format to "auto" in .formats.
This utilizes the format_auto() formatting function. Note that only data for the current row & variable (for all
columns) will be considered (.df_row[[.var]], see rtables::additional_fun_params) and not the whole dataset.
-
Functions
+
Functions
+
-
analyze_vars(): Layout-creating function which can take statistics function arguments
+
+
analyze_vars(): Layout-creating function which can take statistics function arguments
and additional format arguments. This function is a wrapper for rtables::analyze().
s_summary(): S3 generic function to produces a variable summary.
If x is an empty vector, NA is returned. This is the expected feature so as to return rcell content in
+
+
If x is an empty vector, NA is returned. This is the expected feature so as to return rcell content in
rtables when the intersection of a column and a row delimits an empty data selection.
When the mean function is applied to an empty vector, NA will be returned instead of NaN, the latter
being standard behavior in R.
-
If x is an empty factor, a list is still returned for counts with one element
+
+
+
If x is an empty factor, a list is still returned for counts with one element
per factor level. If there are no levels in x, the function fails.
If factor variables contain NA, these NA values are excluded by default. To include NA values
set na.rm = FALSE and missing values will be displayed as an NA level. Alternatively, an explicit
factor level can be defined for NA values during pre-processing via df_explicit_na() - the
default na_level ("<Missing>") will also be excluded when na.rm is set to TRUE.
-
Automatic conversion of character to factor does not guarantee that the table
+
+
+
Automatic conversion of character to factor does not guarantee that the table
can be generated correctly. In particular for sparse tables this very likely can fail.
It is therefore better to always pre-process the dataset such that factors are manually
created from character variables before passing the dataset to rtables::build_table().
-
To use for comparison (with additional p-value statistic), parameter compare must be set to TRUE.
+
+
+
To use for comparison (with additional p-value statistic), parameter compare must be set to TRUE.
Ensure that either all NA values are converted to an explicit NA level or all NA values are left as is.
(PreDataTableLayouts) layout that analyses will be added to.
-
vars
+
vars
+
(character) variable names for the primary analysis variable to be iterated over.
-
...
+
...
+
additional arguments for the lower level functions.
-
.stats
+
.stats
+
(character) statistics to select for the table.
-
.labels
+
.labels
+
(named character) labels for the statistics (without indent).
-
row_labels
+
row_labels
+
(character) as this function works in columns space, usually .labels
character vector applies on the column space. You can change the row labels by defining this
parameter to a named character vector with names corresponding to the split values. It defaults
to NULL and if it contains only one string, it will duplicate that as a row label.
-
do_summarize_row_groups
+
do_summarize_row_groups
+
(flag) defaults to FALSE and applies the analysis to the current
label rows. This is a wrapper of rtables::summarize_row_groups() and it can accept labelstr
to define row labels. This behavior is not supported as we never need to overload row labels.
-
split_col_vars
+
split_col_vars
+
(flag) defaults to TRUE and puts the analysis results onto the columns.
This option allows you to add multiple instances of this functions, also in a nested fashion,
without adding more splits. This split must happen only one time on a single layout.
-
imp_rule
+
imp_rule
+
(string or NULL) imputation rule setting. Defaults to NULL for no imputation rule. Can
also be "1/3" to implement 1/3 imputation rule or "1/2" to implement 1/2 imputation rule. In order
to use an imputation rule, the avalcat_var argument must be specified. See imputation_rule()
for more details on imputation.
-
avalcat_var
+
avalcat_var
+
(string) if imp_rule is not NULL, name of variable that indicates whether a
row in the data corresponds to an analysis value in category "BLQ", "LTR", "<PCLLOQ", or none of
the above (defaults to "AVALCAT1"). Variable must be present in the data and should match the variable
used to calculate the n_blq statistic (if included in .stats).
-
cache
+
cache
+
(flag) whether to store computed values in a temporary caching environment. This will
speed up calculations in large tables, but should be set to FALSE if the same rtable layout is
used for multiple tables with different data. Defaults to FALSE.
-
.indent_mods
+
.indent_mods
+
(named integer) indent modifiers for the labels. Defaults to 0, which corresponds to the
unmodified default behavior. Can be negative.
-
na_str
+
na_str
+
(string) string used to replace all NA or empty values in the output.
-
nested
+
nested
+
(flag) whether this layout instruction should be applied within the existing layout structure _if
possible (TRUE, the default) or as a new top-level element (FALSE). Ignored if it would nest a split.
underneath analyses, which is not allowed.
-
.formats
+
.formats
+
(named character or list) formats for the statistics. See Details in analyze_vars for more
information on the "auto" setting.
-
.aligns
+
.aligns
+
(character or NULL) alignment for table contents (not including labels). When NULL,
"center" is applied. See formatters::list_valid_aligns() for a list of all currently supported alignments.
-
+
+
-
Value
+
Value
+
A layout object suitable for passing to further layouting functions, or to rtables::build_table().
Adding this function to an rtable layout will summarize the given variables, arrange the output
in columns, and add it to the table layout.
This is an experimental implementation of rtables::summarize_row_groups() and rtables::analyze_colvars()
that may be subjected to changes as rtables extends its support to more complex analysis pipelines in the
column space. We encourage users to read the examples carefully and file issues for different use cases.
In this function, labelstr behaves atypically. If labelstr = NULL (the default), row labels are assigned
automatically as the split values if do_summarize_row_groups = FALSE (the default), and as the group label
if do_summarize_row_groups = TRUE.
(PreDataTableLayouts) layout that analyses will be added to.
-
df
+
df
+
(data.frame) data set containing all analysis variables.
-
vars
+
vars
+
(character) variable names of which the labels are to be looked up in df.
-
indent
+
indent
+
(integer(1)) non-negative number of nested indent space, default to 0L which means no indent.
1L means two spaces indent, 2L means four spaces indent and so on.
-
+
+
-
Value
+
Value
+
A modified layout with the new variable label(s) added to the top-left material.
-
Note
+
Note
+
This is not an optimal implementation of course, since we are using here the data set
itself during the layout creation. When we have a more mature rtables implementation then
this will also be improved or not necessary anymore.
additional arguments for the lower level functions.
-
.aligns
+
.aligns
+
(character or NULL) alignment for table contents (not including labels). When NULL,
"center" is applied. See formatters::list_valid_aligns() for a list of all currently supported alignments.
-
.all_col_counts
+
.all_col_counts
+
(integer) vector where each value represents a global count for a column. Values are
taken from alt_counts_df if specified (see rtables::build_table()).
-
.df_row
+
.df_row
+
(data.frame) data frame across all of the columns for the given row split.
-
.formats
+
.formats
+
(named character or list) formats for the statistics. See Details in analyze_vars for more
information on the "auto" setting.
-
.in_ref_col
+
.in_ref_col
+
(flag) TRUE when working with the reference level, FALSE otherwise.
-
.indent_mods
+
.indent_mods
+
(named integer) indent modifiers for the labels. Defaults to 0, which corresponds to the
unmodified default behavior. Can be negative.
-
.labels
+
.labels
+
(named character) labels for the statistics (without indent).
-
.N_col
+
.N_col
+
(integer(1)) column-wise N (column count) for the full column being analyzed that is typically
passed by rtables.
-
.N_row
+
.N_row
+
(integer(1)) row-wise N (row group count) for the group of observations being analyzed
(i.e. with no column-based subsetting) that is typically passed by rtables.
-
.ref_group
+
.ref_group
+
(data.frame or vector) the data corresponding to the reference group.
-
.spl_context
+
.spl_context
+
(data.frame) gives information about ancestor split states
that is passed by rtables.
-
.stats
+
.stats
+
(character) statistics to select for the table.
-
.var
+
.var
+
(string) single variable name that is passed by rtables when requested
by a statistics function.
-
add_total_level
+
add_total_level
+
(flag) adds a "total" level after the others which includes all the levels
that constitute the split. A custom label can be set for this level via the custom_label argument.
-
col_by
+
col_by
+
(factor) defining column groups.
-
conf_level
+
conf_level
+
(proportion) confidence level of the interval.
-
data
+
data
+
(data.frame) the dataset containing the variables to summarize.
-
denom
-
(string) choice of denominator for proportion. Options are:
n: number of values in this row and column intersection.
+
denom
+
+
+
(string) choice of denominator for proportion. Options are:
+
+
n: number of values in this row and column intersection.
N_row: total number of values in this row across columns.
N_col: total number of values in this column across rows.
-
+
+
-
df
+
df
+
(data.frame) data set containing all analysis variables.
-
groups_lists
+
groups_lists
+
(named list of list) optionally contains for each subgroups variable a
list, which specifies the new group levels via the names and the
levels that belong to it in the character vectors that are elements of the list.
-
id
+
id
+
(string) subject variable name.
-
is_event
+
is_event
+
(flag) TRUE if event, FALSE if time to event is censored.
-
label_all
+
label_all
+
(string) label for the total population analysis.
-
labelstr
+
labelstr
+
(string) label of the level of the parent split currently being summarized
(must be present as second argument in Content Row Functions). See rtables::summarize_row_groups()
for more information.
-
lyt
+
lyt
+
(PreDataTableLayouts) layout that analyses will be added to.
-
method
+
method
+
(string or NULL) specifies the test used to calculate the p-value for the difference between
two proportions. For options, see test_proportion_diff(). Default is NULL so no test is performed.
-
na.rm
+
na.rm
+
(flag) whether NA values should be removed from x prior to analysis.
-
na_str
+
na_str
+
(string) string used to replace all NA or empty values in the output.
-
nested
+
nested
+
(flag) whether this layout instruction should be applied within the existing layout structure _if
possible (TRUE, the default) or as a new top-level element (FALSE). Ignored if it would nest a split.
underneath analyses, which is not allowed.
-
prune_zero_rows
+
prune_zero_rows
+
(flag) whether to prune all zero rows.
-
riskdiff
+
riskdiff
+
(flag) whether a risk difference column is present. When set to TRUE, add_riskdiff() must be
used as split_fun in the prior column split of the table layout, specifying which columns should be compared.
See stat_propdiff_ci() for details on risk difference calculation.
-
rsp
+
rsp
+
(logical) vector indicating whether each subject is a responder or not.
-
show_labels
+
show_labels
+
(string) label visibility: one of "default", "visible" and "hidden".
-
section_div
+
section_div
+
(string) string which should be repeated as a section divider after each group
defined by this split instruction, or NA_character_ (the default) for no section divider.
-
table_names
+
table_names
+
(character) this can be customized in the case that the same vars are analyzed multiple
times, to avoid warnings from rtables.
-
tte
+
tte
+
(numeric) vector of time-to-event duration values.
-
var_labels
+
var_labels
+
(character) variable labels.
-
variables
+
variables
+
(named list of string) list of additional analysis variables.
-
vars
+
vars
+
(character) variable names for the primary analysis variable to be iterated over.
-
var
+
var
+
(string) single variable name for the primary analysis variable.
-
x
+
x
+
(numeric) vector of numbers we want to analyze.
-
xlim
+
xlim
+
(numeric(2)) vector containing lower and upper limits for the x-axis, respectively.
If NULL (default), the default scale range is used.
-
ylim
+
ylim
+
(numeric(2)) vector containing lower and upper limits for the y-axis, respectively.
If NULL (default), the default scale range is used.
-
+
+
-
Details
+
Details
+
Although this function just returns NULL it has two uses, for
the tern users it provides a documentation of arguments that are
commonly and consistently used in the framework. For the developer it adds a
@@ -269,17 +384,19 @@
[character(1)]
Name of the checked object to print in assertions. Defaults to
the heuristic implemented in vname.
-
add
+
add
+
[AssertCollection]
Collection to store assertion messages. See AssertCollection.
-
df
+
df
+
(data.frame) data set to test.
-
variables
+
variables
+
(named list of character) list of variables to test.
-
na_level
+
na_level
+
(string) the string you have been using to represent NA or
missing data. For NA values please consider using directly is.na() or
similar approaches.
-
min.levels
+
min.levels
+
[integer(1)]
Minimum number of factor levels.
Default is NULL (no check).
-
max.levels
+
max.levels
+
[integer(1)]
Maximum number of factor levels.
Default is NULL (no check).
-
null.ok
+
null.ok
+
[logical(1)]
If set to TRUE, x may also be NULL.
In this case only a type check of x is performed, all additional checks are disabled.
-
any.missing
+
any.missing
+
[logical(1)]
Are vectors with missing values allowed? Default is TRUE.
-
n.levels
+
n.levels
+
[integer(1)]
Exact number of factor levels.
Default is NULL (no check).
-
len
+
len
+
[integer(1)]
Exact expected length of x.
-
include_boundaries
+
include_boundaries
+
(flag) whether to include boundaries when testing
for proportions.
-
+
+
-
Value
+
Value
+
Nothing if assertion passes, otherwise prints the error message.
-
Functions
+
Functions
+
-
assert_list_of_variables(): Checks whether x is a valid list of variable names.
+
+
assert_list_of_variables(): Checks whether x is a valid list of variable names.
NULL elements of the list x are dropped with Filter(Negate(is.null), x).
assert_df_with_variables(): Check whether df is a data frame with the analysis variables.
Please notice how this produces an error when not all variables are present in the
@@ -178,20 +262,23 @@
Functionsfactor() will
trim NA levels out of the vector list itself.
assert_proportion_value(): Check whether x is a proportion: number between 0 and 1.
(numeric) the probabilities identifying the quantiles.
This is a sorted vector of unique proportion values, i.e. between 0 and 1, where
the boundaries 0 and 1 must not be included.
-
digits
+
digits
+
(integer(1)) number of decimal places to round the percent numbers.
-
+
+
-
Value
+
Value
+
A character vector with labels in the format [0%,20%], (20%,50%], etc.
+
+
-
+
+
-
+
+
diff --git a/main/reference/c_label_n.html b/main/reference/c_label_n.html
index a996650262..74f8981381 100644
--- a/main/reference/c_label_n.html
+++ b/main/reference/c_label_n.html
@@ -1,9 +1,32 @@
-
-Content row function to add row total to labels — c_label_n • tern
+
+
+
+
+
+Content row function to add row total to labels — c_label_n • tern
+
+
+
+
+
+
+
+
+
+
+
+
+
+alt_counts_df, and is used by add_rowcounts() when alt_counts is set to FALSE.">
+
+
+
+
+
Skip to contents
@@ -19,26 +42,66 @@
(data.frame) data set containing all analysis variables.
-
labelstr
+
labelstr
+
(string) label of the level of the parent split currently being summarized
(must be present as second argument in Content Row Functions). See rtables::summarize_row_groups()
for more information.
-
.N_row
+
.N_row
+
(integer(1)) row-wise N (row group count) for the group of observations being analyzed
(i.e. with no column-based subsetting) that is typically passed by rtables.
-
+
+
-
Value
+
Value
+
A list with formatted rtables::CellValue() with the row count value and the correct label.
-
Note
+
Note
+
It is important here to not use df but rather .N_row in the implementation, because
the former is already split by columns and will refer to the first column of the data only.
-
See also
+
See also
+
c_label_n_alt() which performs the same function but retrieves row counts from
alt_counts_df instead of df.
+
+
-
+
+
-
+
+
diff --git a/main/reference/c_label_n_alt.html b/main/reference/c_label_n_alt.html
index c240df9b67..5ad808fe2f 100644
--- a/main/reference/c_label_n_alt.html
+++ b/main/reference/c_label_n_alt.html
@@ -1,9 +1,32 @@
-
-Content row function to add alt_counts_df row total to labels — c_label_n_alt • tern
+
+
+
+
+
+Content row function to add alt_counts_df row total to labels — c_label_n_alt • tern
+
+
+
+
+
+
+
+
+
+
+
+
+
+rather than df, and is used by add_rowcounts() when alt_counts is set to TRUE.">
+
+
+
+
+
Skip to contents
@@ -19,26 +42,66 @@
(data.frame) data set containing all analysis variables.
-
labelstr
+
labelstr
+
(string) label of the level of the parent split currently being summarized
(must be present as second argument in Content Row Functions). See rtables::summarize_row_groups()
for more information.
-
+
+
-
Value
+
Value
+
A list with formatted rtables::CellValue() with the row count value and the correct label.
-
See also
+
See also
+
c_label_n() which performs the same function but retrieves row counts from df instead
of alt_counts_df.
+
+
-
+
+
-
+
+
diff --git a/main/reference/cfun_by_flag.html b/main/reference/cfun_by_flag.html
index 2fd5bb597b..8bc81730c6 100644
--- a/main/reference/cfun_by_flag.html
+++ b/main/reference/cfun_by_flag.html
@@ -1,5 +1,28 @@
-
-Constructor for content functions given a data frame with flag input — cfun_by_flag • tern
+
+
+
+
+
+
+Constructor for content functions given a data frame with flag input — cfun_by_flag • tern
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Skip to contents
@@ -15,26 +38,66 @@
# S4 method for class 'CombinationFunction,CombinationFunction'e1&e2
@@ -69,29 +134,38 @@
Usage
-
Arguments
+
Arguments
+
-
e1
+
+
e1
+
(CombinationFunction) left hand side of logical operator.
-
e2
+
e2
+
(CombinationFunction) right hand side of logical operator.
-
x
+
x
+
(CombinationFunction) the function which should be negated.
-
+
+
-
Value
+
Value
+
A logical value indicating whether the left hand side of the equation equals the right hand side.
-
Functions
+
Functions
+
-
e1 & e2: Logical "AND" combination of CombinationFunction functions.
+
+
e1 & e2: Logical "AND" combination of CombinationFunction functions.
The resulting object is of the same class, and evaluates the two argument functions. The result
is then the "AND" of the two individual results.
(factor) the variable with levels which needs to be grouped.
-
groups_list
+
groups_list
+
(named list of character) specifies the new group levels via the names and the
levels that belong to it in the character vectors that are elements of the list.
(PreDataTableLayouts) layout that analyses will be added to.
-
vars
+
vars
+
(character) variable names for the primary analysis variable to be iterated over.
-
var_labels
+
var_labels
+
(character) variable labels.
-
na_str
+
na_str
+
(string) string used to replace all NA or empty values in the output.
-
nested
+
nested
+
(flag) whether this layout instruction should be applied within the existing layout structure _if
possible (TRUE, the default) or as a new top-level element (FALSE). Ignored if it would nest a split.
underneath analyses, which is not allowed.
-
...
+
...
+
arguments passed to s_compare().
-
na.rm
+
na.rm
+
(flag) whether NA values should be removed from x prior to analysis.
-
show_labels
+
show_labels
+
(string) label visibility: one of "default", "visible" and "hidden".
-
table_names
+
table_names
+
(character) this can be customized in the case that the same vars are analyzed multiple
times, to avoid warnings from rtables.
-
section_div
+
section_div
+
(string) string which should be repeated as a section divider after each group
defined by this split instruction, or NA_character_ (the default) for no section divider.
(named character or list) formats for the statistics. See Details in analyze_vars for more
information on the "auto" setting.
-
.labels
+
.labels
+
(named character) labels for the statistics (without indent).
-
.indent_mods
+
.indent_mods
+
(named integer) indent modifiers for the labels. Each element of the vector
should be a name-value pair with name corresponding to a statistic specified in .stats and value the indentation
for that statistic's row label.
-
x
+
x
+
(numeric) vector of numbers we want to analyze.
-
.ref_group
+
.ref_group
+
(data.frame or vector) the data corresponding to the reference group.
-
.in_ref_col
+
.in_ref_col
+
(flag) TRUE when working with the reference level, FALSE otherwise.
-
denom
+
denom
+
(string) choice of denominator for factor proportions,
can only be n (number of values in this row and column intersection).
-
.var
+
.var
+
(string) single variable name that is passed by rtables when requested
by a statistics function.
-
verbose
+
verbose
+
(flag) whether warnings and messages should be printed. Mainly used
to print out information about factor casting. Defaults to TRUE.
-
+
+
-
Value
+
Value
+
-
compare_vars() returns a layout object suitable for passing to further layouting functions,
+
+
compare_vars() returns a layout object suitable for passing to further layouting functions,
or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing
the statistics from s_compare() to the table layout.
-
s_compare() returns output of s_summary() and comparisons versus the reference group in the form of p-values.
-
+
+
+
s_compare() returns output of s_summary() and comparisons versus the reference group in the form of p-values.
+
+
-
Functions
+
Functions
+
-
compare_vars(): Layout-creating function which can take statistics function arguments
+
+
compare_vars(): Layout-creating function which can take statistics function arguments
and additional format arguments. This function is a wrapper for rtables::analyze().
s_compare(): S3 generic function to produce a comparison summary.
s_compare(numeric): Method for numeric class. This uses the standard t-test
@@ -238,11 +334,14 @@
For factor variables, denom for factor proportions can only be n since the purpose is to compare proportions
+
+
For factor variables, denom for factor proportions can only be n since the purpose is to compare proportions
between columns, therefore a row-based proportion would not make sense. Proportion based on N_col would
be difficult since we use counts for the chi-squared test statistic, therefore missing values should be accounted
for as explicit factor levels.
@@ -255,15 +354,18 @@
Note
Therefore it is always better to manually convert character variables to factors during pre-processing.
For compare_vars(), the column split must define a reference group via ref_group so that the comparison
is well defined.
-
+
+
-
See also
+
See also
+
s_summary() which is used internally to compute a summary within s_compare(), and a_summary()
which is used (with compare = TRUE) as the analysis function for compare_vars().
-
Examples
+
Examples
+
# `compare_vars()` in `rtables` pipelines## Default output within a `rtables` pipeline.
@@ -1097,17 +1199,19 @@
Examples
+
+
-
+
+
-
+
+
diff --git a/main/reference/control_analyze_vars.html b/main/reference/control_analyze_vars.html
index 5158bdbf12..9d6fe4c831 100644
--- a/main/reference/control_analyze_vars.html
+++ b/main/reference/control_analyze_vars.html
@@ -1,9 +1,32 @@
-
-Control function for descriptive statistics — control_analyze_vars • tern
+
+
+
+
+
+Control function for descriptive statistics — control_analyze_vars • tern
+
+
+
+
+
+
+
+
+
+
+
+
+
+details for s_summary(). This function family is mainly used by analyze_vars().">
+
+
+
+
+
Skip to contents
@@ -19,26 +42,66 @@
(numeric(2)) vector of length two to specify the quantiles to calculate.
-
quantile_type
+
quantile_type
+
(numeric(1)) number between 1 and 9 selecting quantile algorithms to be used.
Default is set to 2 as this matches the default quantile algorithm in SAS proc univariate set by QNTLDEF=5.
This differs from R's default. See more about type in stats::quantile().
-
test_mean
+
test_mean
+
(numeric(1)) number to test against the mean under the null hypothesis when calculating
p-value.
-
+
+
-
Value
+
Value
+
A list of components with the same names as the arguments.
