Title:	Tidy Presentation of Clinical Reporting
Version:	0.1.3
Date:	2026-03-20
Description:	Streamlined statistical reporting in 'Rmarkdown' environments. Facilitates the automated reporting of descriptive statistics, multiple univariate models, multivariable models and tables combining these outputs. Plotting functions include customisable survival curves, forest plots from logistic and ordinal regression and bivariate comparison plots.
License:	MIT + file LICENSE
Suggests:	geepack, lme4, lmerTest, MASS, mice, nlme, tidycmprsk, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.2
Imports:	aod, boot, cmprsk, cowplot, dplyr, ggplot2, ggpubr, kableExtra, knitr, lifecycle, pander, rlang, rstudioapi, scales, stats, survival, tidyr, tidyselect
Collate:	'imports.R' 'helper.R' 'model_registry.R' 'main.R' 'globals.R' 'data.R' 'lblCode.R' 'rm_compactsum.R' 'rm_uvsum2.R' 'autoreg.R' 'autosum.R' 'getVarLevels.R' 'ggkmcif3.R' 'rm_mvsum2.R' 'deprecated.R'
Depends:	R (≥ 4.2)
LazyData:	no
URL:	https://biostatspmh.github.io/reportRmd/
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-03-20 15:44:17 UTC; lisaavery
Author:	Lisa Avery [cre, aut], Ryan Del Bel [aut], Osvaldo Espin-Garcia [aut], Katherine Lajkosz [aut], Clarina Ong [aut], Tyler Pittman [aut], Anna Santiago [aut], Yanning Wang [ctr], Jessica Weiss [aut], Wei Xu [aut]
Maintainer:	Lisa Avery <lisa.avery@uhn.ca>
Repository:	CRAN
Date/Publication:	2026-03-20 16:10:03 UTC

Compute Generalized Variance Inflation Factor (GVIF)

Description

Calculates GVIF for model terms to detect multicollinearity. Adapted from the car package.

Usage

GVIF(model)

Arguments

Details

For terms with degrees of freedom > 1 (e.g., factor variables), returns GVIF^(1/(2*df)) for comparability with standard VIF.

Value

Data frame with columns: Covariate (term name) and VIF (value)

References

Fox, J. and Weisberg, S. (2019). An R Companion to Applied Regression, Third Edition. Thousand Oaks CA: Sage.

Add censor marks to KM plot

Description

Add censor marks to KM plot

Usage

add_censor_marks(p, df, censor.size = 0.5, censor.stroke = 1.5, shape = "|")

Arguments

Add CIF Hazard Ratios to Strata Labels

Description

Add CIF Hazard Ratios to Strata Labels

Usage

add_cif_hazard_ratios(
  stratalabs,
  data,
  response,
  cov,
  plot.event = 1,
  HR = FALSE,
  HR_pval = FALSE,
  HR.digits = 2,
  HR.pval.digits = 3
)

Arguments

Value

Updated strata labels

Add confidence bands to plot

Description

Add confidence bands to plot

Usage

add_confidence_bands(p, df, type, event = "col", plot.event = 1)

Arguments

Add hazard ratios to strata labels

Description

Add hazard ratios to strata labels

Usage

add_km_hazard_ratios(
  stratalabs,
  data,
  response,
  cov,
  type,
  plot.event = 1,
  HR = FALSE,
  HR_pval = FALSE,
  HR.digits = 2,
  HR.pval.digits = 3
)

Arguments

Add median survival lines to plot

Description

Add median survival lines to plot

Usage

add_median_lines(p, median_vals, median.lsize = 1)

Arguments

Add median survival text to plot

Description

Add median survival text to plot

Usage

add_median_text(
  p,
  type,
  multiple_lines,
  median_txt,
  median.pos = NULL,
  times,
  ylim,
  median.size = 3,
  plot.event = 1,
  eventlabs = NULL
)

Arguments

Add survival at set time lines to plot

Description

Add survival at set time lines to plot

Usage

add_set_time_lines(p, set.surv, set.lsize = 1)

Arguments

Add survival at set time text to plot

Description

Add survival at set time text to plot

Usage

add_set_time_text(
  p,
  type,
  multiple_lines,
  set.surv.text,
  set.pos = NULL,
  times,
  ylim,
  set.size = 3,
  plot.event = 1,
  eventlabs = NULL
)

Arguments

Add statistical test results to plot

Description

Add statistical test results to plot

Usage

add_statistical_tests(
  p,
  type,
  multiple_lines,
  pval_result,
  pval.pos = NULL,
  times,
  xlim,
  ylim,
  psize = 3.5,
  pval.digits = 3,
  plot.event = 1,
  eventlabs = NULL
)

Arguments

Apply colour and linetype scales

Description

Apply colour and linetype scales

Usage

apply_scales_and_guides(
  p,
  col,
  linetype = NULL,
  stratalabs,
  eventlabs = NULL,
  multiple_lines,
  plot.event = 1,
  event = "col"
)

Arguments

Fit a regression model based on response type

Description

S3 generic that dispatches to the appropriate model fitting function based on the class of the response variable.

Usage

autoreg(
  response,
  data,
  x_var,
  id = NULL,
  strata = "",
  family = NULL,
  offset = NULL,
  corstr = "independence"
)

Arguments

Value

A fitted model object.

fit box cox transformed linear model

Description

Wrapper function to fit fine and gray competing risk model using function crr from package cmprsk

Usage

boxcoxfitRx(f, data, lambda = FALSE)

Arguments

Value

a list containing the linear model (lm) object and, if requested, lambda

Standard break function using pretty()

Description

Creates nice axis breaks using R's built-in pretty() function. This is the standard approach used by ggkmcif functions.

Usage

break_function(x, n = 5)

Arguments

Value

Numeric vector of break positions

Custom break function for axis scaling

Description

Creates axis breaks based on maximum value with custom logic for determining break intervals based on magnitude.

Usage

break_function_custom(xmax)

Arguments

Value

Numeric vector of break positions

Build arrow segments for CIs extending beyond xlim

Description

Returns a list of ggplot layers for left and right arrows.

Usage

build_arrow_segments(tab, xlim, use_linetype = FALSE)

Arguments

Value

list of ggplot layers

Build a forest plot from prepared data

Description

Internal function that handles all ggplot construction for forest plots. Called by forestplotMV and forestplotUV after data preparation.

Usage

build_forest_ggplot(
  tab,
  x_lab,
  show_linetype = FALSE,
  colours = "default",
  showEst = TRUE,
  showRef = TRUE,
  logScale = TRUE,
  nxTicks = 5,
  showN = TRUE,
  showEvent = TRUE,
  xlim = NULL
)

Arguments

Build log scale for forest plot x-axis

Description

Build log scale for forest plot x-axis

Usage

build_log_scale(tab, xlim, nxTicks)

Arguments

Value

a scale_x_log10 layer

Build secondary axis specification

Description

Build secondary axis specification

Usage

build_secondary_axis(tab, yLabels, showN, showEvent)

Arguments

Value

list with axis (scale_y_continuous) and theme elements

Calculate median survival times and add to labels

Description

Calculate median survival times and add to labels

Usage

calculate_and_add_median_times(
  sfit = NULL,
  fit = NULL,
  stratalabs,
  type = "KM",
  plot.event = 1,
  median.text = FALSE,
  median.CI = FALSE,
  median.digits = 3
)

Arguments

Calculate survival/CIF at specific time points and add to labels

Description

Calculate survival/CIF at specific time points and add to labels

Usage

calculate_and_add_time_specific_estimates(
  sfit = NULL,
  fit = NULL,
  stratalabs,
  type = "KM",
  plot.event = 1,
  set.time.text = NULL,
  set.time = NULL,
  set.time.line = FALSE,
  set.time.CI = FALSE,
  set.time.digits = 3
)

Arguments

Calculate Median Time to Event for CIF

Description

Calculate Median Time to Event for CIF

Usage

calculate_cif_median(fit, event_name)

Arguments

Value

Median time to event

Calculate CIF Estimates at Specific Time Points

Description

Calculate CIF Estimates at Specific Time Points

Usage

calculate_cif_timepoints(
  fit,
  plot.event,
  set.time,
  set.time.CI = FALSE,
  set.time.digits = 3,
  multiple_lines = FALSE
)

Arguments

Value

Data frame with time-specific estimates

Clear variable labels from a data frame

Description

This function will remove all label attributes from variables in the data.

Usage

clear_labels(data)

Arguments

Details

To change or remove individual labels use set_labels or set_var_labels

Examples

# Set a few variable labels for ctDNA
data("ctDNA")
ctDNA <- ctDNA |> set_var_labels(
   ctdna_status="detectable ctDNA",
  cohort="A cohort label")
# Clear all variable data frames and check
clear_labels(ctDNA)

Extract model coefficient summary

Description

S3 generic to extract formatted coefficient summaries from fitted models.

Usage

coeffSum(model, CIwidth = 0.95, digits = 2)

Arguments

Value

A data frame of formatted model coefficients.

Match coefficient names to covariate names

Description

Matches model coefficient names (with factor levels) back to original covariate names from the model call. Handles cases where one factor name is a subset of another.

Usage

covnm(betanames, call)

Arguments

Value

Vector of matched covariate names

Get covariate summary dataframe

Description

Returns a dataframe corresponding to a descriptive table.

Usage

covsum(
  data,
  covs,
  maincov = NULL,
  digits = 1,
  numobs = NULL,
  markup = FALSE,
  sanitize = FALSE,
  nicenames = TRUE,
  IQR = FALSE,
  all.stats = FALSE,
  pvalue = TRUE,
  effSize = FALSE,
  show.tests = FALSE,
  dropLevels = TRUE,
  excludeLevels = NULL,
  full = TRUE,
  digits.cat = 0,
  testcont = c("rank-sum test", "ANOVA"),
  testcat = c("Chi-squared", "Fisher"),
  include_missing = FALSE,
  percentage = c("column", "row")
)

Arguments

Details

Comparisons for categorical variables default to chi-square tests, but if there are counts of <5 then the Fisher Exact test will be used and if this is unsuccessful then a second attempt will be made computing p-values using MC simulation. If testcont='ANOVA' then the t-test with unequal variance will be used for two groups and an ANOVA will be used for three or more. The statistical test used can be displayed by specifying show.tests=TRUE.

The number of decimals places to display the statistics can be changed with digits, but this will not change the display of p-values. If more significant digits are required for p-values then use tableOnly=TRUE and format as desired.

References

Ellis, P.D. (2010) The essential guide to effect sizes: statistical power, meta-analysis, and the interpretation of research results. Cambridge: Cambridge University Press.doi:10.1017/CBO9780511761676

Lakens, D. (2013) Calculating and reporting effect sizes to facilitate cumulative science: a practical primer for t-tests and ANOVAs. Frontiers in Psychology, 4; 863:1-12. doi:10.3389/fpsyg.2013.00863

See Also

fisher.test,chisq.test, wilcox.test,kruskal.test,and anova

Create base ggplot for survival curves

Description

Create base ggplot for survival curves

Usage

create_base_plot(
  df,
  type,
  xlab = "Time",
  ylab = "Survival Probability",
  multiple_lines,
  plot.event = 1,
  event = "col",
  lsize = 0.5,
  fsize,
  col,
  linetype = NULL,
  legend.pos = "bottom",
  legend.title = NULL,
  times,
  ylim = c(0, 1),
  xlim = NULL,
  main = NULL
)

Arguments

Create CIF Plotting Data Frame

Description

Create CIF Plotting Data Frame

Usage

create_cif_dataframe(
  fit,
  gsep,
  plot.event,
  stratalabs,
  conf.type = "log",
  flip.CIF = FALSE,
  eventlabs = NULL,
  cov = NULL,
  data = NULL
)

Arguments

Value

Data frame for plotting

Create Survival Fit for Risk Table in CIF

Description

Create Survival Fit for Risk Table in CIF

Usage

create_cif_risk_table_sfit(data, response, cov = NULL)

Arguments

Value

Survival fit object for risk table

Create plotting dataframe for KM curves

Description

Create plotting dataframe for KM curves

Usage

create_km_dataframe(sfit, stratalabs, conf.curves = FALSE, conf.type = "log")

Arguments

Create risk table for survival plot

Description

Create risk table for survival plot

Usage

create_risk_table(
  sfit,
  times,
  xlim,
  stratalabs,
  stratalabs.table = NULL,
  strataname.table = "",
  Numbers_at_risk_text = "At Risk",
  multiple_lines = TRUE,
  col = NULL,
  fsize = 12,
  nsize = 3
)

Arguments

fit crr model

Description

Wrapper function to fit fine and gray competing risk model using function crr from package cmprsk

Usage

crrRx(f, data)

Arguments

Value

a competing risk model with the call appended to the list

See Also

cmprsk::crr

Examples

# From the crr help file:
set.seed(10)
ftime <- rexp(200)
fstatus <- sample(0:2,200,replace=TRUE)
cov <- matrix(runif(600),nrow=200)
dimnames(cov)[[2]] <- c('x1','x2','x3')
df <- data.frame(ftime,fstatus,cov)
m1 <- crrRx(as.formula('ftime+fstatus~x1+x2+x3'),df)
# Nicely output to report:
rm_mvsum(m1,data=df,showN = TRUE,vif=TRUE)

Column separator for paste operations

Description

Column separator for paste operations

Usage

csep()

Value

Character string ", "

Tumour size change over time Longitudinal changes in tumour size since baseline for patients by changes in ctDNA status (clearance, decrease or increase) since baseline.

Description

Tumour size change over time

Longitudinal changes in tumour size since baseline for patients by changes in ctDNA status (clearance, decrease or increase) since baseline.

Usage

data('ctDNA')

Format

A data frame with 270 rows and 5 variables:

id

Patient ID

cohort

Study Cohort

ctdna_status

Change in ctDNA since baseline

time

Number of weeks on treatment

size_change

Percentage change in tumour measurement

Source

https://www.nature.com/articles/s43018-020-0096-5

Remove duplicate reference level rows

Description

When combining adjusted and unadjusted data, reference levels appear twice. This keeps only the first occurrence per variable + level combination.

Usage

deduplicate_refs(tab)

Arguments

Value

data frame with duplicate reference rows removed

Lower bound of non-centrality parameter confidence interval

Description

S3 generic to compute the lower bound of the confidence interval for the non-centrality parameter of a test statistic.

Usage

delta_l(htest, CIwidth)

Arguments

Value

A numeric lower bound.

Upper bound of non-centrality parameter confidence interval

Description

S3 generic to compute the upper bound of the confidence interval for the non-centrality parameter of a test statistic.

Usage

delta_u(htest, CIwidth)

Arguments

Value

A numeric upper bound.

Retrieve columns number from spreadsheet columns specified as unquoted letters

Description

Retrieve columns number from spreadsheet columns specified as unquoted letters

Usage

excelCol(...)

Arguments

Value

a numeric vector corresponding to columns in a spreadsheet

Examples

## Find the column numbers for excel columns AB, CE and BB
excelCol(AB,CE,bb)
## Get the columns between A and K and Z
excelCol(A-K,Z)

Retrieve spreadsheet column letter-names from columns indices

Description

Creates a vector of spreadsheet-style letter-names corresponding to column numbers

Usage

excelColLetters(columnIndices)

Arguments

Details

This is the inverse function of excelCol

Value

a character vector corresponding to the spreadsheet column headings

Examples

## Find the column numbers for excel columns AB, CE and BB
colIndices <- excelCol(AB,CE,bb)
## Go back to the column names
excelColLetters(colIndices)

Extract Gray's test results from CIF fit

Description

Extract Gray's test results from CIF fit

Usage

extract_grays_test(fit, plot.event = 1)

Arguments

Extract variable labels from labelled data frame

Description

Extract variable labels from data and return a data frame with labels

Usage

extract_labels(data, sep = "_")

Arguments

Details

All variable names will be returned, even those with no labels. If the label attribute has length greater than one the values will be concatenated and returned as a single string separated by sep

Examples

# Set a few variable labels for ctDNA
data("ctDNA")
ctDNA <- ctDNA |> set_var_labels(
   ctdna_status="detectable ctDNA",
  cohort="A cohort label")
# Extract labels
extract_labels(ctDNA)

Extract Function and Package Information from Current Document

Description

The function automatically detects the current R script file (works best in RStudio), parses the code to identify function calls, determines which packages they belong to, and creates a summary of all non-base R packages used in the script. It handles both namespace-qualified function calls (e.g., dplyr::filter) and regular function calls, while filtering out base R functions and control structures.

Usage

extract_package_details(ignore_comments = TRUE)

Arguments

Details

This function analyses the current file (an R script, Rmd or qmd file) to extract information about all functions called within the code, identifies their associated packages, and returns a summary of packages used with version and citation information.

Value

A data frame with the following columns:

package_name

Character. Name of the package

functions_called

Character. Comma-separated list of functions called from this package

package_version

Character. Version number of the installed package

package_citation

Character. Formatted citation for the package

Note

• Works best when run from RStudio with an active source file

• Requires that referenced packages are already loaded/installed

• Will not detect functions called through indirect methods (e.g., do.call())

See Also

getAnywhere, packageVersion, citation

Examples

## Not run: 
# Run this function from within an R script to analyze its dependencies
package_info <- extract_package_details()

# Include functions from commented code
package_info_all <- extract_package_details(ignore_comments = FALSE)
print(package_info)

## End(Not run)

Forward fill NA values (vectorized implementation)

Description

Efficiently fills NA values by carrying forward the last non-NA value. Uses vectorized operations for better performance than loop-based approaches.

Usage

fillNAs(x)

Arguments

Value

Vector with NAs filled

Examples

## Not run: 
fillNAs(c(1, NA, NA, 2, NA, 3))  # Returns: c(1, 1, 1, 2, 2, 3)

## End(Not run)

Fit Competing Risks Model

Description

Fit Competing Risks Model

Usage

fit_cif_model(data, response, cov = NULL)

Arguments

Value

List containing fit object and group separator

Fit Kaplan-Meier survival curves

Description

Fit Kaplan-Meier survival curves

Usage

fit_km_model(data, response, cov = NULL, conf.type = "log")

Arguments

Create a forest plot using ggplot2 (DEPRECATED)

Description

#' @description Deprecated: Please use forestplotMV() instead.

Usage

forestplot2(
  model,
  conf.level = 0.95,
  orderByRisk = TRUE,
  colours = "default",
  showEst = TRUE,
  rmRef = FALSE,
  logScale = getOption("reportRmd.logScale", TRUE),
  nxTicks = 5
)

Arguments

Details

This function will be removed in a future version.

This function will accept a log or logistic regression fit from glm or geeglm, and display the OR or RR for each variable on the appropriate log scale.

Value

a plot object

Create a multivariable forest plot using ggplot2

Description

This function creates forest plots from fitted regression models, with optional inclusion of unadjusted estimates. It uses m_summary for robust data extraction and properly handles factor level ordering and reference levels.

Usage

forestplotMV(
  model,
  data = NULL,
  include_unadjusted = FALSE,
  conf.level = 0.95,
  colours = "default",
  showEst = TRUE,
  showRef = TRUE,
  digits = getOption("reportRmd.digits", 2),
  logScale = getOption("reportRmd.logScale", TRUE),
  nxTicks = 5,
  showN = TRUE,
  showEvent = TRUE,
  xlim = NULL
)

Arguments

Value

a ggplot object

Examples

data("pembrolizumab")
glm_fit <- glm(orr ~ change_ctdna_group + sex + age + l_size,
               data = pembrolizumab, family = 'binomial')

# Adjusted only
forestplotMV(glm_fit, data = pembrolizumab)

# Both adjusted and unadjusted
forestplotMV(glm_fit, data = pembrolizumab, include_unadjusted = TRUE)

Create a univariable forest plot using ggplot2

Description

This function creates forest plots from univariable regression models. For new code, consider using forestplotMV() which can handle both adjusted and unadjusted estimates.

Usage

forestplotUV(
  response,
  covs,
  data,
  model = "glm",
  id = NULL,
  corstr = NULL,
  family = NULL,
  digits = getOption("reportRmd.digits", 2),
  conf.level = 0.95,
  colours = "default",
  showEst = TRUE,
  showRef = TRUE,
  logScale = getOption("reportRmd.logScale", TRUE),
  nxTicks = 5,
  showN = TRUE,
  showEvent = TRUE,
  xlim = NULL
)

Arguments

Value

a ggplot object

Examples

data("pembrolizumab")
forestplotUV(response = "orr",
             covs = c("change_ctdna_group", "sex", "age", "l_size"),
             data = pembrolizumab, family = 'binomial')

Combine univariable and multivariable forest plot (DEPRECATED)

Description

This function is deprecated. Please use forestplotMV() with include_unadjusted = TRUE instead.

Usage

forestplotUVMV(UVmodel, MVmodel, ...)

Arguments

Parameter Estimation for the Box-Cox Transformation

Description

This function is copied from the geoR package which has been removed from the CRAN repository.

Usage

geoR_boxcoxfit(object, xmat, lambda, lambda2 = NULL, add.to.data = 0)

Arguments

Details

For more information see: https://cran.r-project.org/web/packages/geoR/index.html

Get beta label for model type

Description

Returns the appropriate coefficient label (OR, HR, RR, Estimate) for a given model class.

Usage

get_beta_label(model_class)

Arguments

Value

Character string for beta label

Extract cluster IDs from a fitted model

Description

S3 generic to extract the cluster/group identifier vector from a fitted model. Returns NULL for models that do not have a clustering structure.

Usage

get_cluster_ids(model)

Arguments

Value

A vector of cluster identifiers (one per observation), or NULL.

Extract event counts from a fitted model

Description

S3 generic to extract event and sample size counts from a fitted model.

Usage

get_event_counts(model)

Arguments

Value

A named list with event count information, or NULL.

Get model class from model specifications

Description

Internal function that maps model type, family, and GEE usage to the appropriate S3 class for autoreg() dispatch.

Usage

get_model_class(type, family = NULL, gee = FALSE)

Arguments

Value

Character string of S3 class name

Extract model coefficients

Description

S3 generic to extract raw coefficients from a fitted model.

Usage

get_model_coef(model)

Arguments

Value

A named numeric vector of model coefficients.

Extract data from a fitted model

Description

S3 generic to extract the data frame used to fit a model.

Usage

get_model_data(model)

Arguments

Value

A data frame, or NULL if data cannot be extracted.

Create Kaplan-Meier or cumulative incidence plots

Description

ggkmcif() was deprecated in version 0.1.2 and will be removed in a future version. Please use ggkmcif2() instead.

Usage

ggkmcif(
  response,
  cov = NULL,
  data,
  type = NULL,
  pval = TRUE,
  HR = FALSE,
  HR_pval = FALSE,
  conf.curves = FALSE,
  conf.type = "log",
  table = TRUE,
  times = NULL,
  xlab = "Time",
  ylab = NULL,
  main = NULL,
  stratalabs = NULL,
  strataname = nicename(cov),
  stratalabs.table = NULL,
  strataname.table = strataname,
  median.text = FALSE,
  median.lines = FALSE,
  median.CI = FALSE,
  set.time.text = NULL,
  set.time.line = FALSE,
  set.time = 5,
  set.time.CI = FALSE,
  censor.marks = TRUE,
  censor.size = 3,
  censor.stroke = 1.5,
  fsize = 10,
  nsize = 3,
  lsize = 1,
  psize = 3.5,
  median.size = 3,
  median.pos = NULL,
  median.lsize = 1,
  set.size = 3,
  set.pos = NULL,
  set.lsize = 1,
  ylim = c(0, 1),
  col = NULL,
  linetype = NULL,
  xlim = NULL,
  legend.pos = NULL,
  pval.pos = NULL,
  plot.event = 1,
  event = c("col", "linetype"),
  flip.CIF = FALSE,
  cut = NULL,
  eventlabs = NULL,
  event.name = NULL,
  Numbers_at_risk_text = "Numbers at risk",
  HR.digits = 2,
  HR.pval.digits = 3,
  pval.digits = 3,
  median.digits = 3,
  set.time.digits = 3,
  returns = FALSE,
  print.n.missing = TRUE
)

Arguments

Value

See ggkmcif2() for return value details

Plot KM and CIF curves with ggplot

Description

This function will plot a KM or CIF curve with option to add the number at risk. You can specify if you want confidence bands, the hazard ratio, and pvalues, as well as the units of time used.

Usage

ggkmcif2(
  response,
  cov = NULL,
  data,
  pval = TRUE,
  conf.curves = FALSE,
  table = TRUE,
  xlab = "Time",
  ylab = NULL,
  col = NULL,
  times = NULL,
  type = NULL,
  plot.event = 1,
  returns = FALSE,
  ...
)

Arguments

Details

Note that for proper pdf output of special characters the following code needs to be included in the first chunk of the rmd knitr::opts_chunk$set(dev="cairo_pdf")

Additional parameters passed to ggkmcif2

Description

This section documents the additional parameters for ggkmcif2.

Usage

ggkmcif2Parameters(
  HR = FALSE,
  HR_pval = FALSE,
  conf.type = "log",
  main = NULL,
  stratalabs = NULL,
  strataname,
  stratalabs.table = NULL,
  strataname.table = strataname,
  median.text = FALSE,
  median.lines = FALSE,
  median.CI = FALSE,
  set.time.text = NULL,
  set.time.line = FALSE,
  set.time = 5,
  set.time.CI = FALSE,
  censor.marks = TRUE,
  censor.size = 2,
  censor.stroke = 1.5,
  censor.symbol = "|",
  fsize,
  nsize = 3,
  lsize = 0.7,
  psize = 3.5,
  median.size = 3,
  median.pos = NULL,
  median.lsize = 1,
  set.size = 3,
  set.pos = NULL,
  set.lsize = 1,
  ylim = c(0, 1),
  linetype = NULL,
  xlim = NULL,
  legend.pos,
  legend.title = strataname,
  pval.pos = NULL,
  event = c("col", "linetype"),
  flip.CIF = FALSE,
  cut = NULL,
  eventlabs = NULL,
  event.name = NULL,
  Numbers_at_risk_text = "At risk",
  tbl.height = NULL,
  HR.digits = 2,
  HR.pval.digits = 3,
  pval.digits = 3,
  median.digits = 3,
  set.time.digits = 3,
  print.n.missing = TRUE,
  returns = FALSE
)

Arguments

Additional parameters passed to ggkmcif2

Description

This section documents the additional parameters for ggkmcif2.

Arguments

Plot KM and CIF curves with ggplot

Description

This function will plot a KM or CIF curve with option to add the number at risk. You can specify if you want confidence bands, the hazard ratio, and pvalues, as well as the units of time used.

Arguments

Details

Note that for proper pdf output of special characters the following code needs to be included in the first chunk of the rmd knitr::opts_chunk$set(dev="cairo_pdf")

Value

ggplot object; if table = F then only curves are output; if table = T then curves and risk table are output together

Examples

# Simple plot without confidence intervals
data("pembrolizumab")
ggkmcif2(response = c('os_time','os_status'),
cov='cohort',
data=pembrolizumab)

# Plot with median survival time
ggkmcif2(response = c('os_time','os_status'),
cov='sex',
data=pembrolizumab,
median.text = TRUE,median.lines=TRUE,conf.curves=TRUE)

# Plot with specified survival times and log-log CI
ggkmcif2(response = c('os_time','os_status'),
cov='sex',
data=pembrolizumab,
median.text = FALSE,set.time.text = 'mo OS',
set.time = c(12,24),conf.type = 'log-log',conf.curves=TRUE)

# KM plot with 95% CI and censor marks
ggkmcif2(c('os_time','os_status'),'sex',data = pembrolizumab, type = 'KM',
HR=TRUE, HR_pval = TRUE, conf.curves = TRUE,conf.type='log-log',
set.time.CI = TRUE, censor.marks=TRUE)

combine components of a call to ggkmci

Description

ggkmcif() was deprecated in version 0.1.2 and will be removed in a future version.

Usage

ggkmcif_paste(list_gg)

Arguments

Calculate global p-values for categorical variables

Description

S3 generic to compute global (Type II/III) p-values for categorical predictors in a fitted model.

Usage

gp(model, ...)

Arguments

Value

A data frame with columns var and global_p.

Bold strings for HTML output

Description

Wraps strings in HTML bold formatting using inline CSS.

Usage

hbld(strings)

Arguments

Value

Vector of strings wrapped in HTML bold span

Format p-values for plot annotations

Description

Formats p-values specifically for display in plots (e.g., survival curves). Returns formatted string with "p = " or "p < " prefix.

Usage

lpvalue2(x, digits)

Arguments

Details

Formatting rules:

• p < 10^-digits: returns "p < threshold" (e.g., "p < 0.001")

• p >= threshold: returns "p = value" rounded to specified digits

Used by: ggkmcif2() for survival curve annotations in main.R and ggkmcif3.R

Value

Character string with "p = " or "p < " prefix

Examples

## Not run: 
lpvalue2(0.0001, 3)  # Returns: "p < 0.001"
lpvalue2(0.0456, 3)  # Returns: "p = 0.046"

## End(Not run)

Output a table for multivariate or univariate regression models

Description

A dataframe corresponding to a univariate or multivariate regression table. If for_plot = TRUE, estimates and confidence interval bounds will also be displayed separately for easy plotting.

Usage

m_summary(
  model,
  CIwidth = 0.95,
  digits = 2,
  vif = FALSE,
  whichp = "levels",
  for_plot = FALSE
)

Arguments

Details

Global p-values are likelihood ratio tests for lm, glm and polr models. For lme models an attempt is made to re-fit the model using ML and if,successful LRT is used to obtain a global p-value. For coxph models the model is re-run without robust variances with and without each variable and a LRT is presented. If unsuccessful a Wald p-value is returned. For GEE and CRR models Wald global p-values are returned. For negative binomial models a deviance test is used.

If the variance inflation factor is requested (VIF=TRUE) then a generalised VIF will be calculated in the same manner as the car package.

As of R 4.4.0 the likelihood profiles are included in base R.

The number of decimals places to display the statistics can be changed with digits, but this will not change the display of p-values. If more significant digits are required for p-values then use tableOnly=TRUE and format as desired.

Examples

## Not run: data("pembrolizumab")
uv_lm <- lm(age~sex,data=pembrolizumab)
m_summary(uv_lm, digits = 3, for_plot = FALSE)

mv_binom <- glm(orr~age+sex+cohort,family = 'binomial',data = pembrolizumab)
m_summary(mv_binom, whichp = "both", for_plot = TRUE)
## End(Not run)

Match coefficient names to covariate indices

Description

Matches model coefficient names (including interactions) to original covariate indices from the model call. Handles centered variables and interaction terms. Returns a numeric encoding for sorting.

Usage

matchcovariate(betanames, ucall)

Arguments

Details

Changes:

• Feb 21, 2019: Changed from charmatch to grepl for more reliable matching

• Dec 14, 2020: Added space removal to support centered variables

Value

Numeric vector of encoded covariate indices, or -1 if matching fails

Extract data frame name from model call argument

Description

Attempts to identify the data frame object used in a model call by searching the global environment.

Usage

matchdata(dataArg)

Arguments

Value

Character string of data frame name, or NULL if not found

Create model matrix from formula

Description

Extracts model matrix from formula, optionally separating response variables from predictors. Removes intercept column and cleans column names.

Usage

modelmatrix(f, data = NULL)

Arguments

Value

Model matrix or list of matrices (y and x) if response present

Extract model term names

Description

S3 generic to extract predictor term names from a fitted model, excluding the intercept.

Usage

mterms(model)

Arguments

Value

A character vector of term names.

Get multivariate summary dataframe

Description

Returns a dataframe with the model summary and global p-value for multi-level variables.

Usage

mvsum(
  model,
  data,
  digits = getOption("reportRmd.digits", 2),
  showN = TRUE,
  showEvent = TRUE,
  markup = TRUE,
  sanitize = TRUE,
  nicenames = TRUE,
  CIwidth = 0.95,
  vif = TRUE
)

Arguments

Details

Global p-values are likelihood ratio tests for lm, glm and polr models. For lme models an attempt is made to re-fit the model using ML and if,successful LRT is used to obtain a global p-value. For coxph models the model is re-run without robust variances with and without each variable and a LRT is presented. If unsuccessful a Wald p-value is returned. For GEE and CRR models Wald global p-values are returned.

If the variance inflation factor is requested (VIF=TRUE) then a generalised VIF will be calculated in the same manner as the car package.

VIF for competing risk models is computed by fitting a linear model with a dependent variable comprised of the sum of the model independent variables and then calculating VIF from this linear model.

References

John Fox & Georges Monette (1992) Generalized Collinearity Diagnostics, Journal of the American Statistical Association, 87:417, 178-183, DOI: 10.1080/01621459.1992.10475190

John Fox and Sanford Weisberg (2019). An R Companion to Applied Regression, Third Edition. Thousand Oaks CA: Sage.

Combine two table columns into a single column with levels of one nested within levels of the other.

Description

This function accepts a data frame (via the data argument) and combines two columns into a single column with values from the head_col serving as headers and values of the to_col displayed underneath each header. The resulting table is then passed to outTable for printing and output, to use the grouped table as a data frame specify tableOnly=TRUE. By default the headers will be bolded and the remaining values indented.

Usage

nestTable(
  data,
  head_col,
  to_col,
  colHeader = "",
  caption = NULL,
  indent = TRUE,
  boldheaders = TRUE,
  hdr_prefix = "",
  hdr_suffix = "",
  digits = getOption("reportRmd.digits", 2),
  tableOnly = FALSE,
  fontsize
)

Arguments

Details

Note that it is possible to combine multiple tables (more than two) with this function.

Value

A character vector of the table source code, unless tableOnly=TRUE in which case a data frame is returned

Examples

## Investigate models to predict baseline ctDNA and tumour size and display together
## (not clinically useful!)
data(pembrolizumab)
fit1 <- lm(baseline_ctdna~age+l_size+pdl1,data=pembrolizumab)
m1 <- rm_mvsum(fit1,tableOnly=TRUE)
m1$Response = 'ctDNA'
fit2 <- lm(l_size~age+baseline_ctdna+pdl1,data=pembrolizumab)
m2 <- rm_mvsum(fit2,tableOnly=TRUE)
m2$Response = 'Tumour Size'
nestTable(rbind(m1,m2),head_col='Response',to_col='Covariate')

Format model call as clean string

Description

Converts model call to string with single quotes instead of double quotes.

Usage

nicecall(model_call)

Arguments

Value

Character string of formatted call

Order forest plot data by risk and factor levels

Description

Orders variables by their maximum estimate (descending) and levels within variables by their original order, with reference levels first.

Usage

order_forest_data(tab)

Arguments

Details

When both Adjusted and Unadjusted rows are present, ordering is determined by the Adjusted estimates. When only Unadjusted rows are present (e.g., from forestplotUV), ordering uses those estimates directly.

Print tables to PDF/Latex HTML or Word

Description

Output the table nicely to whatever format is appropriate. This is the output function used by the rm_* printing functions.

Usage

outTable(
  tab,
  row.names = NULL,
  to_indent = numeric(0),
  bold_headers = TRUE,
  rows_bold = numeric(0),
  bold_cells = NULL,
  caption = NULL,
  digits = getOption("reportRmd.digits", 2),
  align,
  applyAttributes = TRUE,
  keep.rownames = FALSE,
  nicenames = TRUE,
  fontsize,
  chunk_label,
  format = NULL,
  header_above = NULL
)

Arguments

Details

Entire rows can be bolded, or specific cells. Currently indentation refers to the first column only. By default, underscores in column names are converted to spaces. To disable this set nicenames to FALSE

Value

A character vector of the table source code, unless tableOnly=TRUE in which case a data frame is returned

Survival data Survival status and ctDNA levels for patients receiving pembrolizumab

Description

Survival data

Survival status and ctDNA levels for patients receiving pembrolizumab

Usage

data('pembrolizumab')

Format

A data frame with 94 rows and 15 variables:

id

Patient ID

age

Age at study entry

sex

Patient Sex

cohort

Study Cohort

l_size

Target lesion size at baseline

pdl1

PD L1 percent

tmb

log of TMB

baseline_ctdna

Baseline ctDNA

change_ctdna_group

Did ctDNA increase or decrease from baseline to cycle 3

orr

Objective Response

cbr

Clinical Beneficial Response

os_status

Overall survival status

os_time

Overall survival time in months

pfs_status

Progression free survival status

pfs_time

Progression free survival time in months

Source

https://www.nature.com/articles/s43018-020-0096-5

Plot multiple bivariate relationships in a single plot

Description

This function is designed to accompany rm_uvsum as a means of visualising the results, and uses similar syntax.

Usage

plotuv(
  response,
  covs,
  data,
  showN = FALSE,
  showPoints = TRUE,
  na.rm = TRUE,
  response_title = NULL,
  return_plotlist = FALSE,
  ncol = 2,
  p_margins = c(0, 0.2, 1, 0.2),
  bpThreshold = 20,
  mixed = TRUE,
  violin = FALSE,
  position = c("dodge", "stack", "fill"),
  use_labels = TRUE
)

Arguments

Details

Plots are displayed as follows: If response is continuous For a numeric predictor scatterplot For a categorical predictor: If 20+ observations available boxplot, otherwise dotplot with median line If response is a factor For a numeric predictor: If 20+ observations available boxplot, otherwise dotplot with median line For a categorical predictor barplot Response variables are shown on the ordinate (y-axis) and covariates on the abscissa (x-axis)

Variable names are replaced by their labels if available, or by tidy versions if not. Set use_labels=FALSE to use the variable names.

Value

a list containing plots for each variable in covs

See Also

ggplot2::ggplot and ggpubr::ggarrange replace_plot_labels

Examples

## Run multiple univariate analyses on the pembrolizumab dataset to predict cbr and
## then visualise the relationships.
data("pembrolizumab")
rm_uvsum(data=pembrolizumab,
response='cbr',covs=c('age','sex','l_size','baseline_ctdna'))
plotuv(data=pembrolizumab,  response='cbr',
covs=c('age','sex','l_size','baseline_ctdna'),showN=TRUE)

Extract and prepare forest plot data from m_summary output

Description

Extract and prepare forest plot data from m_summary output

Usage

prepare_forest_data(summary_output, model_type = "Adjusted", digits = 2)

Arguments

Process CIF Median Values

Description

Process CIF Median Values

Usage

process_cif_medians(
  fit,
  plot.event,
  stratalabs,
  median.lines = FALSE,
  median.text = FALSE,
  median.digits = 3,
  multiple_lines = FALSE
)

Arguments

Value

List with updated stratalabs and median values

Process CIF Time-Specific Estimates

Description

Process CIF Time-Specific Estimates

Usage

process_cif_timepoints(
  fit,
  plot.event,
  stratalabs,
  set.time.text = NULL,
  set.time = NULL,
  set.time.line = FALSE,
  set.time.CI = FALSE,
  set.time.digits = 3,
  multiple_lines = FALSE
)

Arguments

Value

List with updated stratalabs and time-specific estimates

Process covariate variable (factor conversion, numeric cutoffs)

Description

Process covariate variable (factor conversion, numeric cutoffs)

Usage

process_covariate(data, cov, cut = NULL, stratalabs = NULL)

Arguments

Round and paste with parentheses (smart formatting)

Description

Rounds numeric values and formats as "value (lower, upper)" with intelligent formatting:

• Values with |x| < 0.01 or |x| > 1000: scientific notation

• Other values: standard rounding with trailing zeros

Usage

psthr(x, y = 2, compact = FALSE)

psthr0(x, digits = 2)

Arguments

Value

Character string with first element followed by remaining elements in parentheses

Functions

• psthr0(): Compact version without spaces (for plots)

Paste vector elements with parentheses

Description

Formats a vector as "first (second, third, ...)" where remaining elements are comma-separated inside parentheses.

Usage

pstprn(x, compact = FALSE)

pstprn0(x)

Arguments

Value

Character string with first element followed by remaining elements in parentheses

Functions

• pstprn0(): Compact version without spaces (for plots)

Remove dollar sign prefix from column names

Description

Removes common prefix (before $) from interaction term column names. Used to clean up model matrix column names.

Usage

removedollar(x)

Arguments

Value

Character vector with dollar sign prefixes removed

Replace variable names with labels in ggplot

Description

If the data stored in a ggplot object has variable labels then this will replace the variable names with the variable labels. If no labels are set then the variable names will be tidied and a nicer version used.

Usage

replace_plot_labels(plot)

Arguments

See Also

set_var_labels() for setting individual variable labels, set_labels() for setting variable labels using a data frame, extract_labels() for creating a data frame of all variable labels, clear_labels() for removing variable labels

Examples

## Not run: 
data("pembrolizumab")
p <- ggplot(pembrolizumab,aes(x=change_ctdna_group,y=baseline_ctdna)) +
geom_boxplot()
replace_plot_labels(p)
pembrolizumab <- set_var_labels(pembrolizumab,
change_ctdna_group="Change in ctDNA group")
p <- ggplot(pembrolizumab,aes(x=change_ctdna_group,y=baseline_ctdna)) +
geom_boxplot()
replace_plot_labels(p)
# Can also be used with a pipe, but expression needs to be wrapped in a brace
(ggplot(pembrolizumab,aes(x=change_ctdna_group,y=baseline_ctdna)) +
geom_boxplot()) |> replace_plot_labels()

## End(Not run)

Summarize cumulative incidence by group

Description

Displays event counts and event rates at specified time points for the entire cohort and by group. Gray's test of differences in cumulative incidence is displayed.

Usage

rm_cifsum(
  data,
  time,
  status,
  group = NULL,
  eventcode = 1,
  cencode = 0,
  eventtimes,
  eventtimeunit,
  eventtimeLbls = NULL,
  CIwidth = 0.95,
  unformattedp = FALSE,
  na.action = "na.omit",
  showCounts = TRUE,
  showGraystest = TRUE,
  digits = 2,
  caption = NULL,
  tableOnly = FALSE
)

Arguments

Value

A character vector of the event table source code, unless tableOnly=TRUE in which case a data frame is returned

Examples

library(survival)
data(pbc)

# Event probabilities at various time points with replacement time labels
rm_cifsum(data=pbc,time='time',status='status',
eventtimes=c(1825,3650),eventtimeLbls=c(5,10),eventtimeunit='yr')

# Event probabilities by one group
rm_cifsum(data=pbc,time='time',status='status',group='trt',
eventtimes=c(1825,3650),eventtimeunit='day')


# Event probabilities by multiple groups
rm_cifsum(data=pbc,time='time',status='status',group=c('trt','sex'),
eventtimes=c(1825,3650),eventtimeunit='day')

Output a compact summary table

Description

Outputs a table formatted for pdf, word or html output with summary statistics

Usage

rm_compactsum(
  data,
  xvars,
  grp,
  use_mean,
  caption = NULL,
  tableOnly = FALSE,
  covTitle = "",
  digits = 1,
  digits.cat = 0,
  nicenames = TRUE,
  iqr = TRUE,
  all.stats = FALSE,
  pvalue = TRUE,
  effSize = FALSE,
  p.adjust = "none",
  unformattedp = FALSE,
  show.sumstats = FALSE,
  show.tests = FALSE,
  full = TRUE,
  percentage = "col"
)

Arguments

Details

Comparisons for categorical variables default to chi-square tests, but if there are counts of <5 then the Fisher Exact test will be used. For grouping variables with two levels, either t-tests (mean) or wilcoxon tests (median) will be used for numerical variables. Otherwise, ANOVA (mean) or Kruskal- Wallis tests will be used. The statistical test used can be displayed by specifying show.tests = TRUE. Statistical tests and effect sizes for grp and/ or xvars with less than 2 counts in any level will not be shown.

Effect sizes are calculated as Cohen d for between group differences if the variable is summarised with the mean, otherwise Wilcoxon R if summarised with a median. Cramer's V is used for categorical variables, omega is used for differences in means among more than two groups and epsilon for differences in medians among more than two groups. Confidence intervals are calculated using bootstrapping.

tidyselect can only be used for xvars and grp arguments. Additional arguments (digits, use_mean) must be passed in using characters if variable names are used.

Value

A character vector of the table source code, unless tableOnly = TRUE in which case a data frame is returned. The output has the following attribute:

• "description", which describes what is included in the output table and the type of statistical summary for each covariate. When applicable, the types of statistical tests used will be included. If effSize = TRUE, the effect sizes for each covariate will also be mentioned.

References

Smithson, M. (2002). Noncentral Confidence Intervals for Standardized Effect Sizes. (07/140 ed., Vol. 140). SAGE Publications. doi:10.4135/9781412983761.n4

Steiger, J. H. (2004). Beyond the F Test: Effect Size Confidence Intervals and Tests of Close Fit in the Analysis of Variance and Contrast Analysis. Psychological Methods, 9(2), 164–182. doi:10.1037/1082-989X.9.2.164

Kelley, T. L. (1935). An Unbiased Correlation Ratio Measure. Proceedings of the National Academy of Sciences - PNAS, 21(9), 554–559. doi:10.1073/pnas.21.9.554

Okada, K. (2013). Is Omega Squared Less Biased? A Comparison of Three Major Effect Size Indices in One-Way ANOVA. Behavior Research Methods, 40(2), 129-147.

Breslow, N. (1970). A generalized Kruskal-Wallis test for comparing K samples subject to unequal patterns of censorship. Biometrika, 57(3), 579-594.

FRITZ, C. O., MORRIS, P. E., & RICHLER, J. J. (2012). Effect Size Estimates: Current Use, Calculations, and Interpretation. Journal of Experimental Psychology. General, 141(1), 2–18. doi:10.1037/a0024338

Examples

data("pembrolizumab")
rm_compactsum(data = pembrolizumab, xvars = c("age",
"change_ctdna_group", "l_size", "pdl1"), grp = "sex", use_mean = "age",
digits = c("age" = 2, "l_size" = 3), digits.cat = 1, iqr = TRUE,
show.tests = TRUE)

# Other Examples (not run)
## Include the summary statistic in the variable column
#rm_compactsum(data = pembrolizumab, xvars = c("age",
#"change_ctdna_group"), grp = "sex", use_mean = "age", show.sumstats=TRUE)

## To show effect sizes
#rm_compactsum(data = pembrolizumab, xvars = c("age",
#"change_ctdna_group"), grp = "sex", use_mean = "age", digits = 2,
#effSize = TRUE, show.tests = TRUE)

## To return unformatted p-values
#rm_compactsum(data = pembrolizumab, xvars = c("l_size",
#"change_ctdna_group"), grp = "cohort", effSize = TRUE, unformattedp = TRUE)

## Using tidyselect
#pembrolizumab |> rm_compactsum(xvars = c(age, sex, pdl1), grp = cohort,
#effSize = TRUE)

Add header row to table Outputs a descriptive covariate table

Description

Returns a data frame corresponding to a descriptive table.

Usage

rm_covsum(
  data,
  covs = NULL,
  maincov = NULL,
  caption = NULL,
  tableOnly = FALSE,
  covTitle = "",
  digits = 1,
  digits.cat = 0,
  nicenames = TRUE,
  IQR = FALSE,
  all.stats = FALSE,
  pvalue = TRUE,
  effSize = FALSE,
  p.adjust = "none",
  unformattedp = FALSE,
  show.tests = FALSE,
  testcont = c("rank-sum test", "ANOVA"),
  testcat = c("Chi-squared", "Fisher"),
  full = TRUE,
  include_missing = FALSE,
  percentage = c("column", "row"),
  dropLevels = TRUE,
  excludeLevels = NULL,
  numobs = NULL,
  fontsize,
  chunk_label,
  xvars = NULL,
  grp = NULL
)

Arguments

Details

Comparisons for categorical variables default to chi-square tests, but if there are counts of <5 then the Fisher Exact test will be used and if this is unsuccessful then a second attempt will be made computing p-values using MC simulation. If testcont='ANOVA' then the t-test with unequal variance will be used for two groups and an ANOVA will be used for three or more. The statistical test used can be displayed by specifying show.tests=TRUE.

Effect size can be obtained when p-value is requested.

Further formatting options are available using tableOnly=TRUE and outputting the table with a call to outTable.

A newer version of this function is rm_compactsum which is more flexible and displays fewer rows of output.

Tidyselect can be used for covs, maincov, xvars, and grp arguments, allowing bare column names (e.g., c(age, sex)) in addition to character strings (e.g., c("age", "sex")).

Value

A character vector of the table source code, unless tableOnly=TRUE in which case a data frame is returned

References

Ellis, P.D. (2010) The essential guide to effect sizes: statistical power, meta-analysis, and the interpretation of research results. Cambridge: Cambridge University Press.doi:10.1017/CBO9780511761676

Lakens, D. (2013) Calculating and reporting effect sizes to facilitate cumulative science: a practical primer for t-tests and ANOVAs. Frontiers in Psychology, 4; 863:1-12. doi:10.3389/fpsyg.2013.00863

See Also

covsum,fisher.test, chisq.test, wilcox.test, kruskal.test, anova, and outTable

Examples

data("pembrolizumab")
rm_covsum(data=pembrolizumab, maincov = 'orr',
covs=c('age','sex','pdl1','tmb','l_size','change_ctdna_group'),
show.tests=TRUE)

# To Show Effect Sizes
rm_covsum(data=pembrolizumab, maincov = 'orr',
covs=c('age','sex'),
effSize=TRUE)

# To make custom changes or change the fontsize in PDF/HTML
tab <- rm_covsum(data=pembrolizumab,maincov = 'change_ctdna_group',
covs=c('age','sex','pdl1','tmb','l_size'),show.tests=TRUE,tableOnly = TRUE)
outTable(tab, fontsize=7)

# To return unformatted p-values
tab <- rm_covsum(data=pembrolizumab, maincov = 'orr',
covs=c('age','sex','pdl1','tmb','l_size','change_ctdna_group'),
show.tests=TRUE,unformattedp=TRUE,tableOnly=TRUE)
outTable(tab,digits=5)
outTable(tab,digits=5, applyAttributes=FALSE) # remove bold/indent

Format a regression model nicely for 'Rmarkdown'

Description

Multivariable (or univariate) regression models are re-formatted for reporting and a global p-value is added for the evaluation of factor variables.

Usage

rm_mvsum(
  model,
  data,
  digits = getOption("reportRmd.digits", 2),
  covTitle = "",
  showN = TRUE,
  showEvent = TRUE,
  CIwidth = 0.95,
  vif = TRUE,
  whichp = c("levels", "global", "both"),
  caption = NULL,
  tableOnly = FALSE,
  p.adjust = "none",
  unformattedp = FALSE,
  nicenames = TRUE,
  include_unadjusted = FALSE,
  chunk_label,
  fontsize
)

Arguments

Details

Global p-values are likelihood ratio tests for lm, glm and polr models. For lme models an attempt is made to re-fit the model using ML and if successful LRT is used to obtain a global p-value. For lmer models (lme4), if the lmerTest package is installed, Satterthwaite-based p-values and F-test global p-values are used; otherwise Wald z-based p-values and chi-squared LRT global p-values are returned. For glmer models (lme4), Wald z-based p-values are used with chi-squared LRT global p-values. Estimates are exponentiated for binomial (OR) and poisson/negative binomial (RR) families. For coxph models the model is re-run without robust variances with and without each variable and a LRT is presented. If unsuccessful a Wald p-value is returned. For GEE and CRR models Wald global p-values are returned. For negative binomial models a deviance test is used.

If the variance inflation factor is requested (VIF=TRUE, default) then a generalised VIF will be calculated in the same manner as the car package.

As of version 0.1.1 if global p-values are requested they will be included in the p-value column.

As of R 4.4.0 profile likelihood confidence intervals will be calculated automatically and there is no longer an option to force Wald tests.

The number of decimals places to display the statistics can be changed with digits, but this will not change the display of p-values. If more significant digits are required for p-values then use tableOnly=TRUE and format as desired.

Value

A character vector of the table source code, unless tableOnly=TRUE in which case a data frame is returned

References

John Fox & Georges Monette (1992) Generalized Collinearity Diagnostics, Journal of the American Statistical Association, 87:417, 178-183, doi:10.1080/01621459.1992.10475190

John Fox and Sanford Weisberg (2019). An R Companion to Applied Regression, Third Edition. Thousand Oaks CA: Sage.

Examples

data("pembrolizumab")
glm_fit = glm(change_ctdna_group~sex:age+baseline_ctdna+l_size,
data=pembrolizumab,family = 'binomial')
rm_mvsum(glm_fit)

#linear model with p-value adjustment
lm_fit=lm(baseline_ctdna~age+sex+l_size+tmb,data=pembrolizumab)
rm_mvsum(lm_fit,p.adjust = "bonferroni")
#Coxph
require(survival)
res.cox <- coxph(Surv(os_time, os_status) ~ sex+age+l_size+tmb, data = pembrolizumab)
rm_mvsum(res.cox, vif=TRUE)

# lmer (lme4 mixed effects model) - single random intercept

if (require(lme4)){
lmer_fit <- lme4::lmer(age ~ sex + pdl1 + (1|cohort), data = pembrolizumab)
rm_mvsum(lmer_fit)
}


# lmer with multiple random effects and global p-values

if (require(lme4) && require(geepack)){
data(dietox, package = "geepack")
dietox$Cu <- as.factor(dietox$Cu)
lmer_fit2 <- lme4::lmer(Weight ~ Cu + Time + (1|Pig) + (1|Litter), data = dietox)
rm_mvsum(lmer_fit2, whichp = "both")
}


# glmer (binomial mixed effects model) - odds ratios

if (require(lme4)){
data(cbpp, package = "lme4")
glmer_fit <- lme4::glmer(cbind(incidence, size - incidence) ~ period + (1|herd),
  data = cbpp, family = binomial)
rm_mvsum(glmer_fit)
}


# glmer.nb (negative binomial mixed effects model) - rate ratios

if (require(lme4) && require(geepack)){
data(dietox, package = "geepack")
dietox$Cu <- as.factor(dietox$Cu)
nb_fit <- lme4::glmer.nb(Weight ~ Cu + Time + (1|Pig), data = dietox)
rm_mvsum(nb_fit, whichp = "both")
}

Display event counts, expected event counts and logrank test of differences

Description

This is a wrapper function around the survdiff function to display overall event rates and group-specific rates along with the log-rank test of a difference in survival between groups in a single table suitable for markdown output. Median survival times are included by default but can be removed setting median=FALSE

Usage

rm_survdiff(
  data,
  time,
  status,
  covs,
  strata,
  includeVarNames = FALSE,
  digits = 1,
  showCols = c("N", "Observed", "Expected"),
  CIwidth = 0.95,
  conf.type = "log",
  caption = NULL,
  tableOnly = FALSE,
  fontsize,
  unformattedp = FALSE
)

Arguments

Value

A character vector of the survival table source code, unless tableOnly=TRUE in which case a data frame is returned

See Also

survival::survdiff

Examples

#' # Differences between sex
data("pembrolizumab")
rm_survdiff(data=pembrolizumab,time='os_time',status='os_status',
covs='sex',digits=1)

# Differences between sex, stratified by cohort
rm_survdiff(data=pembrolizumab,time='os_time',status='os_status',
covs='sex',strata='cohort',digits=1)
# Differences between sex/cohort groups
rm_survdiff(data=pembrolizumab,time='os_time',status='os_status',
covs=c('sex','cohort'),digits=1)

Summarise survival data by group

Description

Displays event counts, median survival time and survival rates at specified times points for the entire cohort and by group. The logrank test of differences in survival curves is displayed.

Usage

rm_survsum(
  data,
  time,
  status,
  group = NULL,
  survtimes = NULL,
  survtimeunit,
  survtimesLbls = NULL,
  CIwidth = 0.95,
  unformattedp = FALSE,
  conf.type = "log",
  na.action = "na.omit",
  showCounts = TRUE,
  showLogrank = TRUE,
  eventProb = FALSE,
  digits = getOption("reportRmd.digits", 2),
  caption = NULL,
  tableOnly = FALSE,
  fontsize
)

Arguments

Details

This summary table is supplied for simple group comparisons only. To examine differences in groups with stratification see rm_survdiff. To summarise differences in survival rates controlling for covariates see rm_survtime.

Value

A character vector of the survival table source code, unless tableOnly=TRUE in which case a data frame is returned

See Also

survival::survfit

Examples

# Simple median survival table
data("pembrolizumab")
rm_survsum(data=pembrolizumab,time='os_time',status='os_status')

# Survival table with yearly survival rates
rm_survsum(data=pembrolizumab,time='os_time',status='os_status',
survtimes=c(12,24),survtimesLbls=1:2, survtimeunit='yr')

#Median survival by group
rm_survsum(data=pembrolizumab,time='os_time',status='os_status',group='sex')

# Survival Summary by cohort, displayed in years
rm_survsum(data=pembrolizumab,time='os_time',status='os_status',
group="cohort",survtimes=seq(12,72,12),
survtimesLbls=seq(1,6,1),
survtimeunit='years')

# Survival Summary by Sex and ctDNA group
rm_survsum(data=pembrolizumab,time='os_time',status='os_status',
group=c('sex','change_ctdna_group'),survtimes=c(12,24),survtimeunit='mo')

Display survival rates and events for specified times

Description

This is a wrapper for the survfit function to output a tidy display for reporting. Either Kaplan Meier or Cox Proportional Hazards models may be used to estimate the survival probabilities.

Usage

rm_survtime(
  data,
  time,
  status,
  covs = NULL,
  strata = NULL,
  type = "KM",
  survtimes,
  survtimeunit,
  strata.prefix = NULL,
  survtimesLbls = NULL,
  showCols = c("At Risk", "Events", "Censored"),
  CIwidth = 0.95,
  conf.type = "log",
  na.action = "na.omit",
  showCounts = TRUE,
  digits = getOption("reportRmd.digits", 2),
  caption = NULL,
  tableOnly = FALSE,
  fontsize
)

Arguments

Details

If covariates are supplied then a Cox proportional hazards model is fit for the entire cohort and each strata. Otherwise the default is for Kaplan-Meier estimates. Setting type = 'PH' will force a proportional hazards model.

Value

A character vector of the survival table source code, unless tableOnly=TRUE in which case a data frame is returned

See Also

survival::survfit

Examples

# Kaplan-Mieir survival probabilities with time displayed in years
data("pembrolizumab")
rm_survtime(data=pembrolizumab,time='os_time',status='os_status',
strata="cohort",type='KM',survtimes=seq(12,72,12),
survtimesLbls=seq(1,6,1),
survtimeunit='years')

# Cox Proportional Hazards survivial probabilities
rm_survtime(data=pembrolizumab,time='os_time',status='os_status',
strata="cohort",type='PH',survtimes=seq(12,72,12),survtimeunit='months')

# Cox Proportional Hazards survivial probabilities controlling for age
rm_survtime(data=pembrolizumab,time='os_time',status='os_status',
covs='age',strata="cohort",survtimes=seq(12,72,12),survtimeunit='months')

Combine univariate and multivariable regression tables

Description

This function will combine rm_uvsum and rm_mvsum outputs into a single table. The tableOnly argument must be set to TRUE when tables to be combined are created. The resulting table will be in the same order as the uvsum table and will contain the same columns as the uvsum and mvsum tables, but the p-values will be combined into a single column. There must be a variable overlapping between the uvsum and mvsum tables and all variables in the mvsum table must also appear in the uvsum table.

Usage

rm_uv_mv(
  uvsumTable,
  mvsumTable,
  covTitle = "",
  vif = FALSE,
  showN = FALSE,
  showEvent = FALSE,
  caption = NULL,
  tableOnly = FALSE,
  chunk_label,
  fontsize
)

Arguments

Value

A character vector of the table source code, unless tableOnly=TRUE in which case a data frame is returned

See Also

rm_uvsum,rm_mvsum

Examples

require(survival)
data("pembrolizumab")
uvTab <- rm_uvsum(response = c('os_time','os_status'),
covs=c('age','sex','baseline_ctdna','l_size','change_ctdna_group'),
data=pembrolizumab,tableOnly=TRUE)
mv_surv_fit <- coxph(Surv(os_time,os_status)~age+sex+
baseline_ctdna+l_size+change_ctdna_group, data=pembrolizumab)
uvTab <- rm_mvsum(mv_surv_fit)

#linear model
uvtab<-rm_uvsum(response = 'baseline_ctdna',
covs=c('age','sex','l_size','pdl1','tmb'),
data=pembrolizumab,tableOnly=TRUE)
lm_fit=lm(baseline_ctdna~age+sex+l_size+tmb,data=pembrolizumab)
mvtab<-rm_mvsum(lm_fit,tableOnly = TRUE)
rm_uv_mv(uvtab,mvtab,tableOnly=TRUE)

#logistic model
uvtab<-rm_uvsum(response = 'os_status',
covs=c('age','sex','l_size','pdl1','tmb'),
data=pembrolizumab,family = binomial,tableOnly=TRUE)
logis_fit<-glm(os_status~age+sex+l_size+pdl1+tmb,data = pembrolizumab,family = 'binomial')
mvtab<-rm_mvsum(logis_fit,tableOnly = TRUE)
rm_uv_mv(uvtab,mvtab,tableOnly=TRUE)

Output several univariate models nicely in a single table

Description

#'A table with the model parameters from running separate univariate models on each covariate. For factors with more than two levels a Global p-value is returned.

Usage

rm_uvsum(
  response,
  covs,
  data,
  digits = getOption("reportRmd.digits", 2),
  covTitle = "",
  caption = NULL,
  tableOnly = FALSE,
  removeInf = FALSE,
  p.adjust = "none",
  unformattedp = FALSE,
  whichp = c("levels", "global", "both"),
  chunk_label,
  gee = FALSE,
  id = NULL,
  corstr = NULL,
  family = NULL,
  type = NULL,
  offset = NULL,
  strata = 1,
  nicenames = TRUE,
  showN = TRUE,
  showEvent = TRUE,
  CIwidth = 0.95,
  reflevel = NULL,
  returnModels = FALSE,
  fontsize,
  forceWald = FALSE
)

Arguments

Details

Global p-values are likelihood ratio tests for lm, glm and polr models. For lme models an attempt is made to re-fit the model using ML and if,successful LRT is used to obtain a global p-value. For coxph models the model is re-run without robust variances with and without each variable and a LRT is presented. If unsuccessful a Wald p-value is returned. For GEE and CRR models Wald global p-values are returned.

As of version 0.1.1 if global p-values are requested they will be included in the p-value column.

The number of decimals places to display the statistics can be changed with digits, but this will not change the display of p-values. If more significant digits are required for p-values then use tableOnly=TRUE and format as desired.

tidyselect can only be used for response and covs variables. Additional arguments must be passed in using characters

Value

A character vector of the table source code, unless tableOnly=TRUE in which case a data frame is returned

See Also

lm,glm, cmprsk::crr, survival::coxph, nlme::lme, geepack::geeglm, MASS::glm.nb

Examples

# Examples are for demonstration and are not meaningful
# Coxph model with 90% CI
data("pembrolizumab")
rm_uvsum(response = c('os_time','os_status'),
covs=c('age','sex','baseline_ctdna','l_size','change_ctdna_group'),
data=pembrolizumab,CIwidth=.9)

# Linear model with default 95% CI
rm_uvsum(response = 'baseline_ctdna',
covs=c('age','sex','l_size','pdl1','tmb'),
data=pembrolizumab)

# Logistic model with default 95% CI
rm_uvsum(response = 'os_status',
covs=c('age','sex','l_size','pdl1','tmb'),
data=pembrolizumab,family = binomial)
# Poisson models returned as model list
mList <- rm_uvsum(response = 'baseline_ctdna',
covs=c('age','sex','l_size','pdl1','tmb'),
data=pembrolizumab, returnModels=TRUE)
#'
# GEE on correlated outcomes
data("ctDNA")
rm_uvsum(response = 'size_change',
covs=c('time','ctdna_status'),
gee=TRUE,
id='id', corstr="exchangeable",
family=gaussian("identity"),
data=ctDNA,showN=TRUE)

# Using tidyselect
pembrolizumab |> rm_uvsum(response = sex,
covs = c(age, cohort))

Round with sprintf formatting

Description

Rounds values using sprintf for precise decimal formatting. Used internally by psthr0().

Usage

round_sprintf(value, digits)

Arguments

Value

Character string with exactly 'digits' decimal places

Output a scrollable table

Description

This function accepts the output of a aa call to knitr::kable or reportRmd::outTable and, if the output format is html, will produce a scrollable table. Otherwise a regular table will be output for pandoc/latex

Usage

scrolling_table(knitrTable, pixelHeight = 500)

Arguments

Examples

data("pembrolizumab")
tab <- rm_covsum(data=pembrolizumab,maincov = 'change_ctdna_group',
covs=c('age','cohort','sex','pdl1','tmb','l_size'),full=FALSE)
scrolling_table(tab,pixelHeight=300)

Set variable labels

Description

Assign variable labels to a data.frame from a lookup table.

Usage

set_labels(data, names_labels)

Arguments

Details

Useful if variable labels have been imported from a data dictionary. The first column in names_labels must contain the variable name and the second column the variable label. The column names are not used.

If no label is provided then the existing label will not be changed. To remove a label set the label to NA.

See Also

set_var_labels() for setting individual variable labels, extract_labels() for creating a data frame of all variable labels, clear_labels() for removing variable labels

Examples

data("ctDNA")
# create data frame with labels
lbls <- data.frame(c1=c('cohort','size_change'),
c2=c('Cancer cohort','Change in tumour size'))
# set labels and return labelled data frame
set_labels(ctDNA,lbls)

Set variable labels

Description

Set variable labels for a data frame using name-label pairs.

Usage

set_var_labels(data, ...)

Arguments

Details

If no label is provided for a variable then the existing label will not be changed. To remove a label set the label to NA.

See Also

set_labels() for setting variable labels using a data frame, extract_labels() for creating a data frame of all variable labels, clear_labels() for removing variable labels

Examples

# set labels using name-label pairs
# and return labelled data frame
data("ctDNA")
ctDNA |> set_var_labels(
   ctdna_status="detectable ctDNA",
  cohort="A cohort label")

Validate and prepare input data

Description

Validate and prepare input data

Usage

validate_and_prepare_data(data, response, cov = NULL, print.n.missing = TRUE)

Arguments

Create a summary table for an individual covariate

Description

Create a summary table for an individual covariate

Usage

xvar_function(
  xvar,
  data,
  grp,
  covTitle = "",
  digits = 1,
  digits.cat = 0,
  iqr = TRUE,
  all.stats = FALSE,
  pvalue = TRUE,
  effSize = FALSE,
  show.tests = FALSE,
  percentage = "col"
)

Arguments

Value

A data frame is returned