cov — Compute covariance of variables across observations.
C = cov(X) returns a covariance matrix with columns as variables and rows as observations. Paired inputs, normalization, row filtering, and observation weights are supported.
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
X- Type
Any- Required
- Yes
- Description
- Input observations (rows are observations, columns are variables).
Y_or_w- Type
Any- Required
- Yes
- Description
- Second dataset (Y) or weight vector (w), depending on shape/position.
normalization- Type
NumericScalar- Required
- Yes
- Default
0- Description
- Normalization flag: 0 (unbiased) or 1 (biased).
rows_option- Type
StringScalar- Required
- Yes
- Default
"all"- Description
- Rows handling mode: 'all', 'omitrows', or 'partialrows'.
Y- Type
Any- Required
- Yes
- Description
- Second dataset with matching size (or equal vector length).
opt- Type
Any- Required
- Yes
- Description
- Normalization flag or rows option.
w- Type
Any- Required
- Yes
- Description
- Weight vector with one weight per observation row.
Returns
C- Type
NumericArray- Description
- Covariance matrix.
Errors
RunMat:cov:InvalidArgument- When
- Arguments are malformed or unsupported for cov.
- Message
cov: invalid argument
RunMat:cov:ComplexUnsupported- When
- Any argument is complex-valued.
- Message
cov: complex inputs are not supported yet
RunMat:cov:RowsMismatch- When
- Two input datasets do not have the same size or equal vector lengths.
- Message
cov: paired inputs must have the same size
Inputs and estimators
With one matrix, each column is a variable. A vector produces a scalar variance. Two compatible arrays are vectorized into two variables and produce a 2-by-2 result; they are not concatenated as all of their original columns.
Normalization 0 (default) divides the unweighted covariance by N-1; 1 divides by N. A row- or column-vector of nonnegative observation weights is a RunMat extension and uses frequency-weighted covariance; ambiguity between a second vector variable and weights is resolved by the argument context.
all retains non-finite observations and propagates missing results. omitrows filters a whole row if any variable is non-finite. partialrows selects finite observations separately for each covariance entry.
Classes and execution
Real typed-integer observations, logical observations, typed-integer/logical normalization flags, and observation weight vectors are RunMat extensions. RunMat returns single covariance for single observations and double if any observation data are double, integer, or logical; controls and weights do not promote the output. The host calculation may accumulate in double precision. Complex observations are rejected by this implementation.
For Rows=all, a compatible resident input can use a provider covariance hook; supported weighted forms can remain resident when provider ownership and weight-domain conditions hold. An upstream resident expression can supply the input without an explicit gpuArray call; gpuArray is still available to request device residency. Row filtering or an unsupported hook uses the admitted host materialization path, then restores output placement according to resident-input intent. If a completed provider covariance needs a class conversion that is rejected as unsupported before conversion effects, RunMat converts that produced result on the host and applies the same placement policy without recomputing covariance. Provider ownership and live-allocation checks precede transfer. Provider choice is dynamic; the output class follows the observation data.
This is a fusion boundary with a portable runtime binding usable by the interpreter, JIT, native compilation, and browser execution. Device execution is provider-specific.
Examples
Covariance of matrix columns
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] (rounded to four decimals)Covariance between two vectors
x = [1 2 3 4]'; y = [10 11 9 12]'; C = cov(x,y)Expected output:
C = [5/3 2/3; 2/3 5/3]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] (rounded to four decimals)Discard incomplete rows
X = [1 NaN 2; 3 4 5; NaN 6 7; 8 9 10]; C = cov(X,'omitrows')Expected output:
C is a 3-by-3 matrix with every entry equal to 12.5; only the second and fourth observations remain.Pairwise deletion
X = [1 2 NaN; 4 NaN 6; 7 8 9]; C = cov(X,'partialrows')Expected output:
C = [9 18 4.5; 18 18 NaN; 4.5 NaN 4.5]Covariance of resident observations
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); C = gather(CG)Expected output:
C = [0.0250 0.0075 0.0018; 0.0075 0.0070 0.0014; 0.0018 0.0014 0.0004] (rounded to four decimals)Preserve single observation precision
X = single([1 2; 2 3; 3 5]); C = cov(X)Expected output:
C is single precision.Using 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
Which normalization is used?⌄
The default flag is zero (sample normalization); flag one selects population normalization.
How do I provide observation weights?⌄
Pass a vector with one nonnegative finite weight per observation. This is a RunMat extension and can use a supported provider hook.
What happens to constant columns?⌄
Their variance and covariance with other variables are zero, subject to floating-point arithmetic. Tiny negative diagonal variance caused by roundoff is clamped to zero; off-diagonal covariance is not clamped.
How do non-finite values behave?⌄
Default all propagates them; omitrows removes entire affected observations; partialrows filters for each variable pair.
Can logical observations be used?⌄
Yes in RunMat mode. Logical observations are converted at the covariance calculation boundary and host results are double.
Related Stats functions
Summary
anova1 · binocdf · binscatter · boxplot · cdf · cdfplot · chi2cdf · corr · corrcoef · corrcov · cov2corr · dummyvar · ecdf · filloutliers · fitdist · geomean · grpstats · harmmean · icdf · isoutlier · ksdensity · kstest · kurtosis · lsline · mad · mode · nanmax · normalize · normcdf · norminv · normpdf · onehotdecode · onehotencode · pca · pdf · prctile · qqplot · quantile · refline · rmse · scatterhist · skewness · tabulate · tcdf · tiedrank · tinv · tpdf · ttest · ttest2 · wblinv
Ml
bayesopt · classify · confusionmat · crossvalind · cvpartition · fitclinear · fitctree · fitlm · kmeans · knnsearch · lasso · lassoglm · linkage · lscov · mnrfit · nlparci · optimizableVariable · pdist · pdist2 · perfcurve · predict · regress · ridge · squareform · test · training · tsne
Random
binornd · bootstrp · datasample · dividerand · exprnd · gamrnd · gpurng · lhsdesign · mvnrnd · normrnd · random · randsample · rng · trnd · unidrnd · unifrnd · wblrnd
Hist
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.