RunMat
GitHub

View all functions

CategoryStats: Summary
GPUYes

corrcoef — Compute Pearson correlation coefficients for the columns of matrices or paired data sets.

corrcoef returns the Pearson correlation coefficients between pairs of variables. Given a matrix, every column is treated as a separate variable and every row is an observation. You can also pass two matching data sets and RunMat will concatenate them column-wise, mirroring MATLAB.

How does the corrcoef function behave in MATLAB / RunMat?

  • corrcoef(X) returns a square matrix whose (i, j) entry is the correlation between column i and column j of X.
  • corrcoef(X, Y) concatenates the columns of X and Y (they must share the same number of rows) before computing correlations.
  • An optional normalisation flag allows you to divide by N - 1 (default, unbiased) or N (flag = 1, biased) just like MATLAB.
  • Use 'rows' with 'all', 'complete', or 'pairwise' to control how rows containing NaN or Inf are handled.
  • Columns with zero variance produce NaN on both the diagonal and in every correlation that references them, matching MATLAB semantics.

GPU behavior

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 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 of using corrcoef in MATLAB / RunMat

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

Correlating 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.0000

Ignoring 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   NaN

Pairwise 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     1

Using 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.0000

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

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.

See also

mean, sum, histcounts, gpuArray, gather

Source & Feedback