rm_covsum: Add header row to table Outputs a descriptive covariate table

In reportRmd: Tidy Presentation of Clinical Reporting

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

data	dataframe containing data
covs	Covariate names to summarize. Accepts either a character vector (e.g., c("age", "sex")) or tidyselect bare names (e.g., c(age, sex)). Can also be specified using the xvars alias.
maincov	Grouping variable. Accepts either a character string (e.g., "sex") or a tidyselect bare name (e.g., sex). Can also be specified using the grp alias.
caption	character containing table caption (default is no caption)
tableOnly	Logical, if TRUE then a dataframe is returned, otherwise a formatted printed object is returned (default).
covTitle	character with the names of the covariate (predictor) column. The default is to leave this empty for output or, for table only output to use the column name 'Covariate'.
digits	number of digits for summarizing mean data
digits.cat	number of digits for the proportions when summarizing categorical data (default: 0)
nicenames	boolean indicating if you want to replace . and _ in strings with a space
IQR	boolean indicating if you want to display the inter quantile range (Q1,Q3) as opposed to (min,max) in the summary for continuous variables
all.stats	boolean indicating if all summary statistics (Q1,Q3 + min,max on a separate line) should be displayed. Overrides IQR.
pvalue	boolean indicating if you want p-values included in the table
effSize	boolean indicating if you want effect sizes included in the table. Can only be obtained if pvalue is also requested. Effect sizes calculated include Cramer's V for categorical variables, Cohen's d, Wilcoxon r, or Eta-squared for numeric/continuous variables.
p.adjust	p-adjustments to be performed. Uses the p.adjust function from base R
unformattedp	boolean indicating if you would like the p-value to be returned unformatted (ie not rounded or prefixed with '<'). Best used with tableOnly = T and outTable function. See examples.
show.tests	boolean indicating if the type of statistical test and effect size used should be shown in a column beside the pvalues. Ignored if pvalue=FALSE.
testcont	test of choice for continuous variables,one of rank-sum (default) or ANOVA
testcat	test of choice for categorical variables,one of Chi-squared (default) or Fisher
full	boolean indicating if you want the full sample included in the table, ignored if maincov is NULL
include_missing	Option to include NA values of maincov. NAs will not be included in statistical tests
percentage	choice of how percentages are presented, one of column (default) or row
dropLevels	logical, indicating if empty factor levels be dropped from the output, default is TRUE.
excludeLevels	a named list of covariate levels to exclude from statistical tests in the form list(varname =c('level1','level2')). These levels will be excluded from association tests, but not the table. This can be useful for levels where there is a logical skip (ie not missing, but not presented). Ignored if pvalue=FALSE.
numobs	named list overriding the number of people you expect to have the covariate
fontsize	PDF/HTML output only, manually set the table fontsize
chunk_label	only used if output is to Word to allow cross-referencing
xvars	Alias for covs. Supports tidyselect.
grp	Alias for maincov. Supports tidyselect.

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.\Sexpr[results=rd]{tools:::Rd_expr_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. \Sexpr[results=rd]{tools:::Rd_expr_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

reportRmd documentation built on March 20, 2026, 5:06 p.m.