quick_cor: Quick Correlation Analysis with Heatmap Visualization

In evanverse: Utility Functions for Data Analysis and Visualization

Quick Correlation Analysis with Heatmap Visualization

Description

Perform correlation analysis with automatic p-value calculation and publication-ready heatmap visualization. Supports multiple correlation methods and significance testing with optional multiple testing correction.

Usage

quick_cor(
  data,
  vars = NULL,
  method = c("pearson", "spearman", "kendall"),
  use = "pairwise.complete.obs",
  p_adjust_method = c("none", "holm", "hochberg", "hommel", "bonferroni", "BH", "BY",
    "fdr"),
  sig_level = c(0.001, 0.01, 0.05),
  type = c("full", "upper", "lower"),
  show_coef = FALSE,
  show_sig = TRUE,
  hc_order = TRUE,
  hc_method = "complete",
  palette = "gradient_rd_bu",
  lab_size = 3,
  title = NULL,
  show_axis_x = TRUE,
  show_axis_y = TRUE,
  axis_x_angle = 45,
  axis_y_angle = 0,
  axis_text_size = 10,
  verbose = TRUE,
  ...
)

Arguments

data	A data frame containing numeric variables.
vars	Optional character vector specifying which variables to include. If NULL (default), all numeric columns will be used.
method	Character. Correlation method: "pearson" (default), "spearman", or "kendall".
use	Character. Method for handling missing values, passed to cor(). Default is "pairwise.complete.obs". Other options: "everything", "all.obs", "complete.obs", "na.or.complete".
p_adjust_method	Character. Method for p-value adjustment for multiple testing. Default is "none". Options: "holm", "hochberg", "hommel", "bonferroni", "BH", "BY", "fdr", "none". See p.adjust.
sig_level	Numeric vector. Significance levels for star annotations. Default is c(0.001, 0.01, 0.05) corresponding to ***, **, *.
type	Character. Type of heatmap: "full" (default), "upper", or "lower".
show_coef	Logical. Display correlation coefficients on the heatmap? Default is FALSE.
show_sig	Logical. Display significance stars on the heatmap? Default is TRUE.
hc_order	Logical. Reorder variables using hierarchical clustering? Default is TRUE.
hc_method	Character. Hierarchical clustering method if hc_order = TRUE. Default is "complete". See hclust.
palette	Character. Color palette name from evanverse palettes. Default is "gradient_rd_bu" (diverging Red-Blue palette, recommended for correlation matrices). Set to NULL to use ggplot2 defaults. Other diverging options: "piyg", "earthy_diverge", "fire_ice_duo".
lab_size	Numeric. Size of coefficient labels if show_coef = TRUE. Default is 3.
title	Character. Plot title. Default is NULL (no title).
show_axis_x	Logical. Display x-axis labels? Default is TRUE.
show_axis_y	Logical. Display y-axis labels? Default is TRUE.
axis_x_angle	Numeric. Rotation angle for x-axis labels in degrees. Default is 45. Common values: 0 (horizontal), 45 (diagonal), 90 (vertical).
axis_y_angle	Numeric. Rotation angle for y-axis labels in degrees. Default is 0 (horizontal).
axis_text_size	Numeric. Font size for axis labels. Default is 10.
verbose	Logical. Print diagnostic messages? Default is TRUE.
...	Additional arguments (currently unused, reserved for future extensions).

Details

"Quick" means easy to use, not simplified or inaccurate.

This function performs complete correlation analysis with proper statistical testing:

Correlation Methods

• Pearson: Measures linear relationships, assumes normality

• Spearman: Rank-based, robust to outliers and non-normality

• Kendall: Rank-based, better for small samples or many ties

P-value Calculation

P-values are calculated for each pairwise correlation. The function automatically uses psych::corr.test() if the psych package is installed, which provides significantly faster computation (10-100x speedup for large matrices) compared to the base R stats::cor.test() loop. If psych is not available, the function gracefully falls back to the base R implementation.

For large correlation matrices with many tests, consider using p_adjust_method to control for multiple testing (e.g., "bonferroni" or "fdr").

Performance tip: Install the psych package for faster p-value computation: install.packages("psych")

Visualization

The heatmap includes:

• Color-coded correlation coefficients (red = positive, blue = negative)

• Optional significance stars (***, **, *)

• Optional coefficient values

• Hierarchical clustering to group similar variables

• Publication-ready styling

Value

An object of class quick_cor_result containing:

plot

A ggplot object with the correlation heatmap

cor_matrix

Correlation coefficient matrix

p_matrix

P-value matrix (unadjusted)

p_adjusted

Adjusted p-value matrix (if p_adjust_method != "none")

method_used

Correlation method used

significant_pairs

Data frame of significant correlation pairs

descriptive_stats

Descriptive statistics for each variable

parameters

List of analysis parameters

timestamp

POSIXct timestamp of analysis

Important Notes

• Numeric variables only: The function automatically selects numeric columns or uses the variables specified in vars.

• Constant variables: Variables with zero variance are automatically removed with a warning.

• Sample size: The function will warn if sample sizes are very small (n < 5) after removing missing values.

• Missing values: Handled according to the use parameter. "pairwise.complete.obs" is recommended for optimal sample size usage.

• Optional dependencies: For optimal performance, install psych (fast p-value computation) and ggcorrplot (heatmap visualization). The function will work without them but may be slower or use fallback plotting.

See Also

cor, cor.test

Examples

if (requireNamespace("ggcorrplot", quietly = TRUE)) {
  # Example 1: Basic correlation analysis
  result <- quick_cor(mtcars)
  print(result)

  # Example 2: Spearman correlation with specific variables
  result <- quick_cor(
    mtcars,
    vars = c("mpg", "hp", "wt", "qsec"),
    method = "spearman"
  )

  # Example 3: Upper triangular with Bonferroni correction
  result <- quick_cor(
    iris,
    type = "upper",
    p_adjust_method = "bonferroni",
    show_coef = TRUE
  )

  # Example 4: Custom palette and title
  result <- quick_cor(
    mtcars,
    palette = "gradient_rd_bu",
    title = "Correlation Matrix of mtcars Dataset",
    hc_order = TRUE
  )

  # Example 5: Customize axis labels
  result <- quick_cor(
    mtcars,
    axis_x_angle = 90,      # Vertical x-axis labels
    axis_text_size = 12,    # Larger text
    show_axis_y = FALSE     # Hide y-axis labels
  )

  # Access components
  result$plot                 # ggplot object
  result$cor_matrix           # Correlation matrix
  result$significant_pairs    # Significant pairs
  summary(result)             # Detailed summary
}

evanverse documentation built on March 10, 2026, 5:07 p.m.