RunMat
GitHub

View all functions

CategoryStats: Summary
GPUYes

What does the cov function do in MATLAB / RunMat?

cov returns covariance matrices for numeric data. Columns represent variables and rows are observations. You can pass in one matrix, two matching data sets, or supply observation weights and row-handling options that mirror MATLAB.

How does the cov function behave in MATLAB / RunMat?

  • cov(X) treats each column of X as a variable and returns a square covariance matrix.
  • cov(X, Y) concatenates X and Y column-wise (they must have the same number of rows) before computing the covariance.
  • The second argument can be the normalization flag 0 (default) or 1, matching MATLAB's unbiased and biased estimators.
  • You can pass a weight vector to obtain frequency-weighted covariance.
  • 'omitrows' drops rows containing NaN or Inf before the covariance is computed.
  • 'partialrows' performs pairwise deletion: each covariance entry uses only the rows that contain finite values for that column pair.

cov Function GPU Execution Behaviour

RunMat invokes provider-specific GPU kernels when:

  1. All inputs already reside on the GPU;
  2. No weight vector is supplied;
  3. The rows option is 'all'; and
  4. The active provider exposes the custom covariance hook.

If any of these conditions is not met, RunMat gathers the data to the host, evaluates the reference implementation, and returns a dense host tensor. This guarantees MATLAB-compatible behaviour regardless of GPU support.

Examples of using the cov function in MATLAB / RunMat

Computing covariance of columns in a matrix

X = [4.0 2.0 0.60;
     4.2 2.1 0.59;
     3.9 2.0 0.58;
     4.3 2.1 0.62;
     4.1 2.2 0.63];
C = cov(X);

Expected output:

C =
    0.0250    0.0075    0.0018
    0.0075    0.0070    0.0014
    0.0018    0.0014    0.0004

Covariance between two vectors

x = [1 2 3 4]';
y = [10 11 9 12]';
C = cov(x, y);

Expected output:

C =
    1.6667    1.5000
    1.5000    1.6667

Weighted covariance with observation weights

X = [4.0 2.0;
     4.2 2.1;
     3.9 2.0;
     4.3 2.1;
     4.1 2.2];
w = [1 1 1 2 2];
Cw = cov(X, w);

Expected output:

Cw =
    0.0224    0.0050
    0.0050    0.0067

Ignoring rows that contain missing values

X = [1   NaN 2;
     3   4   5;
     NaN 6   7;
     8   9   10];
C = cov(X, 'omitrows');

Expected output:

C =
   12.5000   12.5000   12.5000
   12.5000   12.5000   12.5000
   12.5000   12.5000   12.5000

Pairwise covariance with staggered NaNs

X = [ 1   2   NaN;
      4   NaN 6;
      7   8   9];
C = cov(X, 'partialrows');

Expected output:

C =
    9.0000   18.0000    4.5000
   18.0000   18.0000       NaN
    4.5000       NaN    4.5000

Running covariance on gpuArray inputs

G = gpuArray(X);        % reuse matrix from earlier examples
CG = cov(G);
CG_host = gather(CG);

Expected output:

CG_host =
    0.0250    0.0075    0.0018
    0.0075    0.0070    0.0014
    0.0018    0.0014    0.0004

GPU residency in RunMat (Do I need gpuArray?)

You usually do not need to call gpuArray. Expressions such as cov(sin(X)) keep temporary results on the GPU as long as the active provider handles the operation. The builtin gathers to the CPU only when weights, 'omitrows', or 'partialrows' are requested, or when the provider does not implement the covariance hook. Explicitly calling gpuArray remains supported for MATLAB compatibility and to seed GPU residency when you are unsure about planner decisions.

FAQ

Does cov support biased and unbiased estimators?

Yes. The default is the unbiased estimator (divide by N - 1). Passing 1 as the second argument switches to the biased estimator (divide by N), matching MATLAB.

How do I provide observation weights?

Supply a weight vector whose length equals the number of observations. The covariance is frequency-weighted using the MATLAB formula. Weighted covariance currently falls back to the CPU implementation when running on the GPU.

What happens when columns contain constant values?

The diagonal entries become zero, and off-diagonal entries involving the constant column are zero. Any slight negative values caused by floating-point noise are clamped to zero.

How are NaN and Inf handled?

By default ('all'), non-finite values propagate NaN into the affected covariance entries. 'omitrows' drops rows containing non-finite values, while 'partialrows' recomputes each covariance entry using only rows that are finite for the relevant column pair.

Can I call cov on logical inputs?

Yes. Logical arrays are converted to double precision (true → 1.0, false → 0.0) before the covariance is computed, matching MATLAB's behaviour.

See Also

corrcoef, mean, sum, gpuArray, gather

Source & Feedback