Correlation / partial correlation table

Formats a tidy data frame of (partial) correlation results into a publication-ready table. Column-name arguments accept character strings. Defaults match a typical correlation results frame with columns named variable, outcome, r, and p.

Formatting defaults are inherited from clerk_options() and can be overridden per call.

Usage

tbl_correlation(
  data,
  predictor = "variable",
  outcome = "outcome",
  r = "r",
  p = "p",
  n = NULL,
  extra_cols = NULL,
  domains = list(),
  fdr = FALSE,
  fdr_within = NULL,
  r_digits = NULL,
  p_digits = NULL,
  p_threshold = NULL,
  p_style = NULL,
  stars = NULL,
  fdr_ns = NULL,
  fdr_alpha = NULL,
  domain_other = NULL,
  pivot = FALSE,
  output = c("gt", "html", "latex")
)

Arguments

data

A tidy data frame of correlation results.

predictor

Character string. Predictor column name. Default "variable".

outcome

Character string. Outcome column name. Default "outcome".

r

Character string. Correlation coefficient column. Default "r".

p

Character string. P-value column. Default "p".

n

Character string or NULL. Sample size column. Default NULL.

extra_cols

Character vector of additional columns to carry through.

domains

A named list mapping predictor names to domain/section labels. An entry may itself be a named list to create a nested sub-section within a domain (e.g. repeated timepoints) – see vignette("formatting-options").

fdr

Logical. Apply BH FDR correction (default FALSE).

fdr_within

Character string or NULL. Column to group FDR within.

r_digits

Integer. Decimal places for r.

p_digits

Integer. Decimal places for p-values.

p_threshold

Numeric. P-values below this are shown as "< {threshold}". Inherits from clerk_options()$p_threshold if NULL.

p_style

Character. P-value style.

stars

Logical. Append significance stars.

fdr_ns

Logical. Replace non-surviving FDR p-values with "ns".

fdr_alpha

Numeric. Alpha level for FDR survival (BH-adjusted p).

domain_other

Character string. Label for variables not assigned to any domain. Default "" (blank). Inherits from clerk_options()$domain_other.

pivot

Logical. Pivot to wide format (default FALSE).

output

Character string. One of "gt" (default), "html", or "latex".

Value

A clerk_tbl object with type "correlation".

Examples

tbl_correlation(
  clerk_cor_example,
  domains = list(
    "Metabolic"      = c("hdl", "glucose", "bmi"),
    "Anthropometric" = c("waist", "systolic_bp"),
    "Mental health"  = c("bdi", "panas_neg")
  ),
  fdr    = TRUE,
  output = "gt"
) |> clerk_render(title = "Partial correlations (age + sex controlled)")


  
Partial correlations (age + sex controlled)
    

      
Outcome
      
r
      
p
      
p (FDR)
    
Metabolic
    
hdl
tmt_time
+0.190
= 0.008
= 0.032
glucose
tmt_time
-0.229
= 0.398
ns
bmi
tmt_time
-0.086
= 0.013
= 0.042
hdl
verbal_fluency
+0.078
= 0.072
ns
glucose
verbal_fluency
+0.216
= 0.003
= 0.024
bmi
verbal_fluency
+0.022
= 0.207
ns
Anthropometric
    
waist
tmt_time
+0.279
= 0.002
= 0.024
systolic_bp
tmt_time
+0.195
= 0.379
ns
waist
verbal_fluency
+0.047
= 0.185
ns
systolic_bp
verbal_fluency
-0.105
= 0.077
ns
Mental health
    
bdi
tmt_time
+0.096
= 0.109
ns
panas_neg
tmt_time
+0.157
= 0.006
= 0.032
bdi
verbal_fluency
-0.176
= 0.070
ns
panas_neg
verbal_fluency
+0.232
= 0.117
ns

    
life_satisfaction
tmt_time
+0.247
= 0.117
ns
life_satisfaction
verbal_fluency
+0.201
= 0.234
ns
p (FDR): Benjamini-Hochberg false discovery rate correction applied.