Create a correlation table with summary statistics in APA style

This function creates (and optionally saves) a correlation table with summary statistics. It accepts correlation matrices from various functions in this package as its first argument.

report_cor_table(
  cor_matrix,
  ci_type = deprecated(),
  ci_width = deprecated(),
  ci = deprecated(),
  n = deprecated(),
  add_distributions = FALSE,
  data = NULL,
  filename = NULL,
  notes = list(NULL),
  stars = NULL,
  add_title = FALSE,
  extras = NULL,
  apa_style = TRUE,
  ...
)

Source

Based on the apaTables apa.cor.table() function, but adapted to accept weighted correlation matrices and work with the gt package instead. Code for calculation of confidence intervals adapted from https://medium.com/@shandou/how-to-compute-confidence-interval-for-pearsons-r-a-brief-guide-951445b9cb2d`

Arguments

cor_matrix

A correlation matrix, for example returned from cor_matrix(), svy_cor_matrix(), or cor_matrix_mi().

ci_type

Recalculating CIs in this function has been removed. Please generate CIs in cor_matrix().

ci_width

Use conf_level in cor_matrix() instead.

ci

Superseded by functionality in cor_matrix().

n

No longer used.

add_distributions

Logical. Add graphs showing variable distributions? Works with both regular data frames and survey design objects.

data

Original data, only needed if add_distributions = TRUE. Can be a regular data frame or a survey design object. For survey data, distributions will be properly weighted using svyhist() and svysmooth().

filename

The file name to create on disk. Include '.html' extension to best preserve formatting (see gt::gtsave for details).

notes

List of additional notes to show under the table.

stars

A character vector to change the significance symbols (see details below)

add_title

Should title be added to table? Set to TRUE for default title or provide a character string for custom title.

extras

Tibble of additional columns to be added after the descriptives column - needs to be sorted in the same order as the desc element in the cor_matrix unless there is a row_names column. If there is, this will be used to match it to the desc rows.

apa_style

Logical, should APA-style formatting be applied.

...

Arguments passed on to plot_distributions

plot_type

Type of plot that should be produced - histogram or density plot. If auto, histograms are produced for variables that take fewer than 10 unique values, density plots for others. If a number is provided, that number is used as the maximum number of unique values for which a histogram is used.

hist_align_y

Should histograms use the same y-axis, so that bin heights are comparable? Defaults to FALSE

plot_theme

Additional theme_ commands to be added to each plot

Value

A gt table that can be further formatted with gt-functions.

Examples

# Basic correlation table
cor_matrix(iris, var_names = c(Sepal.Length = "Sepal Length",
                                Sepal.Width = "Sepal Width")) %>%
  report_cor_table()


  
Variable
      
M (SD)
      
1
    
Sepal Length

5.84 (0.83)
 
Sepal Width

3.06 (0.44)
-.12 
[-0.27, 0.04]
M and SD are used to represent mean and standard deviation, respectively.
    
Values in square brackets indicate the confidence interval for each correlation.
    
† p < .1, * p < .05, ** p < .01, *** p < .001
    

# With distributions
cor_matrix(iris) %>%
  report_cor_table(add_distributions = TRUE, data = iris,
                   add_title = "Iris correlations and distributions")


  
Iris correlations and distributions
    
Variable
      
M (SD)
      
Distributions
      
1
      
2
      
3
    
Sepal.Length

5.84 (0.83)

 

 

 
Sepal.Width

3.06 (0.44)

-.12 
[-0.27, 0.04]
 

 
Petal.Length

3.76 (1.77)

.87 ***
[0.83, 0.91]
-.43 ***
[-0.55, -0.29]
 
Petal.Width

1.20 (0.76)

.82 ***
[0.76, 0.86]
-.37 ***
[-0.50, -0.22]
.96 ***
[0.95, 0.97]
M and SD are used to represent mean and standard deviation, respectively.
    
Values in square brackets indicate the confidence interval for each correlation.
    
† p < .1, * p < .05, ** p < .01, *** p < .001
    

# Using ESS health data
cor_matrix(ess_health, var_names = c(health = "Health",
                                      dosprt = "Physical activity",
                                      etfruit = "Fruit consumption")) %>%
  report_cor_table()


  
Variable
      
M (SD)
      
1
      
2
    
Health

2.26 (0.92)
 

 
Physical activity

3.26 (2.65)
-.18 ***
[-0.20, -0.16]
 
Fruit consumption

3.04 (1.43)
.06 ***
[0.04, 0.08]
-.11 ***
[-0.13, -0.09]
M and SD are used to represent mean and standard deviation, respectively.
    
Values in square brackets indicate the confidence interval for each correlation.
    
† p < .1, * p < .05, ** p < .01, *** p < .001
    

# With survey data and distributions
if (FALSE) { # \dontrun{
library(survey)
library(srvyr)
data(api)
dstrat <- apistrat %>% as_survey_design(1, strata = stype, fpc = fpc, weight = pw)
svy_cor_matrix(dstrat, var_names = c(enroll = "Enrollment",
                                      api00 = "API 2000",
                                      api99 = "API 1999")) %>%
  report_cor_table(add_distributions = TRUE, data = dstrat)
} # }