ComplexHeatmap of Correlation Matrix Across Iterations — plot_correlation

Computes correlation between values (e.g., p-values, t-statistics) across iterations per feature, reshapes the data into wide format, calculates a correlation matrix, and visualizes it as a clustered heatmap.

Usage

plot_correlation_heatmap(
  data,
  value_col,
  iter_col,
  method = "pearson",
  row_names = NULL,
  title = NULL,
  file = NULL,
  width = 8,
  height = 8
)

Arguments

data: A data frame with columns: `feature`, an iteration column (e.g., `perm_id`), and a numeric value column (e.g., `p_value`, `T_obs`).
value_col: A string specifying the column name in `data` to use for correlation (e.g., `"p_value"` or `"T_obs"`).
iter_col: A string specifying the column name in `data` to use as the iteration identifier (e.g., `"iteration"`, `"perm_id"`).
method: A string specifying the correlation method to use. One of `"pearson"` (default), `"spearman"`, or `"kendall"`.
row_names: Optional string to display as the row title in the heatmap.
title: Optional string for the main heatmap title.
file: Optional file path to save the plot (e.g., `"plot.pdf"` or `"plot.png"`). If `NULL`, the plot is shown interactively.
width: Width of the plot in inches (default = 8).
height: Height of the plot in inches (default = 8).

Value

Invisibly returns `NULL`. The function is called for its side effect of drawing or saving a heatmap.

Details

This function is useful for visualizing the stability or similarity of a given statistic (like p-values or test statistics) across multiple iterations or resampling runs. It internally uses `compute_correlation_matrix()` to compute the correlation matrix.

The upper triangle of the matrix is used to calculate a summary mean correlation, which is displayed above the heatmap.