Multiclassroc

---
name: multiclassroc
description: Compute the MulticlassROC metric — provided by torchmetrics. Use when the user has predictions and ground-truth and needs to compute MulticlassROC, or asks how to score with MulticlassROC.
metadata:
  skill_kind: metric
  source_lib: torchmetrics
  import_path: torchmetrics.classification.MulticlassROC
  source: library_introspection
---

# multiclassroc

> Metric `MulticlassROC` from `torchmetrics` (torchmetrics.classification.MulticlassROC)

## When to invoke this skill

The user has predictions + ground truth and asks to evaluate with MulticlassROC, or
mentions `torchmetrics.classification.MulticlassROC` directly, or wants the standard torchmetrics implementation.

## Reference signature

```python
from torchmetrics.classification import MulticlassROC

# MulticlassROC(num_classes: int, thresholds: Union[int, list[float], torch.Tensor, NoneType] = None, average: Optional[Literal['micro', 'macro']] = None, ignore_index: Optional[int] = None, validate_args: bool = True, **kwargs: Any) -> None
```

## Library docstring

```
Compute the Receiver Operating Characteristic (ROC) for binary tasks.

The curve consist of multiple pairs of true positive rate (TPR) and false positive rate (FPR) values evaluated at
different thresholds, such that the tradeoff between the two values can be seen.

For multiclass the metric is calculated by iteratively treating each class as the positive class and all other
classes as the negative, which is referred to as the one-vs-rest approach. One-vs-one is currently not supported by
this metric.

As input to ``forward`` and ``update`` the metric accepts the following input:

- ``preds`` (:class:`~torch.Tensor`): A float tensor of shape ``(N, C, ...)``. Preds should be a tensor
  containing probabilities or logits for each observation. If preds has values outside [0,1] range we consider
  the input to be logits and will auto apply softmax per sample.
- ``target`` (:class:`~torch.Tensor`): An int tensor of shape ``(N, ...)``. Target should be a tensor containing
  ground truth labels, and therefore only contain values in the [0, n_classes-1] range (except if `ignore_index`
  is specified).

.. tip::
   Additional dimension ``...`` will be flattened into the batch dimension.

As output to ``forward`` and ``compute`` the metric returns a tuple of either 3 tensors or 3 lists containing

- ``fpr`` (:class:`~torch.Tensor`): if `thresholds=None` a list for each class is returned with an 1d tensor of
  size ``(n_thresholds+1, )`` with false positive rate values (length may differ between classes). If `thresholds`
  is set to something else, then a single 2d tensor of size ``(n_classes, n_thresholds+1)`` with false positive rate
  values is returned.
- ``tpr`` (:class:`~torch.Tensor`): if `thresholds=None` a list for each class is returned with an 1d tensor of
  size ``(n_thresholds+1, )`` with true positive rate values (length may differ between classes). If `thresholds` is
  set to something else, then a single 2d tensor of size ``(n_classes, n_thresholds+1)`` with true positive rate
  values is returned.
- ``thresholds`` (:class:`~torch.Tensor`): if `thresholds=None` a list for each class is returned with an 1d
  tensor of size ``(n_thresholds, )`` with decreasin
```

## Quick recipe

```python
import torchmetrics.classification as _m
score = _m.MulticlassROC(y_true, y_pred)
```

## Don'ts

- Don't reimplement when the library version handles edge cases (NaN, ties, empty inputs) better than a hand-rolled formula.
- Always check the library version's argument order — sklearn is `(y_true, y_pred)` while torchmetrics is `(preds, target)`.