r.covar(1grass)

💖 r.covar — the GRASS User's Manual page, bestie edition 💖

okay so real talk: this is r.covar from the 1grass manual, and it's the GRASS tool that spits out a covariance/correlation matrix for whatever raster maps you throw at it. no cap, that's the whole job and it does it flawlessly. ✨

---

✨ NAME ✨

r.covar — outputs a covariance/correlation matrix for user-specified raster map layer(s). literally that's it, that's the icon.

🌸 KEYWORDS 🌸

raster, statistics

🦋 SYNOPSIS 🦋

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

💅 Flags

• -r — print the correlation matrix (not the covariance one, bestie, they are not the same thing)
• --help — print usage summary
• --verbose — verbose module output
• --quiet — quiet module output
• --ui — force launching GUI dialog

🎀 Parameters

• map=name[,name,...] [required] — name of the raster map(s). yes it's required, you cannot skip it, it's giving mandatory main character.

👑 DESCRIPTION 👑

r.covar outputs a covariance/correlation matrix for user-specified raster map layer(s). you can print that output, or you can save it by redirecting the output into a file. your call, both are valid. 🫶

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. so like, 3 maps in → 3x3 matrix out. girl math but make it statistics. ✨

🧚 NOTES 🧚

this module can be used as the first step of a principle components transformation. the covariance matrix would be input into a system which determines eigen values and eigen vectors. an NxN covariance matrix would result in N real eigen values and N eigen vectors (each composed of N real numbers). slay, linear algebra ate that.

the module m.eigensystem in GRASS Addons can be installed and used to generate the eigenvalues and vectors. iykyk. 💜

🔥 EXAMPLE 🔥

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):

     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. 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. 💖

bestie the ranges are NOT gonna match up on their own, so rescale before you get confused, ok? 🙈

🌈 SEE ALSO 🌈

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

⭐ AUTHOR ⭐

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

💀 SOURCE CODE 💀

available at: r.covar source code (history)

latest change: Friday Aug 08 09:39:19 2025 in commit: ed72c71d8580e872cd6fd345c84a15c324764465

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

---

and that's the whole page, periodt. 💅 this was GRASS 8.5.0, straight out of the GRASS 8.5.0 Reference Manual, © 2003-2026 GRASS Development Team — go forth and covary responsibly, queen. 🎀🦋✨