ComputeConfusionMatrix - Confusion matrix Computation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Computes the confusion matrix of a classification

Detailed description
--------------------

This application computes the confusion matrix of a classification map relatively to a ground truth. This ground truth can be given as a raster or a vector data. Only reference and produced pixels with values different from NoData are handled in the calculation of the confusion matrix. The confusion matrix is organized the following way: rows = reference labels, columns = produced labels. In the header of the output file, the reference and produced class labels are ordered according to the rows/columns of the confusion matrix.

Parameters
----------

This section describes in details the parameters available for this application. Table [#]_ presents a summary of these parameters and the parameters keys to be used in command-line and programming languages. Application key is *ComputeConfusionMatrix* .

.. [#] Table: Parameters table for Confusion matrix Computation.

+-----------------------+--------------------------------------------------------------+--------------------------+
|Parameter Key          |Parameter Name                                                |Parameter Type            |
+=======================+==============================================================+==========================+
|in                     |Input Image                                                   |Input image               |
+-----------------------+--------------------------------------------------------------+--------------------------+
|out                    |Matrix output                                                 |Output File name          |
+-----------------------+--------------------------------------------------------------+--------------------------+
|format                 |set the output format to contingency table or confusion matrix|Choices                   |
+-----------------------+--------------------------------------------------------------+--------------------------+
|format confusionmatrix |Choice of a confusion matrix as output.                       | *Choice*                 |
+-----------------------+--------------------------------------------------------------+--------------------------+
|format contingencytable|Choice of a contingency table as output.                      | *Choice*                 |
+-----------------------+--------------------------------------------------------------+--------------------------+
|ref                    |Ground truth                                                  |Choices                   |
+-----------------------+--------------------------------------------------------------+--------------------------+
|ref raster             |Ground truth as a raster image                                | *Choice*                 |
+-----------------------+--------------------------------------------------------------+--------------------------+
|ref vector             |Ground truth as a vector data file                            | *Choice*                 |
+-----------------------+--------------------------------------------------------------+--------------------------+
|ref.raster.in          |Input reference image                                         |Input image               |
+-----------------------+--------------------------------------------------------------+--------------------------+
|ref.raster.nodata      |Value for nodata pixels in ref raster                         |Int                       |
+-----------------------+--------------------------------------------------------------+--------------------------+
|ref.vector.in          |Input reference vector data                                   |Input File name           |
+-----------------------+--------------------------------------------------------------+--------------------------+
|ref.vector.field       |Field name                                                    |List                      |
+-----------------------+--------------------------------------------------------------+--------------------------+
|ref.vector.nodata      |Value for nodata pixels in ref vector                         |Int                       |
+-----------------------+--------------------------------------------------------------+--------------------------+
|nodatalabel            |Value for nodata pixels in input image                        |Int                       |
+-----------------------+--------------------------------------------------------------+--------------------------+
|ram                    |Available RAM (Mb)                                            |Int                       |
+-----------------------+--------------------------------------------------------------+--------------------------+
|inxml                  |Load otb application from xml file                            |XML input parameters file |
+-----------------------+--------------------------------------------------------------+--------------------------+
|outxml                 |Save otb application to xml file                              |XML output parameters file|
+-----------------------+--------------------------------------------------------------+--------------------------+

**Input Image**: The input classification image.

**Matrix output**: Filename to store the output matrix (csv format).

**set the output format to contingency table or confusion matrix**: Choice of the output format as a contingency table for unsupervised algorithmsor confusion matrix for supervised ones. Available choices are: 

- **Choice of a confusion matrix as output.**
- **Choice of a contingency table as output.**

**Ground truth**: Choice of ground truth format. Available choices are: 

- **Ground truth as a raster image**

 * **Input reference image**: Input image containing the ground truth labels.
 * **Value for nodata pixels in ref raster**: Label to be treated as no data in ref raster.

- **Ground truth as a vector data file**

 * **Input reference vector data**: Input vector data of the ground truth.
 * **Field name**: Field name containing the label values.
 * **Value for nodata pixels in ref vector**: Label to be treated as no data in ref vector. Please note that this value is always used in vector mode, to generate default values. Please set it to a value that does not correspond to a class label.


**Value for nodata pixels in input image**: Label to be treated as no data in input image.

**Available RAM (Mb)**: Available memory for processing (in MB).

**Load otb application from xml file**: Load otb application from xml file.

**Save otb application to xml file**: Save otb application to xml file.



Example
-------

To run this example in command-line, use the following: 
::

	otbcli_ComputeConfusionMatrix -in clLabeledImageQB1.tif -out ConfusionMatrix.csv -ref vector -ref.vector.in VectorData_QB1_bis.shp -ref.vector.field Class -ref.vector.nodata 255

To run this example from Python, use the following code snippet: 

::

	#!/usr/bin/python

	# Import the otb applications package
	import otbApplication

	# The following line creates an instance of the ComputeConfusionMatrix application 
	ComputeConfusionMatrix = otbApplication.Registry.CreateApplication("ComputeConfusionMatrix")

	# The following lines set all the application parameters:
	ComputeConfusionMatrix.SetParameterString("in", "clLabeledImageQB1.tif")

	ComputeConfusionMatrix.SetParameterString("out", "ConfusionMatrix.csv")

	ComputeConfusionMatrix.SetParameterString("ref","vector")

	ComputeConfusionMatrix.SetParameterString("ref.vector.in", "VectorData_QB1_bis.shp")

	# The following line execute the application
	ComputeConfusionMatrix.ExecuteAndWriteOutput()

Limitations
~~~~~~~~~~~

None

Authors
~~~~~~~

This application has been written by OTB-Team.