r.covar(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

✨ r.covar ✨ — the covariance/correlation matrix bestie 💖

okay so this is r.covar, straight out of the GRASS GIS User's Manual (it lives in section 1, r.covar(1), iykyk). It spits out a covariance/correlation matrix for whatever raster map layers you throw at it, and honestly? it's giving math queen. 👑

🌸 NAME 🌸

r.covar — outputs a covariance/correlation matrix for user-specified raster map layer(s). fr fr that's the whole gig. 💅

🏷️ KEYWORDS 🏷️

raster, statistics

like yes, we're doing raster stats today bestie, get into it ✨

🦋 SYNOPSIS 🦋

r.covar
r.covar --help
r.covar [-r] map=name[,name,...]  [--help]  [--verbose]  [--quiet]
[--ui]

🎀 Flags 🎀

  • -r — print the correlation matrix (not me giving you the option to switch it up 💅)
  • --help — prints the usage summary, the classic "help me bestie" move
  • --verbose — verbose module output, she's chatty ✨
  • --quiet — quiet module output, she's mysterious 🤫
  • --ui — force launching the GUI dialog, for when you want the pretty buttons 🖱️

🌈 Parameters 🌈

  • map=name[,name,...] — required 💀 — name of the raster map(s). Yes you need this one, no you cannot skip it.

💜 DESCRIPTION 💜

So r.covar outputs a covariance/correlation matrix for the raster map layer(s) you specify. You can just let it print to your terminal, or you can save it by redirecting the output into a file — your call, main character. 🫶

The output is an N x N symmetric covariance (correlation) matrix, where N is the number of raster map layers you specified on the command line. Symmetric means it mirrors itself across the diagonal, and that's just gorgeous of it. ✨

🔥 NOTES 🔥

This module is literally the first step of a principle components transformation — she's the opening act, the vibe-setter. The covariance matrix would get fed into a system that determines eigen values and eigen vectors. And an NxN covariance matrix would result in N real eigen values and N eigen vectors (each composed of N real numbers). Math! Iconic! 👑

The module m.eigensystem in GRASS GIS Addons can be installed and used to generate the eigenvalues and vectors. slay. 🎀

🌟 EXAMPLE 🌟

okay for example:

g.region raster=layer.1 -p
r.covar -r map=layer.1,layer.2,layer.3

would produce a 3x3 matrix (values are example only, don't come for me):

     1.000000  0.914922  0.889581
     0.914922  1.000000  0.939452
     0.889581  0.939452  1.000000

In the above example, the eigen values and corresponding eigen vectors for the covariance matrix are:

component   eigen value               eigen vector
    1       1159.745202   <0.691002  0.720528  0.480511>
    2          5.970541   <0.711939 -0.635820 -0.070394>
    3        146.503197   <0.226584  0.347470 -0.846873>

The component corresponding to each vector can be produced using r.mapcalc as follows:

r.mapcalc "pc.1 = 0.691002*layer.1 + 0.720528*layer.2 + 0.480511*layer.3"
r.mapcalc "pc.2 = 0.711939*layer.1 - 0.635820*layer.2 - 0.070394*layer.3"
r.mapcalc "pc.3 = 0.226584*layer.1 + 0.347470*layer.2 - 0.846873*layer.3"

Note that based on the relative sizes of the eigen values, pc.1 will contain about 88% of the variance in the data set, pc.2 will contain about 1% of the variance in the data set, and pc.3 will contain about 11% of the variance in the data set. 🤯

Also, note that the range of values produced in pc.1, pc.2, and pc.3 will not (in general) be the same as those for layer.1, layer.2, and layer.3. So it may be necessary to rescale pc.1, pc.2 and pc.3 to the desired range (e.g. 0-255). This can be done with r.rescale. 💅

ngl this part trips people up — the ranges just aren't gonna match, that's not a bug, that's the math talking.

👀 SEE ALSO 👀

i.pca, m.eigensystem (Addon), r.mapcalc, r.rescale

go read those next bestie, they're all connected, it's a whole ecosystem 🦋

👑 AUTHOR 👑

Michael Shapiro, U.S. Army Construction Engineering Research Laboratory

🧚 SOURCE CODE 🧚

Available at: r.covar source code (history)

Accessed: Saturday Jan 17 05:40:44 2026

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual — and that's the whole page, GRASS 8.4.2, r.covar(1), periodt. 💖 ✨ 🎀 🦋 🌸 💅 🫶

📦 where this page comes from