Multiclassaverageprecision

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

# multiclassaverageprecision

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

## When to invoke this skill

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

## Reference signature

```python
from torchmetrics.classification import MulticlassAveragePrecision

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

## Library docstring

```
Compute the average precision (AP) score for multiclass tasks.

The AP score summarizes a precision-recall curve as an weighted mean of precisions at each threshold, with the
difference in recall from the previous threshold as weight:

.. math::
    AP = \sum_{n} (R_n - R_{n-1}) P_n

where :math:`P_n, R_n` is the respective precision and recall at threshold index :math:`n`. This value is
equivalent to the area under the precision-recall curve (AUPRC).

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. By default the reported metric is then the average over all classes, but this behavior can be changed
by setting the ``average`` argument.

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

- ``preds`` (:class:`~torch.Tensor`): A float tensor of shape ``(N, C, ...)`` 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, ...)`` containing ground truth labels, and
  therefore only contain values in the [0, n_classes-1] range (except if `ignore_index` is specified).

As output to ``forward`` and ``compute`` the metric returns the following output:

- ``mcap`` (:class:`~torch.Tensor`): If `average=None|"none"` then a 1d tensor of shape (n_classes, ) will be
  returned with AP score per class. If `average="macro"|"weighted"` then a single scalar is returned.

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

The implementation both supports calculating the metric in a non-binned but accurate version and a binned version
that is less accurate but more memory efficient. Setting the `thresholds` argument to `None` will activate the
non-binned  version that uses memory of size :math:`\mathcal{O}(n_{samples})` whereas setting the `thresholds`
argument to either an integer, list or a 1d tensor will use a binned version that uses memory of
size :math:
```

## Quick recipe

```python
import torchmetrics.classification as _m
score = _m.MulticlassAveragePrecision(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)`.