diff --git a/DESCRIPTION b/DESCRIPTION index 2fcf743fb5..b78c6f96d8 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: tern Title: Create Common TLGs Used in Clinical Trials -Version: 0.9.6.9005 -Date: 2024-10-09 +Version: 0.9.6.9006 +Date: 2024-10-18 Authors@R: c( person("Joe", "Zhu", , "joe.zhu@roche.com", role = c("aut", "cre")), person("Daniel", "Sabanés Bové", , "daniel.sabanes_bove@roche.com", role = "aut"), diff --git a/NEWS.md b/NEWS.md index ac82f6f010..b8ee450420 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# tern 0.9.6.9005 +# tern 0.9.6.9006 ### Bug Fixes * Fixed bug in `a_summary()` causing non-unique `row_name` values to occur when multiple statistics are selected for count variables. diff --git a/R/bland_altman.R b/R/bland_altman.R index 069887ba2d..f7ce7e3553 100644 --- a/R/bland_altman.R +++ b/R/bland_altman.R @@ -2,29 +2,32 @@ #' #' @description `r lifecycle::badge("experimental")` #' -#' Functions that use the Bland-Altman method to assess the agreement between two numerical vectors. +#' Statistics function that uses the Bland-Altman method to assess the agreement between two numerical vectors +#' and calculates a variety of statistics. #' #' @inheritParams argument_convention #' @param y (`numeric`)\cr vector of numbers we want to analyze, to be compared with `x`. #' -#' @name bland_altman -NULL - -#' @describeIn bland_altman Statistics function that compares two numeric vectors using the Bland-Altman method -#' and calculates a variety of statistics. -#' #' @return -#' * `s_bland_altman()` returns a named list of the following elements: `df`, `difference_mean`, `ci_mean`, -#' `difference_sd`, `difference_se`, `upper_agreement_limit`, `lower_agreement_limit`, `agreement_limit_se`, -#' `upper_agreement_limit_ci`, `lower_agreement_limit_ci`, `t_value`, and `n`. +#' A named list of the following elements: +#' * `df` +#' * `difference_mean` +#' * `ci_mean` +#' * `difference_sd` +#' * `difference_se` +#' * `upper_agreement_limit` +#' * `lower_agreement_limit` +#' * `agreement_limit_se` +#' * `upper_agreement_limit_ci` +#' * `lower_agreement_limit_ci` +#' * `t_value` +#' * `n` #' #' @examples #' x <- seq(1, 60, 5) #' y <- seq(5, 50, 4) -#' conf_level <- 0.9 #' -#' # Derive statistics that are needed for Bland-Altman plot -#' s_bland_altman(x, y, conf_level = conf_level) +#' s_bland_altman(x, y, conf_level = 0.9) #' #' @export s_bland_altman <- function(x, y, conf_level = 0.95) { @@ -75,16 +78,24 @@ s_bland_altman <- function(x, y, conf_level = 0.95) { ) } -#' @describeIn bland_altman Graphing function that produces a Bland-Altman plot. +#' Bland-Altman plot #' -#' @return -#' * `g_bland_altman()` returns a `ggplot` Bland-Altman plot. +#' @description `r lifecycle::badge("experimental")` +#' +#' Graphing function that produces a Bland-Altman plot. +#' +#' @inheritParams s_bland_altman +#' +#' @return A `ggplot` Bland-Altman plot. #' #' @examples -#' # Create a Bland-Altman plot -#' g_bland_altman(x = x, y = y, conf_level = conf_level) +#' x <- seq(1, 60, 5) +#' y <- seq(5, 50, 4) +#' +#' g_bland_altman(x = x, y = y, conf_level = 0.9) #' #' @export +#' @aliases bland_altman g_bland_altman <- function(x, y, conf_level = 0.95) { result_tem <- s_bland_altman(x, y, conf_level = conf_level) xpos <- max(result_tem$df$average) * 0.9 + min(result_tem$df$average) * 0.1 diff --git a/R/formatting_functions.R b/R/formatting_functions.R index 7deb73f2bb..f18409810c 100644 --- a/R/formatting_functions.R +++ b/R/formatting_functions.R @@ -1,7 +1,5 @@ #' Formatting functions #' -#' @description `r lifecycle::badge("stable")` -#' #' See below for the list of formatting functions created in `tern` to work with `rtables`. #' #' Other available formats can be listed via [`formatters::list_valid_format_labels()`]. Additional diff --git a/README.md b/README.md index 0dae397068..37fca43636 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ Data visualizations: - STEP graphs ([`g_step`](https://insightsengineering.github.io/tern/latest-tag/reference/g_step.html)) - Individual patient plots ([`g_ipp`](https://insightsengineering.github.io/tern/latest-tag/reference/g_ipp.html)) - Waterfall plots ([`g_waterfall`](https://insightsengineering.github.io/tern/latest-tag/reference/g_waterfall.html)) +- Bland-Altman plots ([`g_bland_altman`](https://insightsengineering.github.io/tern/latest-tag/reference/g_bland_altman.html)) Statistical model fit summaries: @@ -80,7 +81,7 @@ See package vignettes `browseVignettes(package = "tern")` for usage of this pack ## Acknowledgment -This package is a result of a joint efforts by many developers and stakeholders. We would like to thank everyone who has contributed so far! +This package is the result of the joint efforts by many developers and stakeholders. We would like to thank everyone who has contributed so far! ## Stargazers and Forkers diff --git a/_pkgdown.yml b/_pkgdown.yml index ae5969b54a..b66d1c54bb 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -21,6 +21,7 @@ navbar: github: icon: fa-github href: https://github.com/insightsengineering/tern + aria-label: GitHub reference: - title: Overview Pages @@ -31,13 +32,6 @@ reference: - summarize_functions - formatting_functions - - title: Control Functions - desc: These functions capture options in lists and take care of defaults - (and checks where applicable). They avoid cluttering of function - signatures with long lists of single arguments. - contents: - - starts_with("control_") - - title: Analysis Functions desc: | Analyze functions with their corresponding statistics functions and @@ -61,6 +55,7 @@ reference: - compare_vars - starts_with("count_", internal = TRUE) - starts_with("estimate_", internal = TRUE) + - s_bland_altman - starts_with("summarize_", internal = TRUE) - starts_with("surv_", internal = TRUE) - starts_with("tabulate_", internal = TRUE) @@ -70,6 +65,30 @@ reference: - -estimate_coef - -summarize_functions + - title: Model-Specific Functions + desc: These functions help with fitting or extracting results from specific + models. + contents: + - estimate_coef + - starts_with("extract_") + - starts_with("fit_") + - get_smooths + - starts_with("logistic_") + - starts_with("tidy.") + - univariate + + - title: Graphs + desc: These function create graphical type output. + contents: + - starts_with("g_") + + - title: Control Functions + desc: These functions capture options in lists and take care of defaults + (and checks where applicable). They avoid cluttering of function + signatures with long lists of single arguments. + contents: + - starts_with("control_") + - title: Analysis Helper Functions desc: These functions are useful in defining an analysis. contents: @@ -88,23 +107,6 @@ reference: - -h_xticks - -prop_diff - - title: Model-Specific Functions - desc: These functions help with fitting or extracting results from specific - models. - contents: - - estimate_coef - - starts_with("extract_") - - starts_with("fit_") - - get_smooths - - starts_with("logistic_") - - starts_with("tidy.") - - univariate - - - title: Graphs - desc: These function create graphical type output. - contents: - - starts_with("g_") - - title: rtables Helper Functions desc: These functions help to work with the `rtables` package and may be moved there later. diff --git a/man/bland_altman.Rd b/man/bland_altman.Rd deleted file mode 100644 index 9afa07143d..0000000000 --- a/man/bland_altman.Rd +++ /dev/null @@ -1,55 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/bland_altman.R -\name{bland_altman} -\alias{bland_altman} -\alias{s_bland_altman} -\alias{g_bland_altman} -\title{Bland-Altman analysis} -\usage{ -s_bland_altman(x, y, conf_level = 0.95) - -g_bland_altman(x, y, conf_level = 0.95) -} -\arguments{ -\item{x}{(\code{numeric})\cr vector of numbers we want to analyze.} - -\item{y}{(\code{numeric})\cr vector of numbers we want to analyze, to be compared with \code{x}.} - -\item{conf_level}{(\code{proportion})\cr confidence level of the interval.} -} -\value{ -\itemize{ -\item \code{s_bland_altman()} returns a named list of the following elements: \code{df}, \code{difference_mean}, \code{ci_mean}, -\code{difference_sd}, \code{difference_se}, \code{upper_agreement_limit}, \code{lower_agreement_limit}, \code{agreement_limit_se}, -\code{upper_agreement_limit_ci}, \code{lower_agreement_limit_ci}, \code{t_value}, and \code{n}. -} - -\itemize{ -\item \code{g_bland_altman()} returns a \code{ggplot} Bland-Altman plot. -} -} -\description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} - -Functions that use the Bland-Altman method to assess the agreement between two numerical vectors. -} -\section{Functions}{ -\itemize{ -\item \code{s_bland_altman()}: Statistics function that compares two numeric vectors using the Bland-Altman method -and calculates a variety of statistics. - -\item \code{g_bland_altman()}: Graphing function that produces a Bland-Altman plot. - -}} -\examples{ -x <- seq(1, 60, 5) -y <- seq(5, 50, 4) -conf_level <- 0.9 - -# Derive statistics that are needed for Bland-Altman plot -s_bland_altman(x, y, conf_level = conf_level) - -# Create a Bland-Altman plot -g_bland_altman(x = x, y = y, conf_level = conf_level) - -} diff --git a/man/formatting_functions.Rd b/man/formatting_functions.Rd index 498895be42..b7f7e8d584 100644 --- a/man/formatting_functions.Rd +++ b/man/formatting_functions.Rd @@ -4,10 +4,9 @@ \alias{formatting_functions} \title{Formatting functions} \description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} - See below for the list of formatting functions created in \code{tern} to work with \code{rtables}. - +} +\details{ Other available formats can be listed via \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}}. Additional custom formats can be created via the \code{\link[formatters:sprintf_format]{formatters::sprintf_format()}} function. } diff --git a/man/g_bland_altman.Rd b/man/g_bland_altman.Rd new file mode 100644 index 0000000000..1695e6b38b --- /dev/null +++ b/man/g_bland_altman.Rd @@ -0,0 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/bland_altman.R +\name{g_bland_altman} +\alias{g_bland_altman} +\alias{bland_altman} +\title{Bland-Altman plot} +\usage{ +g_bland_altman(x, y, conf_level = 0.95) +} +\arguments{ +\item{x}{(\code{numeric})\cr vector of numbers we want to analyze.} + +\item{y}{(\code{numeric})\cr vector of numbers we want to analyze, to be compared with \code{x}.} + +\item{conf_level}{(\code{proportion})\cr confidence level of the interval.} +} +\value{ +A \code{ggplot} Bland-Altman plot. +} +\description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + +Graphing function that produces a Bland-Altman plot. +} +\examples{ +x <- seq(1, 60, 5) +y <- seq(5, 50, 4) + +g_bland_altman(x = x, y = y, conf_level = 0.9) + +} diff --git a/man/s_bland_altman.Rd b/man/s_bland_altman.Rd new file mode 100644 index 0000000000..3210000e8f --- /dev/null +++ b/man/s_bland_altman.Rd @@ -0,0 +1,45 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/bland_altman.R +\name{s_bland_altman} +\alias{s_bland_altman} +\title{Bland-Altman analysis} +\usage{ +s_bland_altman(x, y, conf_level = 0.95) +} +\arguments{ +\item{x}{(\code{numeric})\cr vector of numbers we want to analyze.} + +\item{y}{(\code{numeric})\cr vector of numbers we want to analyze, to be compared with \code{x}.} + +\item{conf_level}{(\code{proportion})\cr confidence level of the interval.} +} +\value{ +A named list of the following elements: +\itemize{ +\item \code{df} +\item \code{difference_mean} +\item \code{ci_mean} +\item \code{difference_sd} +\item \code{difference_se} +\item \code{upper_agreement_limit} +\item \code{lower_agreement_limit} +\item \code{agreement_limit_se} +\item \code{upper_agreement_limit_ci} +\item \code{lower_agreement_limit_ci} +\item \code{t_value} +\item \code{n} +} +} +\description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + +Statistics function that uses the Bland-Altman method to assess the agreement between two numerical vectors +and calculates a variety of statistics. +} +\examples{ +x <- seq(1, 60, 5) +y <- seq(5, 50, 4) + +s_bland_altman(x, y, conf_level = 0.9) + +} diff --git a/vignettes/tern.Rmd b/vignettes/tern.Rmd index e3600650f2..86dec5b796 100644 --- a/vignettes/tern.Rmd +++ b/vignettes/tern.Rmd @@ -88,7 +88,7 @@ library(tern) library(dplyr) ``` -Defining the table layout with a pure `rtables` code. +Defining the table layout with a pure `rtables` code: ```{r} # Create table layout pure rtables @@ -98,7 +98,7 @@ lyt <- rtables::basic_table() %>% rtables::analyze(vars = "AVAL", mean, format = "xx.x") ``` -Below the only `tern` function is `analyze_vars` which replaces the `rtables::analyze` function above. +Below, the only `tern` function used is `analyze_vars` which replaces the `rtables::analyze` function used above. ```{r} # Create table layout with tern analyze_vars analyze function @@ -121,11 +121,11 @@ We see that `tern` offers advanced analysis by extending `rtables` function call **More examples with tabulation analyze functions are presented in the `Tabulation` vignette.** -## Clinical Trials Visualizations +## Clinical Trial Visualizations Clinical trial related plots complement the rich palette of `tern` tabulation analysis functions. Thus the `tern` package delivers a full-featured tool for clinical trial reporting. -The `tern` plot functions return `ggplot2` or `gTree` objects, the latter is returned when a table is attached to the plot. +The `tern` plot functions return graphs as `ggplot2` objects. ```{r} adsl <- formatters::ex_adsl @@ -141,15 +141,15 @@ library(nestcolor) Line plot without a table generated by the `g_lineplot` function. -```{r} +```{r, fig.alt='Basic line plot'} # Mean with CI g_lineplot(adlb, adsl, subtitle = "Laboratory Test:") ``` Line plot with a table generated by the `g_lineplot` function. -```{r, fig.height=10, fig.width=8} -# Mean with CI, table and customized confidence level +```{r, fig.height=10, fig.width=8, fig.alt='Line plot with table'} +# Mean with CI, table, and customized confidence level g_lineplot( adlb, adsl, @@ -158,21 +158,15 @@ g_lineplot( ) ``` -The first plot is a `ggplot2` object and the second plot is a `gTree` object, as the latter contains the table. -The second plot has to be properly resized to get a clear and readable table content. - -The `tern` functions used for plot generation are mostly `g_` prefixed. -All `tern` plot functions are listed on [the tern website functions reference](https://insightsengineering.github.io/tern/latest-tag/reference/index.html). +All `tern` functions used for plot generation are `g_` prefixed and are listed on [the tern website functions reference](https://insightsengineering.github.io/tern/latest-tag/reference/index.html#graphs). ## Interactive Apps -Most of `tern` outputs could be easily accommodated into `shiny` apps. -We recommend applying `tern` outputs into `teal` apps. -The [`teal` package](https://insightsengineering.github.io/teal/latest-tag/) is a shiny-based interactive exploration framework for analyzing data. -`teal` shiny apps with `tern` outputs are available in the [`teal.modules.clinical` package](https://insightsengineering.github.io/teal.modules.clinical/latest-tag/). +Most `tern` outputs can be easily converted into `shiny` apps. We recommend building apps using the [`teal` package](https://insightsengineering.github.io/teal/latest-tag/), a shiny-based interactive exploration framework for analyzing data. +A variety of pre-made `teal` shiny apps for `tern` outputs are available in the [`teal.modules.clinical` package](https://insightsengineering.github.io/teal.modules.clinical/latest-tag/). ## Summary -In summary, `tern` contains many additional functions for creating tables, listing and graphs used in clinical trials and other statistical analyses. The design of the package gives users a lot of flexibility to meet the analysis needs in a regulatory or exploratory reporting context. +In summary, `tern` contains many additional functions for creating tables, listings, and graphs used in clinical trials and other statistical analyses. The design of the package gives users the flexibility to meet the analysis needs in both regulatory and exploratory reporting contexts. **For more information please explore [the tern website](https://insightsengineering.github.io/tern/latest-tag/).**