corrcoef — Compute Pearson correlation coefficients in MATLAB and RunMat.
corrcoef returns Pearson correlation coefficients between variable pairs. For matrix input, columns are variables and rows are observations; paired inputs are combined column-wise under MATLAB semantics.
Syntax
R = corrcoef(A)
R = corrcoef(A, B)
[R, P] = corrcoef(A)
[R, P] = corrcoef(A, B)
[R, P, RL, RU] = corrcoef(A)
[R, P, RL, RU] = corrcoef(A, B)
___ = corrcoef(A, Name, Value)
___ = corrcoef(A, B, Name, Value)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input observations (rows are observations, columns are variables). |
B | Any | Yes | — | Second array with the same size as A; both arrays are vectorized. |
nameValuePairs | Any | Variadic | — | Alpha and Rows name-value arguments. |
Returns
| Name | Type | Description |
|---|---|---|
R | NumericArray | Correlation coefficient matrix. |
P | NumericArray | P-values for testing zero correlation. |
RL | NumericArray | Lower confidence bounds for the correlation coefficients. |
RU | NumericArray | Upper confidence bounds for the correlation coefficients. |
Returned values from corrcoef depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:corrcoef:InvalidArgument | Arguments are malformed or unsupported for corrcoef. | corrcoef: invalid argument |
RunMat:corrcoef:ComplexOutputs | P-values or confidence bounds are requested for complex correlation coefficients. | corrcoef: P-values and confidence bounds are invalid for complex coefficients |
RunMat:corrcoef:SizeMismatch | A and B do not have the same size. | corrcoef: A and B must have the same size |
RunMat:corrcoef:AlphaInvalid | Alpha is not a finite single/double scalar strictly between zero and one. | corrcoef: Alpha must be a floating scalar in the open interval (0,1) |
RunMat:corrcoef:RowsOptionUnknown | Rows option value is not supported. | corrcoef: unknown rows option |
RunMat:corrcoef:OptionDuplicate | Alpha or Rows is specified more than once. | corrcoef: option specified more than once |
RunMat:corrcoef:RowsOptionMalformed | Rows keyword is not followed by a valid string option. | corrcoef: rows option is malformed |
RunMat:corrcoef:OptionUnknown | An unknown option keyword is provided. | corrcoef: unknown option |
RunMat:corrcoef:TooManyInputArrays | More than two data arrays are provided. | corrcoef: too many input arrays |
RunMat:corrcoef:Internal | Internal tensor conversion/allocation or corrcoef computation fails. | corrcoef: internal operation failed |
How corrcoef works
corrcoef(X)returns a square matrix whose(i, j)entry is the correlation between columniand columnjofX.corrcoef(X, Y)concatenates the columns ofXandY(they must share the same number of rows) before computing correlations.- An optional normalisation flag allows you to divide by
N - 1(default, unbiased) orN(flag = 1, biased) just like MATLAB. - Use
'rows'with'all','complete', or'pairwise'to control how rows containingNaNorInfare handled. - Columns with zero variance produce
NaNon both the diagonal and in every correlation that references them, matching MATLAB semantics.
Does RunMat run corrcoef on the GPU?
When the input data resides on the GPU, RunMat asks the active acceleration provider to execute the correlation directly on the device whenever:
1. All inputs are gpuArray values; 2. The 'rows' option is 'all'; and 3. The provider exposes the custom corrcoef hook (the WGPU provider does).
If any of these conditions is not met, the builtin gathers the data to host memory, computes the correlation matrix on the CPU reference path, and returns a dense host tensor.
GPU memory and residency
You usually do not need to call gpuArray explicitly. When you write expressions such as corrcoef(sin(X)), the fusion planner keeps the intermediate residency on the GPU as long as the active provider exposes the required hooks (for corrcoef, that means the custom provider kernel and rows='all'). RunMat still honours MATLAB semantics, so explicitly calling gpuArray remains useful for compatibility and for forcing GPU residency when you are unsure whether the planner will do so.
Examples
Calculating correlation between matrix columns
A = [1 2 4; 2 4 1; 3 6 -1; 4 8 0];
R = corrcoef(A)Expected output:
R =
1.0000 1.0000 -0.8367
1.0000 1.0000 -0.8367
-0.8367 -0.8367 1.0000Correlating two separate data sets
height = [1.72 1.84 1.65 1.91]';
weight = [68.5 83.0 59.1 92.2]';
R = corrcoef(height, weight)Expected output:
R =
1.0000 0.9998
0.9998 1.0000Ignoring rows that contain missing values
X = [1 NaN 2;
3 4 5;
6 7 NaN];
R = corrcoef(X, 'rows', 'complete')Expected output:
R =
NaN NaN NaN
NaN NaN NaN
NaN NaN NaNPairwise correlation with staggered NaNs
X = [ 1 2 3;
NaN 5 1;
4 NaN 6;
5 8 NaN];
R = corrcoef(X, 'rows', 'pairwise')Expected output:
R =
1 1 1
1 1 -1
1 -1 1Using biased normalisation (flag = 1)
A = [1 2; 3 4; 5 6];
R = corrcoef(A, 1)Expected output:
R =
1.0000 1.0000
1.0000 1.0000Running corrcoef on gpuArray inputs
G = gpuArray([1 2 4; 2 4 1; 3 6 -1; 4 8 0]);
R = corrcoef(G);
R_host = gather(R)Using corrcoef with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how corrcoef changes the result.
Run a small corrcoef example, explain the result, then change one input and compare the output.
FAQ
Does corrcoef support two outputs like MATLAB?⌄
RunMat currently returns the correlation matrix (R) and omits the optional p-value output. The statistical distribution helpers needed for the p-values are on the roadmap.
How does the normalisation flag affect the result?⌄
flag = 0 (default) divides by N - 1 for an unbiased estimate. flag = 1 divides by N, producing biased estimates that match MATLAB. The choice does not change perfect correlations because both variance and covariance scale by the same factor.
What happens when a column is constant?⌄
Columns with zero variance produce NaN on the diagonal and in any correlation that references that column. MATLAB behaves the same way because the standard deviation is zero.
Which rows are removed by 'rows','complete'?⌄
All rows that contain any NaN or Inf values are discarded before computing the correlation matrix. 'rows','pairwise' performs this filtering separately for each column pair.
Can I call corrcoef on logical arrays?⌄
Yes. Logical inputs are promoted to double precision (true -> 1.0, false -> 0.0) before the correlation matrix is computed.
What does corrcoef do in MATLAB?⌄
corrcoef(X) returns the matrix of correlation coefficients for the columns of X. Each entry R(i,j) is the Pearson linear correlation between columns i and j, ranging from -1 to 1.
How is corrcoef different from cov in MATLAB?⌄
corrcoef returns normalized correlation coefficients (always between -1 and 1), while cov returns the covariance matrix (in the original units squared). corrcoef(X) equals cov(X) ./ (std(X)' * std(X)).
Can I compute the correlation between two vectors with corrcoef?⌄
Yes. corrcoef(x, y) treats x and y as two columns and returns a 2×2 correlation matrix. The off-diagonal element is the correlation coefficient between x and y.
Does corrcoef handle missing data?⌄
Use corrcoef(X, 'rows', 'complete') to exclude any row that contains a NaN in any column, or 'pairwise' to exclude NaN rows separately for each pair of columns.
Related Stats functions
Summary
binocdf · boxplot · cdf · cdfplot · chi2cdf · corr · corrcov · cov · cov2corr · dummyvar · ecdf · filloutliers · fitdist · geomean · grpstats · harmmean · icdf · isoutlier · kstest · kurtosis · lsline · mad · mode · nanmax · normalize · normcdf · norminv · normpdf · onehotdecode · onehotencode · pdf · prctile · quantile · refline · rmse · skewness · tabulate · tcdf · tiedrank · tinv · tpdf · ttest2 · wblinv
Ml
bayesopt · classify · confusionmat · crossvalind · cvpartition · fitclinear · fitctree · fitlm · kmeans · knnsearch · lasso · lassoglm · linkage · lscov · mnrfit · optimizableVariable · pdist · pdist2 · perfcurve · predict · regress · ridge · squareform · test · training · tsne
Random
binornd · bootstrp · datasample · dividerand · exprnd · gamrnd · lhsdesign · mvnrnd · normrnd · random · randsample · rng · trnd · unidrnd · unifrnd · wblrnd
Hist
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how corrcoef is executed, line by line, in Rust.
- View the source for corrcoef in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.