quick_cor: 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,
  ...
)

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

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).

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.

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

Examples

Run this code

# 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

Run the code above in your browser using DataLab