cov — Compute covariance matrices in MATLAB and RunMat.
cov returns covariance matrices for numeric data with columns as variables and rows as observations. Single-matrix, paired-input, weighting, and row-handling forms follow MATLAB semantics.
Syntax
C = cov(X)
C = cov(X, Y_or_w)
C = cov(X, normalization)
C = cov(X, rows_option)
C = cov(X, Y, opt)
C = cov(X, Y, w)
C = cov(X, Y, w, opt)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Input observations (rows are observations, columns are variables). |
Y_or_w | Any | Yes | — | Second dataset (Y) or weight vector (w), depending on shape/position. |
normalization | NumericScalar | Yes | 0 | Normalization flag: 0 (unbiased) or 1 (biased). |
rows_option | StringScalar | Yes | "all" | Rows handling mode: 'all', 'omitrows', or 'partialrows'. |
Y | Any | Yes | — | Second dataset with matching row count. |
opt | Any | Yes | — | Normalization flag or rows option. |
w | Any | Yes | — | Weight vector with one weight per observation row. |
Returns
| Name | Type | Description |
|---|---|---|
C | NumericArray | Covariance matrix. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:cov:InvalidArgument | Arguments are malformed or unsupported for cov. | cov: invalid argument |
RunMat:cov:ComplexUnsupported | Any argument is complex-valued. | cov: complex inputs are not supported yet |
RunMat:cov:RowsMismatch | Two input datasets do not have the same number of rows. | cov: inputs must have the same number of rows |
RunMat:cov:NormalizationInvalid | Normalization flag is non-finite, non-integer, or not 0/1. | cov: normalization flag is invalid |
RunMat:cov:WeightVectorLengthMismatch | Weight vector length does not match observation row count. | cov: weight vector length mismatch |
RunMat:cov:RowsOptionUnknown | Rows option is not one of all/omitrows/partialrows. | cov: unknown rows option |
RunMat:cov:NormalizationDuplicate | Normalization flag is provided more than once. | cov: normalization flag specified more than once |
RunMat:cov:TooManyArrayArguments | More than two data arrays (or Y plus weight) are provided. | cov: too many array arguments |
RunMat:cov:Internal | Internal tensor conversion/allocation or covariance computation fails. | cov: internal operation failed |
How cov works
cov(X)treats each column ofXas a variable and returns a square covariance matrix.cov(X, Y)concatenatesXandYcolumn-wise (they must have the same number of rows) before computing the covariance.- The second argument can be the normalization flag
0(default) or1, matching MATLAB's unbiased and biased estimators. - You can pass a weight vector to obtain frequency-weighted covariance.
'omitrows'drops rows containingNaNorInfbefore the covariance is computed.'partialrows'performs pairwise deletion: each covariance entry uses only the rows that contain finite values for that column pair.
Does RunMat run cov 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.0004Covariance 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.6667Weighted 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.0067Ignoring 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.5000Pairwise 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.5000Running 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.0004Using cov with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how cov changes the result.
Run a small cov example, explain the result, then change one input and compare the output.
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 Stats functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how cov is executed, line by line, in Rust.
- View the source for cov 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.