.TH r.kappa 1grass "" "GRASS 8.3.2" "GRASS GIS User's Manual"
.SH NAME
\fI\fBr.kappa\fR\fR  \- Calculates error matrix and kappa parameter for accuracy assessment of classification result.
.SH KEYWORDS
raster, statistics, classification
.SH SYNOPSIS
\fBr.kappa\fR
.br
\fBr.kappa \-\-help\fR
.br
\fBr.kappa\fR [\-\fBwhm\fR] \fBclassification\fR=\fIname\fR \fBreference\fR=\fIname\fR  [\fBoutput\fR=\fIname\fR]   [\fBtitle\fR=\fIstring\fR]  \fBformat\fR=\fIstring\fR  [\-\-\fBoverwrite\fR]  [\-\-\fBhelp\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR]  [\-\-\fBui\fR]
.SS Flags:
.IP "\fB\-w\fR" 4m
.br
Wide report
.br
132 columns (default: 80)
.IP "\fB\-h\fR" 4m
.br
No header in the report
.IP "\fB\-m\fR" 4m
.br
Print Matrix only
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-help\fR" 4m
.br
Print usage summary
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.IP "\fB\-\-ui\fR" 4m
.br
Force launching GUI dialog
.SS Parameters:
.IP "\fBclassification\fR=\fIname\fR \fB[required]\fR" 4m
.br
Name of raster map containing classification result
.IP "\fBreference\fR=\fIname\fR \fB[required]\fR" 4m
.br
Name of raster map containing reference classes
.IP "\fBoutput\fR=\fIname\fR" 4m
.br
Name for output file containing error matrix and kappa
.br
If not given write to standard output
.IP "\fBtitle\fR=\fIstring\fR" 4m
.br
Title for error matrix and kappa
.br
Default: \fIACCURACY ASSESSMENT\fR
.IP "\fBformat\fR=\fIstring\fR \fB[required]\fR" 4m
.br
Output format
.br
Options: \fIplain, json\fR
.br
Default: \fIplain\fR
.br
\fBplain\fR: Plain text output
.br
\fBjson\fR: JSON (JavaScript Object Notation)
.SH DESCRIPTION
\fIr.kappa\fR tabulates the error matrix of classification result by
crossing classified map layer with respect to reference map layer.  Both
overall \fIkappa\fR (accompanied by its \fIvariance\fR) and
conditional \fIkappa\fR values are calculated.  This analysis program
respects the current geographic region and mask settings.
.PP
\fIr.kappa\fR calculates the error matrix of the
two map layers and prepares the table from which the report
is to be created.  \fIkappa\fR values for overall and
each classes are computed along with their variances. Also
percent of commission and omission error, total correct
classified result by pixel counts, total area in pixel
counts and percentage of overall correctly classified
pixels are tabulated.
.PP
The report will be written to an output file which is in
plain text format and named by user at prompt of running
the program. To obtain machine readable version, specify a
\fIjson\fR output format.
.PP
The body of the report is arranged in panels.  The
classified result map layer categories is arranged along
the vertical axis of the table, while the reference map
layer categories along the horizontal axis.  Each panel has
a maximum of 5 categories (9 if wide format) across the
top.  In addition, 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.  There is a total at the bottom of each column
representing the sum of all the rows in that column.
.SH OUTPUT VARIABLES
.PP
All output variables (except kappa variance) have been
validated to produce correct values in accordance
to formulas given by Rossiter, D.G., 2004. \(dqTechnical Note:
Statistical methods for accuracy assessment of classified
thematic maps\(dq.
.IP "Observations" 4m
.br
Overall count of observed cells (sum of both correct
and incorrect ones).
.IP "Correct" 4m
.br
Overall count of correct cells (cells with equal value
in reference and classification maps).
.IP "Overall accuracy" 4m
.br
Number of correct cells divided by overall cell count
(expressed in percent).
.IP "User\(cqs accuracy" 4m
.br
Share of correctly classified cells out of all cells
classified as belonging to specified class (expressed in percent).
Inverse of commission error.
.IP "Commission" 4m
.br
Commission error = 100 \- user\(cqs accuracy.
.IP "Producer\(cqs accuracy" 4m
.br
Share of correctly classified cells out of all cells
known to belong to specified class (expressed in percent).
Inverse of omission error.
.IP "Omission" 4m
.br
Omission error = 100 \- producer\(cqs accuracy.
.IP "Kappa" 4m
.br
Choen\(cqs kappa index value.
.IP "Kappa variance" 4m
.br
Variance of kappa index. Correctness needs to be validated.
.IP "Conditional kappa" 4m
.br
Conditional user\(cqs kappa for specified class.
.IP "MCC" 4m
.br
Matthews (Mattheus) Correlation Coefficient is implemented
according to Grandini, M., Bagli, E., Visani, G. 2020.
\(dqMetrics for multi\-class classification: An overview.\(dq
.SH NOTES
.PP
It is recommended to reclassify categories of classified
result map layer into a more manageable number before
running \fIr.kappa\fR on the classified raster map
layer. Because \fIr.kappa\fR calculates and then reports
information for each and every category.
.PP
\fINA\fR\(cqs in output mean it was not possible to calculate the value
(e.g. calculation would involve division by zero).
In JSON output \fINA\fR\(cqs are represented with value \fInull\fR.
If there is no overlap between both maps, a warning is printed and
output values are set to 0 or \fInull\fR respectively.
.PP
The \fBEstimated kappa value\fR in \fIr.kappa\fR 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.
.PP
It is calculated as:
.PP
kpp[i] = (pii[i] \- pi[i] * pj[i]) / (pi[i] \- pi[i] * pj[i]);
.PP
where=
.RS 4n
.IP \(bu 4n
pii[i] is the probability of agreement (i.e. number of pixels for which there is agreement divided by total number of assessed pixels)
.IP \(bu 4n
Pi[i] is the probability of classification i having classified the point as i
.IP \(bu 4n
Pj[i] is the probability of classification j having classified the point as i.
.RE
.PP
Some of reported values (overall accuracy, Choen\(cqs kappa, MCC) can be
misleading if cell count among classes is not balanced. See e.g.
Powers, D.M.W., 2012. \(dqThe Problem with Kappa\(dq; Zhu, Q., 2020.
\(dqOn the performance of Matthews correlation coefficient (MCC) for
imbalanced dataset\(dq.
.SH EXAMPLE
Example for North Carolina sample dataset:
.br
.nf
\fC
g.region raster=landclass96 \-p
r.kappa \-w classification=landuse96_28m reference=landclass96
# export Kappa matrix as CSV file \(dqkappa.csv\(dq
r.kappa classification=landuse96_28m reference=landclass96 output=kappa.csv \-m \-h
\fR
.fi
.PP
Verification of classified LANDSAT scene against training areas:
.br
.nf
\fC
r.kappa \-w classification=lsat7_2002_classes reference=training
\fR
.fi
.SH SEE ALSO
\fI
g.region,
r.category,
r.mask,
r.reclass,
r.report,
r.stats
\fR
.SH AUTHORS
Tao Wen, University of Illinois at Urbana\-Champaign, Illinois
.br
Maris Nartiss, University of Latvia (JSON output, MCC)
.SH SOURCE CODE
.PP
Available at:
r.kappa source code
(history)
.PP
Accessed: Thursday Mar 07 18:15:11 2024
.PP
Main index |
Raster index |
Topics index |
Keywords index |
Graphical index |
Full index
.PP
© 2003\-2024
GRASS Development Team,
GRASS GIS 8.3.2 Reference Manual