# recognition_confusion_matrix

Python API: `luxonis_train.attached_modules.metrics.confusion_matrix.recognition_confusion_matrix`

The confusion matrix for classification and segmentation.

## Classes

### RecognitionConfusionMatrix

Confusion matrix for classification and semantic segmentation.

 * `Inputs:`: * `predictions` (`Tensor`): `[B, n_classes, ...]` logits
    * `targets` (`Tensor`): same shape, one-hot
 * `Outputs:`: * `mcc` (`Tensor`): scalar MCC of the matrix, see
   [compute_mcc](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/utils.md)
    * `confusion_matrix` (`Tensor`): [nclasses, nclasses] counts, or [2, 2] for one class, rows are targets
 * `Formula:`: With more than one class, the predicted class of each sample, or of each pixel, is the index of the highest logit.
   The target class is the index of the highest target value. For equal values, the lowest index wins, so a target with only zeros
   counts as class `0`. A `torchmetrics` `MulticlassConfusionMatrix` counts each pair of a target class and a predicted class.
   With one class, a `torchmetrics` `BinaryConfusionMatrix` compares each prediction value with the target value at the same
   position. When a floating point prediction of a batch is outside `[0, 1]`, it applies a sigmoid to all predictions of that
   batch. A prediction above `0.5` is positive. The matrix is `[[TN, FP], [FN, TP]]`, with the counts of true negatives (TN),
   false positives (FP), false negatives (FN), and true positives (TP).

> **References**
> * Source: Wraps [torchmetrics](https://github.com/Lightning-AI/torchmetrics) (Apache-2.0).
 * License: Apache-2.0 (this project)

> **Notes**
> The metric needs a node, because it reads `n_classes` from the node. [reset](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/recognition_confusion_matrix.md) clears the wrapped matrix, but the cached result of [compute](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/recognition_confusion_matrix.md) stays until the next [update](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/recognition_confusion_matrix.md).

> **Example**
> Attached to a `ClassificationHead` in `model.nodes`:

```yaml
- name: ClassificationHead
  inputs: [ResNet]
  metrics:
    - name: RecognitionConfusionMatrix
```

 * `Compatible with:`: * Nodes: *
   [BiSeNetHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/bisenet_head.md)
       * [ClassificationHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/classification_head.md)
       * [DDRNetSegmentationHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ddrnet_segmentation_head.md)
       * [SegmentationHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/segmentation_head.md)
       * [TransformerClassificationHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_classification_head.md)
       * [TransformerSegmentationHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_segmentation_head.md)

#### Methods

##### init

```python
def __init__(**kwargs):
```

Initialize the metric and the wrapped matrix.

The `metric` attribute holds the wrapped matrix. It is a `BinaryConfusionMatrix` when the node has one class. Otherwise it is a
`MulticlassConfusionMatrix` with `n_classes` classes.

Parameters

 * `**kwargs`: Keyword arguments forwarded to
   [BaseMetric](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md),
   such as `node`.

##### compute

```python
def compute(self) -> dict[str, Tensor]:
```

Return the MCC and the matrix since the last reset.

> **Example**
> The batch has three samples and two classes. The third sample has the target class `1`, but the model predicts class `0`. A `SimpleNamespace` stands in for the node.

```pycon
>>> import torch
>>> from types import SimpleNamespace
>>> node = SimpleNamespace(task=None, n_classes=2)
>>> metric = RecognitionConfusionMatrix(node=node)
>>> logits = torch.tensor([[2.0, 0.0], [0.0, 1.0], [3.0, 1.0]])
>>> targets = torch.tensor([[1, 0], [0, 1], [0, 1]])
>>> metric.update(logits, targets)
>>> result = metric.compute()
>>> result["confusion_matrix"].tolist()
[[1, 0], [1, 1]]
>>> result["mcc"].item()
0.5
```

Returns

 * `dict[str, Tensor]`: A dictionary with two keys. * `"mcc"` holds the scalar MCC of the matrix, see
   [compute_mcc](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/utils.md).
    * `"confusion_matrix"` holds the `int64` counts. Rows are target classes and columns are predicted classes. The shape is
      `[n_classes, n_classes]`, or `[2, 2]` for one class.

##### reset

```python
def reset(self):
```

Reset the wrapped `torchmetrics` matrix.

The method does not call `Metric.reset` of `torchmetrics` on this metric. The cached result of the last
[compute](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/recognition_confusion_matrix.md)
stays, and
[compute](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/recognition_confusion_matrix.md)
returns it until the next
[update](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/recognition_confusion_matrix.md).
In
[InstanceSegmentationConfusionMatrix](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/instance_segmentation_confusion_matrix.md),
the box matrix also keeps its counts.

> **Example**
> After the reset, [compute](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/recognition_confusion_matrix.md) returns the cached result of the first batch. The next [update](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/recognition_confusion_matrix.md) clears the cache, and the new result holds only the second batch.

```pycon
>>> import torch
>>> from types import SimpleNamespace
>>> node = SimpleNamespace(task=None, n_classes=2)
>>> metric = RecognitionConfusionMatrix(node=node)
>>> class_0 = torch.tensor([[1.0, 0.0]])
>>> class_1 = torch.tensor([[0.0, 1.0]])
>>> metric.update(class_0, class_0)
>>> metric.compute()["confusion_matrix"].tolist()
[[1, 0], [0, 0]]
>>> metric.reset()
>>> metric.compute()["confusion_matrix"].tolist()
[[1, 0], [0, 0]]
>>> metric.update(class_1, class_1)
>>> metric.compute()["confusion_matrix"].tolist()
[[0, 0], [0, 1]]
```

##### update

```python
def update(predictions: Tensor, targets: Tensor):
```

Add the predictions and targets of one batch to the matrix.

With more than one class, the method takes the `argmax` over dimension `1` of both tensors. With one class, it passes both tensors
unchanged. The class docstring describes how the wrapped matrix counts them.

Parameters

 * `predictions` (`Tensor`): The main output of the node, as logits of shape `[B, n_classes]` for classification, or `[B,
   n_classes, H, W]` for segmentation.
 * `targets` (`Tensor`): One-hot labels of the same shape, the `classification` or `segmentation` label of the task. With one
   class, the values must be `0` or `1`. Other values make `torchmetrics` raise `RuntimeError`.

#### Attributes

##### metric

##### supported_tasks