r.kappa(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💖 r.kappa(1) — the GRASS GIS User's Manual, but make it make sense 💖

okay bestie, welcome to r.kappa, a classic from the GRASS GIS User's Manual (this one's page r.kappa(1)). it does stats on your classified raster and tells you how right you actually are. no cap. let's get into it 🌸

✨ NAME ✨

r.kappa — Calculates error matrix and kappa parameter for accuracy assessment of classification result.

like. it grades your homework. but for rasters. 💅

🏷️ KEYWORDS 🏷️

raster, statistics, classification

🎀 SYNOPSIS 🎀

r.kappa
r.kappa --help
r.kappa [-whm] classification=name reference=name  [output=name]
[title=string]  format=name  [--overwrite]  [--help]  [--verbose]
[--quiet]  [--ui]

🚩 Flags 🚩

  • -w — Wide report. it's 132 columns (default: 80). more room, more slay.
  • -h — No header in the report. skip the intro, get straight to the numbers.
  • -m — Print Matrix only. just the matrix, nothing else, main character energy.
  • --overwrite — Allow output files to overwrite existing files. (respectfully, it WILL replace them 👀)
  • --help — Print usage summary.
  • --verbose — Verbose module output.
  • --quiet — Quiet module output.
  • --ui — Force launching GUI dialog.

🧚 Parameters 🧚

  • classification=name [required] — Name of raster map containing classification result.
  • reference=name [required] — Name of raster map containing reference classes.
  • output=name — Name for output file containing error matrix and kappa. If not given, it writes to standard output.
  • title=string — Title for error matrix and kappa. Default: ACCURACY ASSESSMENT.
  • format=name [required] — Output format.
    • Options: plain, json
    • Default: plain
    • plain: Plain text output
    • json: JSON (JavaScript Object Notation)

💫 DESCRIPTION 💫

so r.kappa tabulates the error matrix of your classification result by crossing the classified map layer against the reference map layer. both the overall kappa (and yes, its variance comes with it, it's a package deal) and the conditional kappa values get calculated. this analysis program respects the current geographic region and mask settings, fr fr. 🌈

r.kappa calculates the error matrix of the two map layers and prepares the table from which the report is going to be created. kappa values for overall and each class are computed along with their variances. also tabulated: percent of commission and omission error, total correct classified result by pixel counts, total area in pixel counts, and the percentage of overall correctly classified pixels. that's a lot of receipts. 💅

the report gets written to an output file which is in plain text format, named by the user at the prompt of running the program. want a machine readable version instead? specify a json output format. periodt.

the body of the report is arranged in panels. the classified result map layer categories go along the vertical axis of the table, while the reference map layer categories go along the horizontal axis. each panel has a maximum of 5 categories (9 if wide format) across the top. also, the last column of the last panel reflects a cross total of each column for each row. all of the categories of the map layer arranged along the vertical axis — i.e., the reference map layer — are included in each panel. and there's a total at the bottom of each column representing the sum of all the rows in that column. 🫶

📊 OUTPUT VARIABLES 📊

all output variables (except kappa variance) have been validated to produce correct values in accordance to formulas given by Rossiter, D.G., 2004. "Technical Note: Statistical methods for accuracy assessment of classified thematic maps". so like, everything's verified except that one guy. 🙈

  • Observations — Overall count of observed cells (sum of both correct and incorrect ones).
  • Correct — Overall count of correct cells (cells with equal value in reference and classification maps).
  • Overall accuracy — Number of correct cells divided by overall cell count (expressed in percent).
  • User's accuracy — Share of correctly classified cells out of all cells classified as belonging to specified class (expressed in percent). Inverse of commission error.
  • Commission — Commission error = 100 - user's accuracy.
  • Producer's accuracy — Share of correctly classified cells out of all cells known to belong to specified class (expressed in percent). Inverse of omission error.
  • Omission — Omission error = 100 - producer's accuracy.
  • Kappa — Choen's kappa index value.
  • Kappa variance — Variance of kappa index. Correctness needs to be validated. (the one unverified one, told you 💀)
  • Conditional kappa — Conditional user's kappa for specified class.
  • MCC — Matthews (Mattheus) Correlation Coefficient is implemented according to Grandini, M., Bagli, E., Visani, G. 2020. "Metrics for multi-class classification: An overview."

🦋 NOTES 🦋

it is recommended to reclassify categories of the classified result map layer into a more manageable number before running r.kappa on the classified raster map layer. because r.kappa calculates and then reports information for each and every category. all of them. every single one. 😭

NA's in output mean it was not possible to calculate the value (e.g. calculation would involve division by zero). in JSON output, NA's are represented with value null. if there is no overlap between both maps, a warning is printed and output values are set to 0 or null respectively.

the Estimated kappa value in r.kappa is the value only for one class, i.e. the observed agreement between the classifications for those observations that have been classified by classifier 1 into the class i. in other words, here the choice of reference is important. 👑

it is calculated as:

kpp[i] = (pii[i] - pi[i] * pj[i]) / (pi[i] - pi[i] * pj[i]);

where=

  • pii[i] is the probability of agreement (i.e. number of pixels for which there is agreement divided by total number of assessed pixels)
  • Pi[i] is the probability of classification i having classified the point as i
  • Pj[i] is the probability of classification j having classified the point as i.

some of the reported values (overall accuracy, Choen's kappa, MCC) can be misleading if cell count among classes is not balanced. see e.g. Powers, D.M.W., 2012. "The Problem with Kappa"; Zhu, Q., 2020. "On the performance of Matthews correlation coefficient (MCC) for imbalanced dataset".

⚠️ bestie listen — unbalanced classes will absolutely lie to your face through these metrics. read those two papers before you trust a pretty number. 💀

🌟 EXAMPLE 🌟

Example for North Carolina sample dataset:

g.region raster=landclass96 -p
r.kappa -w classification=landuse96_28m reference=landclass96
# export Kappa matrix as CSV file "kappa.csv"
r.kappa classification=landuse96_28m reference=landclass96 output=kappa.csv -m -h

Verification of classified LANDSAT scene against training areas:

r.kappa -w classification=lsat7_2002_classes reference=training

👀 SEE ALSO 👀

g.region, r.category, r.mask, r.reclass, r.report, r.stats

👑 AUTHORS 👑

Tao Wen, University of Illinois at Urbana-Champaign, Illinois Maris Nartiss, University of Latvia (JSON output, MCC)

🔥 SOURCE CODE 🔥

Available at: r.kappa source code (history)

Accessed: Saturday Jan 17 05:40:49 2026

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

okay that's the whole page, you ate it, you're welcome 🎀✨ and for the cute sign-off: this was GRASS GIS 8.4.2 (that's the GRASS 8.4.2 footer energy, and the page itself is r.kappa(1)), last touched Saturday Jan 17 05:40:49 2026, with © 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual. love that for us. byeeee 💖🦋💅

📦 where this page comes from