cov — Compute covariance matrices for vectors, matrices, or paired data sets.

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 cov works in 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.

How cov runs on the GPU

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.

GPU memory and residency

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.

Examples

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    0.6667
    0.6667    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

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];
G = gpuArray(X);
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

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.

Related functions to explore

These functions work well alongside cov. Each page has runnable examples you can try in the browser.

corrcoef, mean, sum, gpuArray, gather

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how cov works, line by line, in Rust.

• View cov.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing