xcorrDotPlot

A vectorized, customizable method of plotting correlation dot plots in MATLAB. This function creates a dot plot representing a matrix of statistical values, comparable to R's corrplot function for many pairwise/cross correlations. More generally, it can be used for any matrix containing results like p-values or statistical tests.

Syntax:

xcorrDotPlot(data)

xcorrDotPlot(data, Name, Value, ...)

h = xcorrDotPlot(_)

Input Arguments:

(Required)

• matrix - A 2D m x n matrix (not required to be square) [data type]

Output Arguments:

(Optional)

• h - Structure array of handles to axes, dots, major/minor grid lines, title, row/col labels, text overlaying the values, and colorbar [structure]

Name-Value Pair Arguments:

(Optional; case insensitive)

Parameter	Accepted Values	Default	Description
triangle type	'lower' | 'upper' | 'full'	'full'	Determines whether to plot the lower triangle, upper triangle, or full matrix. 'lower' and 'upper' accept a trailing integer scalar k in the range [-size(matrix,1), size(matrix,2)] specifying the diagonal offset passed to tril()/triu(). 'full' requires no k.
k	integer scalar	0	Diagonal offset for 'lower' or 'upper' plot types. 0 includes the main diagonal; -1 or 1 excludes it for 'lower' or 'upper', respectively; any integer can be passed up to the size of that dimension to exclude more diagonals.
'majorgrid'	true | false | 1 | 0	true	Toggles black enclosing grid lines around all matrix cells.
'minorgrid'	true | false | 1 | 0	false	Toggles light gray grid lines intersecting data points.
'dotscale'	non-negative scalar	1	Scalar multiplier controlling the rendered size of all dots.
'rowlabels'	string | cellstr	""	1-by-n or n-by-1 array of row label strings.
'collabels'	string | cellstr	""	1-by-n or n-by-1 array of column label strings.
'alpha'	scalar in [0, 1]	0.8	Opacity of plotted dots.
'overlayvals'	'all' | 'sigonly'	''	Overlays numeric values on dots. 'sigonly' requires the 'threshold' parameter to also be set.
'threshold'	numeric scalar or matrix	[]	Significance threshold used with 'sigonly'. Values whose absolute value falls below this threshold will not have text overlaid.
'precision'	non-negative integer	2	Maximum number of decimal places for overlaid text labels.
'title'	char | string | cellstr	''	Title string displayed above the plot.
'toffset'	numeric scalar	1.2	Vertical offset of the title in normalized axes units. Increase if the title overlaps rotated column labels.

Examples

Two basic plot examples manipulating grid style and a third showcasing a full customization. See xcorrDotPlot_demo.mlx for a more complete set of examples.

Example 1 subplots and generating code

% make some fictional data
brain_regions= ["V1" "A1" "M1" "M2" "SMA" "dPFC" "vPFC" "BG" "HPC" "PPC" "Amyg" "Thal" "Cereb" "IT" "IP" "ENT"];
br= brain_regions(1:8); 

n= length(br); 

coefs= -1 + 2.*rand(n);             % simulate correlation coefficients bounded between -1 and 1
dmy_m= coefs';                      % store transpose in dummy matrix
dmy_i= logical(tril(coefs, -1));    % index lower triangle
coefs(dmy_i)= dmy_m(dmy_i);         % store as lower triangle of original
coefs(logical(eye(n)))= 0;          % zero out placeholders on the identity line
coefs= coefs + eye(n);              % place autocorrelation into the random coef matrix
d_scale= 200;                       % scale dot size

figure;
subplot(1, 3, 1); 
h1= xcorrDotPlot(coefs, 'dotscale', d_scale, 'title', 'Normal grid', ... 
                 'rowlabels', br, 'collabels', br);
h1.cbar.Location= 'southoutside'; 

subplot(1, 3, 2); 
h2= xcorrDotPlot(coefs, 'dotscale', d_scale, 'title', 'Minor grid', ... 
                 'majorgrid', 0, 'minorgrid', 1, 'collabels', br, 'rowlabels', br);
h2.cbar.Location= 'southoutside'; 


criteria= coefs <= cc_thresh & coefs >= -cc_thresh; % define zero criteria
coefs2= coefs; 
coefs2(criteria)= 0;  % set values meeting zero criteria = 0

% make a colormap
values = flipud( [0.77	 0.26	0.1;
                  0.98	 0.56	0.27;
                  0.99	 0.75	0.43;
                  1      1      1;
                  0.59	 0.81	0.8;
                  0.07   0.56	0.56;
                  0.08	 0.35	0.29] );

sz = size(values, 1);
c = interp1(1:sz, values, linspace(1, sz, 256), 'linear');

ax= subplot(1, 3, 3); 
h3= xcorrDotPlot(coefs2, 'lower', -1, 'dotscale', d_scale*4, 'title', 'Fully customized', ...
                'rowlabels', br, 'collabels', br, 'majorgrid', 0, 'minorgrid', 1, ...
                'overlayvals', 'sigonly', 'threshold', cc_thresh, 'precision', 2);
colormap(ax, c)
clim([-1 1]);
h3.cbar.Location= 'southoutside'; 

Changelog

All notable changes to this project are documented here. This project follows Keep a Changelog and Semantic Versioning.

---

v2.0.0 — 2026-05-06

Major refactor of argument handling and several bug fixes. Argument parsing migrated from fragile positional varargin to inputParser, providing type validation, clearer error messages, and a stable foundation for future parameters. One breaking change accompanies this: the significance threshold previously passed positionally after 'sigonly' must now be supplied as an explicit 'threshold' Name-Value pair.

Added

• inputParser-based argument handling throughout, replacing positional varargin parsing; all parameters now include type and range validators
• 'threshold' Name-Value parameter as an explicit, named companion to 'overlayvals', 'sigonly'; validated as numeric
• 'title' Name-Value parameter for setting a plot title with automatic visibility and positioning (default: '')
• 'toffset' Name-Value parameter for controlling the normalized vertical offset of the title above the axes, to clear rotated column labels (default: 1.2)
• h.title field in the output handle struct, exposing the title text object for post-hoc customization
• Non-negative range validation for 'dotscale'
• Boolean-aware validation for 'majorgrid' and 'minorgrid', accepting true/false or 1/0

Changed

• 'majorgrid' and 'minorgrid' defaults changed from 1/0 to true/false to reflect their boolean semantics
• Grid branch conditionals simplified from logical(mg) / logical(g) to direct boolean evaluation
• Triangle masking for 'lower' and 'upper' plot types now uses a structural ~tril(true(...), k) / ~triu(true(...), k) mask rather than the data matrix itself, correctly preserving genuine zero values in the triangle
• data(~matrix) = nan removed from the 'full' and non-square matrix paths for the same reason

Fixed

• scatter error (Value must be a vector of positive numeric type or nan) thrown when user-suppressed zero-sentinel values produced a size argument of 0; zero sizes are now converted to NaN prior to the scatter call so suppressed points are skipped cleanly
• Genuine zero correlations inside the plotted triangle were silently dropped when the data matrix was used as its own logical mask; structural masking resolves this

Breaking

• 'threshold' value must now be passed as an explicit named parameter rather than positionally after 'sigonly':

  % v1.x — no longer valid
  xcorrDotPlot(M, 'overlayvals', 'sigonly', 0.5)
  
  % v2.0.0 — required syntax
  xcorrDotPlot(M, 'overlayvals', 'sigonly', 'threshold', 0.5)

---

v1.0.0 — 2024-01-03

Initial release.

Added

• Core dot plot rendering for square and non-square matrices via scatter
• 'lower', 'upper', and 'full' triangle plot types with diagonal offset parameter k
• 'majorgrid' and 'minorgrid' toggles for enclosing and intersecting grid lines
• 'rowlabels' and 'collabels' for axis tick labeling
• 'dotscale' scalar for controlling dot size
• 'alpha' for dot opacity
• 'overlayvals' with 'all' and 'sigonly' modes for numeric text overlay
• 'precision' for controlling decimal places on overlaid text
• Output handle struct h with fields for axes, scatter points, grid lines, labels, and colorbar