Create a merged gtsummary table by faceting comparisons across multiple categorical variables

Generates a series of comparison tables using MakeComparisonTable() for each categorical variable (facet) in the provided list and merges them side-by-side using gtsummary::tbl_merge(). This function extends the functionality of MakeComparisonTable() by automatically detecting which facet variables are categorical (factor or character) and producing a faceted summary of how the main comparison variable (e.g., Cluster, TreatmentArm) differs across multiple categorical dimensions such as Race, Sex, or HIV status.

Usage

MakeFacetCatComparisonTable(
  data,
  FacetVariables,
  variables,
  covariates = NULL,
  value_digits = 2,
  p_digits = 3,
  AddEffectSize = FALSE,
  effect_size_digits = 2,
  AddPairwise = FALSE,
  PairwiseMethod = "bonferroni",
  Parametric = TRUE,
  ParametricDisplay = NULL,
  IncludeOverallN = FALSE,
  IncludeMissing = FALSE,
  suppress_warnings = FALSE,
  Referent = NULL,
  IncludeOverallStats = FALSE,
  ShowPositiveBinaryOnLabel = TRUE,
  CompFun = MakeComparisonTable,
  Relabel = TRUE,
  TreatOrdinalAs = "Categorical",
  ...,
  DataFrame = lifecycle::deprecated(),
  Variables = lifecycle::deprecated(),
  Covariates = lifecycle::deprecated(),
  ValueDigits = lifecycle::deprecated(),
  pDigits = lifecycle::deprecated(),
  EffectSizeDigits = lifecycle::deprecated()
)

Arguments

data: A data frame containing all variables to be analyzed.
FacetVariables: A character vector of variable names to facet by. The function automatically selects those that are categorical (factor or character).
variables: A character string naming the variable(s) being compared (e.g., "Cluster").
covariates: Optional character vector of covariate names to adjust for.
value_digits: Number of decimal digits to display for numeric values (default = 2).
p_digits: Number of decimal digits to display for p-values (default = 3).
AddEffectSize: Logical; if TRUE, include effect sizes (default = FALSE).
effect_size_digits: Decimal digits for effect size values (default = 2).
AddPairwise: Logical; if TRUE, include pairwise comparisons (default = FALSE).
PairwiseMethod: Method for pairwise comparison p-value adjustment (default = "bonferroni").
Parametric: Logical; if TRUE, use parametric tests (default = TRUE).
ParametricDisplay: Optional vector specifying which statistics to display for parametric tests.
IncludeOverallN: Logical; if TRUE, adds overall N to the table (default = FALSE).
IncludeMissing: Logical; if TRUE, includes missing categories (default = FALSE).
suppress_warnings: Logical; suppress internal warnings (default = FALSE).
Referent: Optional string specifying the referent category for binary or categorical comparisons.
IncludeOverallStats: Logical; if TRUE, adds overall descriptive statistics (default = FALSE).
ShowPositiveBinaryOnLabel: Logical; if TRUE, labels binary variables with positive outcome (default = TRUE).
CompFun: Comparison function to apply; defaults to MakeComparisonTable.
Relabel: Logical; if TRUE (default), use attached variable labels.
TreatOrdinalAs: How ordinal variables are treated in each table.
...: Additional arguments passed to the comparison function.
DataFrame: Deprecated (since 19.15.0). Use data instead.
Variables: Deprecated (since 19.15.0). Use variables instead.
Covariates: Deprecated (since 19.15.0). Use covariates instead.
ValueDigits: Deprecated (since 19.15.0). Use value_digits instead.
pDigits: Deprecated (since 19.15.0). Use p_digits instead.
EffectSizeDigits: Deprecated (since 19.15.0). Use effect_size_digits instead.

Value

A gtsummary table created by merging each facet's MakeComparisonTable() output side-by-side using gtsummary::tbl_merge(). Each facet variable is labeled with its own tab spanner header for clarity.

Details

MakeFacetCatComparisonTable

Use this when the same set of measures needs to be compared across several different groupings at once - by diagnosis, and by sex, and by APOE status - and those comparisons belong in one table rather than three.

Running MakeComparisonTable() once per grouping produces tables that are each correct but cannot be read against each other: the variables are listed three times, and spotting that a biomarker separates diagnosis groups but not sexes means looking back and forth between pages. Merging them puts one row per variable and one column block per grouping, so that comparison is a left-to-right read.

Facet variables that are not categorical are dropped automatically, so a vector of candidate groupings can be passed without pre-filtering it.

Every argument that controls the individual tables - AddPairwise, covariates, Parametric, and the rest - is passed through to each facet, so the blocks stay consistent with one another.

Examples

# \donttest{
data(SampleData)
data(SampleVariableTypes)

Labelled <- RevalueData(SampleData, SampleVariableTypes)$RevaluedData

vars_Compare <- c("age", "AXL", "Adiponectin", "tau", "p_tau")

# The same five measures compared across two groupings at once
MakeFacetCatComparisonTable(
  data = Labelled,
  FacetVariables = c("Diagnosis", "sex"),
  variables = vars_Compare
)


  Comparison by Diagnosis (values: mean (SD)).
  Characteristic
      
        Diagnosis
      
      
        sex
      
    
Control

N = 242¹
      Impaired

N = 91¹
      p-value²
      Test²
      Female

N = 204¹
      Male

N = 129¹
      p-value²
      Test²
    
Age
72.75 (13.26)
71.78 (13.12)
0.553
Welch t-test
73.51 (12.59)
70.80 (14.04)
0.0818
Welch t-test
AXL receptor tyrosine kinase
0.28 (0.46)
0.34 (0.41)
0.238
Welch t-test
0.29 (0.45)
0.31 (0.45)
0.653
Welch t-test
Adiponectin
-5.26 (0.65)
-5.10 (0.69)
0.0539
Welch t-test
-5.24 (0.65)
-5.18 (0.69)
0.442
Welch t-test
Tau protein
5.61 (0.49)
6.14 (0.55)
<0.001
Welch t-test
5.75 (0.56)
5.73 (0.56)
0.773
Welch t-test
Phosphorylated tau protein
3.94 (0.42)
4.30 (0.48)
<0.001
Welch t-test
4.05 (0.46)
4.02 (0.47)
0.589
Welch t-test
¹ Mean (SD)
    
² p-values use Welch t-test (two groups) or ANOVA (more than two groups) for continuous outcomes and chi-square or Fisher’s exact test, selected from expected counts for categorical outcomes.
    

# Non-categorical facets are ignored, so a mixed vector is safe
MakeFacetCatComparisonTable(
  data = Labelled,
  FacetVariables = c("Diagnosis", "age", "sex"),
  variables = c("AXL", "tau")
)


  Comparison by Diagnosis (values: mean (SD)).
  Characteristic
      
        Diagnosis
      
      
        sex
      
    
Control

N = 242¹
      Impaired

N = 91¹
      p-value²
      Test²
      Female

N = 204¹
      Male

N = 129¹
      p-value²
      Test²
    
AXL receptor tyrosine kinase
0.28 (0.46)
0.34 (0.41)
0.238
Welch t-test
0.29 (0.45)
0.31 (0.45)
0.653
Welch t-test
Tau protein
5.61 (0.49)
6.14 (0.55)
<0.001
Welch t-test
5.75 (0.56)
5.73 (0.56)
0.773
Welch t-test
¹ Mean (SD)
    
² p-values use Welch t-test (two groups) or ANOVA (more than two groups) for continuous outcomes and chi-square or Fisher’s exact test, selected from expected counts for categorical outcomes.
    

# Options are forwarded to every facet
MakeFacetCatComparisonTable(
  data = Labelled,
  FacetVariables = c("Diagnosis", "sex"),
  variables = vars_Compare,
  AddEffectSize = TRUE
)


  Comparison by Diagnosis (values: mean (SD)).
  Characteristic
      
        Diagnosis
      
      
        sex
      
    
Control

N = 242¹
      Impaired

N = 91¹
      p-value²
      Test²
      Effect size
      ES method
      Female

N = 204¹
      Male

N = 129¹
      p-value²
      Test²
      Effect size
      ES method
    
Age
72.75 (13.26)
71.78 (13.12)
0.553
Welch t-test
0.07
|d|
73.51 (12.59)
70.80 (14.04)
0.0818
Welch t-test
0.21
|d|
AXL receptor tyrosine kinase
0.28 (0.46)
0.34 (0.41)
0.238
Welch t-test
0.14
|d|
0.29 (0.45)
0.31 (0.45)
0.653
Welch t-test
0.05
|d|
Adiponectin
-5.26 (0.65)
-5.10 (0.69)
0.0539
Welch t-test
0.25
|d|
-5.24 (0.65)
-5.18 (0.69)
0.442
Welch t-test
0.09
|d|
Tau protein
5.61 (0.49)
6.14 (0.55)
<0.001
Welch t-test
1.03
|d|
5.75 (0.56)
5.73 (0.56)
0.773
Welch t-test
0.04
|d|
Phosphorylated tau protein
3.94 (0.42)
4.30 (0.48)
<0.001
Welch t-test
0.83
|d|
4.05 (0.46)
4.02 (0.47)
0.589
Welch t-test
0.06
|d|
¹ Mean (SD)
    
² p-values use Welch t-test (two groups) or ANOVA (more than two groups) for continuous outcomes and chi-square or Fisher’s exact test, selected from expected counts for categorical outcomes.
    

# Covariate adjustment, applied within each grouping
MakeFacetCatComparisonTable(
  data = Labelled,
  FacetVariables = c("Diagnosis", "sex"),
  variables = c("AXL", "Adiponectin", "tau", "p_tau"),
  covariates = "age"
)


  Comparison by Diagnosis (values: mean (SD)). p-values adjusted for Age.
  Characteristic
      
        Diagnosis
      
      
        sex
      
    
Control

N = 242¹
      Impaired

N = 91¹
      p-value²
      Test²
      Female

N = 204¹
      Male

N = 129¹
      p-value²
      Test²
    
AXL receptor tyrosine kinase
0.28 (0.46)
0.34 (0.41)
0.257
ANCOVA (Type II)
0.29 (0.45)
0.31 (0.45)
0.427
ANCOVA (Type II)
Adiponectin
-5.26 (0.65)
-5.10 (0.69)
0.0704
ANCOVA (Type II)
-5.24 (0.65)
-5.18 (0.69)
0.552
ANCOVA (Type II)
Tau protein
5.61 (0.49)
6.14 (0.55)
<0.001
ANCOVA (Type II)
5.75 (0.56)
5.73 (0.56)
0.667
ANCOVA (Type II)
Phosphorylated tau protein
3.94 (0.42)
4.30 (0.48)
<0.001
ANCOVA (Type II)
4.05 (0.46)
4.02 (0.47)
0.516
ANCOVA (Type II)
¹ Mean (SD)
    
² p-values use Type II ANCOVA for continuous outcomes and logistic likelihood-ratio test for binary outcomes or multinomial likelihood-ratio test for multicategory outcomes for categorical outcomes.
    

# A three-level grouping alongside a two-level one, with pairwise contrasts
Labelled$ApoeGroup <- factor(
  dplyr::case_when(
    Labelled$Genotype %in% c("E2E2", "E2E3") ~ "E2 carrier",
    Labelled$Genotype == "E3E3" ~ "E3/E3",
    TRUE ~ "E4 carrier"
  ),
  levels = c("E2 carrier", "E3/E3", "E4 carrier")
)

MakeFacetCatComparisonTable(
  data = Labelled,
  FacetVariables = c("Diagnosis", "ApoeGroup"),
  variables = c("age", "tau", "p_tau"),
  AddPairwise = TRUE
)


  Comparison by Diagnosis (values: mean (SD)). Pairwise p-values are bonferroni-adjusted within outcome.
  Characteristic
      
        Diagnosis
      
      
        ApoeGroup
      
    
Control

N = 242¹
      Impaired

N = 91¹
      p-value²
      Test²
      Control - Impaired
      E2 carrier

N = 39¹
      E3/E3

N = 167¹
      E4 carrier

N = 127¹
      p-value²
      Test²
      E2 carrier - E3/E3
      E2 carrier - E4 carrier
      E3/E3 - E4 carrier
    
Age
72.75 (13.26)
71.78 (13.12)
0.553
Welch t-test
0.553
71.36 (13.33)
72.04 (13.87)
73.38 (12.33)
0.599
ANOVA
1
1
1
Tau protein
5.61 (0.49)
6.14 (0.55)
<0.001
Welch t-test
<0.001
5.65 (0.44)
5.67 (0.55)
5.89 (0.58)
0.0121
ANOVA
1
0.0643
0.0218
Phosphorylated tau protein
3.94 (0.42)
4.30 (0.48)
<0.001
Welch t-test
<0.001
3.93 (0.37)
3.99 (0.47)
4.15 (0.46)
0.00352
ANOVA
1
0.0104
0.0111
¹ Mean (SD)
    
² p-values use Welch t-test (two groups) or ANOVA (more than two groups) for continuous outcomes and chi-square or Fisher’s exact test, selected from expected counts for categorical outcomes. Pairwise p-values are bonferroni-adjusted within outcome.
    
# }

Characteristic	Diagnosis				sex
Characteristic	Control N = 242¹	Impaired N = 91¹	p-value²	Test²	Female N = 204¹	Male N = 129¹	p-value²	Test²
Age	72.75 (13.26)	71.78 (13.12)	0.553	Welch t-test	73.51 (12.59)	70.80 (14.04)	0.0818	Welch t-test
AXL receptor tyrosine kinase	0.28 (0.46)	0.34 (0.41)	0.238	Welch t-test	0.29 (0.45)	0.31 (0.45)	0.653	Welch t-test
Adiponectin	-5.26 (0.65)	-5.10 (0.69)	0.0539	Welch t-test	-5.24 (0.65)	-5.18 (0.69)	0.442	Welch t-test
Tau protein	5.61 (0.49)	6.14 (0.55)	<0.001	Welch t-test	5.75 (0.56)	5.73 (0.56)	0.773	Welch t-test
Phosphorylated tau protein	3.94 (0.42)	4.30 (0.48)	<0.001	Welch t-test	4.05 (0.46)	4.02 (0.47)	0.589	Welch t-test
¹ Mean (SD)
² p-values use Welch t-test (two groups) or ANOVA (more than two groups) for continuous outcomes and chi-square or Fisher’s exact test, selected from expected counts for categorical outcomes.

Usage

Arguments

Value

Details

See also

Examples