---
title: Recall
description: Compute Recall.
canonical: 'https://lightning.ai/docs/torchmetrics/stable/classification/recall'
---
# Recall {#recall}

## Module Interface {#module-interface}

### `class torchmetrics.Recall(**kwargs)` {#torchmetrics.Recall}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/classification/precision_recall.py#L1024-L1086)

Compute [Recall](https://en.wikipedia.org/wiki/Precision_and_recall).

```math
\text{Recall} = \frac{\text{TP}}{\text{TP} + \text{FN}}
```

Where $`\text{TP}`$ and $`\text{FN}`$ represent the number of true positives and false negatives respectively. The metric is only proper defined when $`\text{TP} + \text{FN} \neq 0`$. If this case is encountered for any class/label, the metric for that class/label will be set to 0 and the overall metric may therefore be affected in turn.

This function is a simple wrapper to get the task specific versions of this metric, which is done by setting the `task` argument to either `'binary'`, `'multiclass'` or `'multilabel'`. See the documentation of [`BinaryRecall`](#torchmetrics.classification.BinaryRecall "torchmetrics.classification.BinaryRecall"), [`MulticlassRecall`](#torchmetrics.classification.MulticlassRecall "torchmetrics.classification.MulticlassRecall") and [`MultilabelRecall`](#torchmetrics.classification.MultilabelRecall "torchmetrics.classification.MultilabelRecall") for the specific details of each argument influence and examples.

Legacy Example:

```python
>>> from torch import tensor
>>> preds  = tensor([2, 0, 2, 1])
>>> target = tensor([1, 1, 2, 0])
>>> recall = Recall(task="multiclass", average='macro', num_classes=3)
>>> recall(preds, target)
tensor(0.3333)
>>> recall = Recall(task="multiclass", average='micro', num_classes=3)
>>> recall(preds, target)
tensor(0.2500)
```

#### `static __new__(cls, task, threshold=0.5, num_classes=None, num_labels=None, average='micro', multidim_average='global', top_k=1, ignore_index=None, validate_args=True, **kwargs)` {#torchmetrics.Recall.__new__}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/classification/precision_recall.py#L1053-L1086)

Initialize task metric.

Return type:

[`Metric`](/docs/torchmetrics/1.9.0/api-reference/metric.md#torchmetrics.Metric "torchmetrics.metric.Metric")

### BinaryRecall {#binaryrecall}

### `class torchmetrics.classification.BinaryRecall(threshold=0.5, multidim_average='global', ignore_index=None, validate_args=True, **kwargs)` {#torchmetrics.classification.BinaryRecall}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/classification/precision_recall.py#L501-L629)

Compute [Recall](https://en.wikipedia.org/wiki/Precision_and_recall) for binary tasks.

```math
\text{Recall} = \frac{\text{TP}}{\text{TP} + \text{FN}}
```

Where $`\text{TP}`$ and $`\text{FN}`$ represent the number of true positives and false negatives respectively. The metric is only proper defined when $`\text{TP} + \text{FN} \neq 0`$. If this case is encountered a score of zero\_division (0 or 1, default is 0) is returned.

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

*   `preds` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): An int tensor or float tensor of shape `(N, ...)`. If preds is a floating point tensor with values outside \[0,1\] range we consider the input to be logits and will auto apply sigmoid per element. Additionally, we convert to int tensor with thresholding using the value in `threshold`.
    
*   `target` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): An int tensor of shape `(N, ...)`
    

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

*   `br` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): If `multidim_average` is set to `global`, the metric returns a scalar value. If `multidim_average` is set to `samplewise`, the metric returns `(N,)` vector consisting of a scalar value per sample.
    

If `multidim_average` is set to `samplewise` we expect at least one additional dimension `...` to be present, which the reduction will then be applied over instead of the sample dimension `N`.

Parameters:

*   **threshold** ([`float`](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")) – Threshold for transforming probability to binary {0,1} predictions
    
*   **multidim\_average** ([`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'global'`, `'samplewise'`\]) –
    
    Defines how additionally dimensions `...` should be handled. Should be one of the following:
    
    *   `global`: Additional dimensions are flatted along the batch dimension
        
    *   `samplewise`: Statistic will be calculated independently for each sample on the `N` axis. The statistics in this case are calculated over the additional dimensions.
        
    
*   **ignore\_index** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")\]) – Specifies a target value that is ignored and does not contribute to the metric calculation
    
*   **validate\_args** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – bool indicating if input arguments and tensors should be validated for correctness. Set to `False` for faster computations.
    
*   **zero\_division** – Should be 0 or 1. The value returned when $`\text{TP} + \text{FN} = 0`$.
    

Example (preds is int tensor):

```python
>>> from torch import tensor
>>> from torchmetrics.classification import BinaryRecall
>>> target = tensor([0, 1, 0, 1, 0, 1])
>>> preds = tensor([0, 0, 1, 1, 0, 1])
>>> metric = BinaryRecall()
>>> metric(preds, target)
tensor(0.6667)
```

Example (preds is float tensor):

```python
>>> from torchmetrics.classification import BinaryRecall
>>> target = tensor([0, 1, 0, 1, 0, 1])
>>> preds = tensor([0.11, 0.22, 0.84, 0.73, 0.33, 0.92])
>>> metric = BinaryRecall()
>>> metric(preds, target)
tensor(0.6667)
```

Example (multidim tensors):

```python
>>> from torchmetrics.classification import BinaryRecall
>>> target = tensor([[[0, 1], [1, 0], [0, 1]], [[1, 1], [0, 0], [1, 0]]])
>>> preds = tensor([[[0.59, 0.91], [0.91, 0.99],  [0.63, 0.04]],
...                 [[0.38, 0.04], [0.86, 0.780], [0.45, 0.37]]])
>>> metric = BinaryRecall(multidim_average='samplewise')
>>> metric(preds, target)
tensor([0.6667, 0.0000])
```

#### `plot(val=None, ax=None)` {#torchmetrics.classification.BinaryRecall.plot}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/classification/precision_recall.py#L589-L629)

Plot a single or multiple values from the metric.

Parameters:

*   **val** (`Union`\[[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)"), [`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.15)")\[[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")\], [`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")\]) – Either a single result from calling metric.forward or metric.compute or a list of these results. If no value is provided, will automatically call metric.compute and plot that result.
    
*   **ax** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Axes`](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.11.2)")\]) – An matplotlib axis object. If provided will add plot to that axis
    

Return type:

[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")\[[`Figure`](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html#matplotlib.figure.Figure "(in Matplotlib v3.11.2)"), `Union`\[[`Axes`](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.11.2)"), [`ndarray`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.5)")\]\]

Returns:

Figure object and Axes object

Raises:

[**ModuleNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#ModuleNotFoundError "(in Python v3.15)") – If matplotlib is not installed

```python
>>> from torch import rand, randint
>>> # Example plotting a single value
>>> from torchmetrics.classification import BinaryRecall
>>> metric = BinaryRecall()
>>> metric.update(rand(10), randint(2,(10,)))
>>> fig_, ax_ = metric.plot()
```

[![../../\_images/recall-1.png](/docs/torchmetrics/1.9.0/static/_images/recall-1.png)](/docs/torchmetrics/1.9.0/static/_images/recall-1.png)

```python
>>> from torch import rand, randint
>>> # Example plotting multiple values
>>> from torchmetrics.classification import BinaryRecall
>>> metric = BinaryRecall()
>>> values = [ ]
>>> for _ in range(10):
...     values.append(metric(rand(10), randint(2,(10,))))
>>> fig_, ax_ = metric.plot(values)
```

[![../../\_images/recall-2.png](/docs/torchmetrics/1.9.0/static/_images/recall-2.png)](/docs/torchmetrics/1.9.0/static/_images/recall-2.png)

### MulticlassRecall {#multiclassrecall}

### `class torchmetrics.classification.MulticlassRecall(num_classes=None, top_k=1, average='macro', multidim_average='global', ignore_index=None, validate_args=True, **kwargs)` {#torchmetrics.classification.MulticlassRecall}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/classification/precision_recall.py#L632-L794)

Compute [Recall](https://en.wikipedia.org/wiki/Precision_and_recall) for multiclass tasks.

```math
\text{Recall} = \frac{\text{TP}}{\text{TP} + \text{FN}}
```

Where $`\text{TP}`$ and $`\text{FN}`$ represent the number of true positives and false negatives respectively. The metric is only proper defined when $`\text{TP} + \text{FN} \neq 0`$. If this case is encountered for any class, the metric for that class will be set to zero\_division (0 or 1, default is 0) and the overall metric may therefore be affected in turn.

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

*   `preds` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): An int tensor of shape `(N, ...)` or float tensor of shape `(N, C, ..)` If preds is a floating point we apply `torch.argmax` along the `C` dimension to automatically convert probabilities/logits into an int tensor.
    
*   `target` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): An int tensor of shape `(N, ...)`
    

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

*   `mcr` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): The returned shape depends on the `average` and `multidim_average` arguments:
    
    *   If `multidim_average` is set to `global`:
        
        *   If `average='micro'/'macro'/'weighted'`, the output will be a scalar tensor
            
        *   If `average=None/'none'`, the shape will be `(C,)`
            
    *   If `multidim_average` is set to `samplewise`:
        
        *   If `average='micro'/'macro'/'weighted'`, the shape will be `(N,)`
            
        *   If `average=None/'none'`, the shape will be `(N, C)`
            

If `multidim_average` is set to `samplewise` we expect at least one additional dimension `...` to be present, which the reduction will then be applied over instead of the sample dimension `N`.

Parameters:

*   **num\_classes** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")\]) – Integer specifying the number of classes
    
*   **average** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'micro'`, `'macro'`, `'weighted'`, `'none'`\]\]) –
    
    Defines the reduction that is applied over labels. Should be one of the following:
    
    *   `micro`: Sum statistics over all labels
        
    *   `macro`: Calculate statistics for each label and average them
        
    *   `weighted`: calculates statistics for each label and computes weighted average using their support
        
    *   `"none"` or `None`: calculates statistic for each label and applies no reduction
        
    
*   **top\_k** ([`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")) – Number of highest probability or logit score predictions considered to find the correct label. Only works when `preds` contain probabilities/logits.
    
*   **multidim\_average** ([`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'global'`, `'samplewise'`\]) –
    
    Defines how additionally dimensions `...` should be handled. Should be one of the following:
    
    *   `global`: Additional dimensions are flatted along the batch dimension
        
    *   `samplewise`: Statistic will be calculated independently for each sample on the `N` axis. The statistics in this case are calculated over the additional dimensions.
        
    
*   **ignore\_index** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")\]) – Specifies a target value that is ignored and does not contribute to the metric calculation
    
*   **validate\_args** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – bool indicating if input arguments and tensors should be validated for correctness. Set to `False` for faster computations.
    
*   **zero\_division** – Should be 0 or 1. The value returned when $`\text{TP} + \text{FN} = 0`$.
    

Example (preds is int tensor):

```python
>>> from torch import tensor
>>> from torchmetrics.classification import MulticlassRecall
>>> target = tensor([2, 1, 0, 0])
>>> preds = tensor([2, 1, 0, 1])
>>> metric = MulticlassRecall(num_classes=3)
>>> metric(preds, target)
tensor(0.8333)
>>> mcr = MulticlassRecall(num_classes=3, average=None)
>>> mcr(preds, target)
tensor([0.5000, 1.0000, 1.0000])
```

Example (preds is float tensor):

```python
>>> from torchmetrics.classification import MulticlassRecall
>>> target = tensor([2, 1, 0, 0])
>>> preds = tensor([[0.16, 0.26, 0.58],
...                 [0.22, 0.61, 0.17],
...                 [0.71, 0.09, 0.20],
...                 [0.05, 0.82, 0.13]])
>>> metric = MulticlassRecall(num_classes=3)
>>> metric(preds, target)
tensor(0.8333)
>>> mcr = MulticlassRecall(num_classes=3, average=None)
>>> mcr(preds, target)
tensor([0.5000, 1.0000, 1.0000])
```

Example (multidim tensors):

```python
>>> from torchmetrics.classification import MulticlassRecall
>>> target = tensor([[[0, 1], [2, 1], [0, 2]], [[1, 1], [2, 0], [1, 2]]])
>>> preds = tensor([[[0, 2], [2, 0], [0, 1]], [[2, 2], [2, 1], [1, 0]]])
>>> metric = MulticlassRecall(num_classes=3, multidim_average='samplewise')
>>> metric(preds, target)
tensor([0.5000, 0.2778])
>>> mcr = MulticlassRecall(num_classes=3, multidim_average='samplewise', average=None)
>>> mcr(preds, target)
tensor([[1.0000, 0.0000, 0.5000],
        [0.0000, 0.3333, 0.5000]])
```

#### `plot(val=None, ax=None)` {#torchmetrics.classification.MulticlassRecall.plot}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/classification/precision_recall.py#L754-L794)

Plot a single or multiple values from the metric.

Parameters:

*   **val** (`Union`\[[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)"), [`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.15)")\[[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")\], [`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")\]) – Either a single result from calling metric.forward or metric.compute or a list of these results. If no value is provided, will automatically call metric.compute and plot that result.
    
*   **ax** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Axes`](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.11.2)")\]) – An matplotlib axis object. If provided will add plot to that axis
    

Return type:

[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")\[[`Figure`](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html#matplotlib.figure.Figure "(in Matplotlib v3.11.2)"), `Union`\[[`Axes`](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.11.2)"), [`ndarray`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.5)")\]\]

Returns:

Figure object and Axes object

Raises:

[**ModuleNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#ModuleNotFoundError "(in Python v3.15)") – If matplotlib is not installed

```python
>>> from torch import randint
>>> # Example plotting a single value per class
>>> from torchmetrics.classification import MulticlassRecall
>>> metric = MulticlassRecall(num_classes=3, average=None)
>>> metric.update(randint(3, (20,)), randint(3, (20,)))
>>> fig_, ax_ = metric.plot()
```

[![../../\_images/recall-3.png](/docs/torchmetrics/1.9.0/static/_images/recall-3.png)](/docs/torchmetrics/1.9.0/static/_images/recall-3.png)

```python
>>> from torch import randint
>>> # Example plotting a multiple values per class
>>> from torchmetrics.classification import MulticlassRecall
>>> metric = MulticlassRecall(num_classes=3, average=None)
>>> values = []
>>> for _ in range(20):
...     values.append(metric(randint(3, (20,)), randint(3, (20,))))
>>> fig_, ax_ = metric.plot(values)
```

[![../../\_images/recall-4.png](/docs/torchmetrics/1.9.0/static/_images/recall-4.png)](/docs/torchmetrics/1.9.0/static/_images/recall-4.png)

### MultilabelRecall {#multilabelrecall}

### `class torchmetrics.classification.MultilabelRecall(num_labels, threshold=0.5, average='macro', multidim_average='global', ignore_index=None, validate_args=True, **kwargs)` {#torchmetrics.classification.MultilabelRecall}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/classification/precision_recall.py#L797-L956)

Compute [Recall](https://en.wikipedia.org/wiki/Precision_and_recall) for multilabel tasks.

```math
\text{Recall} = \frac{\text{TP}}{\text{TP} + \text{FN}}
```

Where $`\text{TP}`$ and $`\text{FN}`$ represent the number of true positives and false negatives respectively. The metric is only proper defined when $`\text{TP} + \text{FN} \neq 0`$. If this case is encountered for any label, the metric for that label will be set to zero\_division (0 or 1, default is 0) and the overall metric may therefore be affected in turn.

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

*   `preds` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): An int or float tensor of shape `(N, C, ...)`. If preds is a floating point tensor with values outside \[0,1\] range we consider the input to be logits and will auto apply sigmoid per element. Additionally, we convert to int tensor with thresholding using the value in `threshold`.
    
*   `target` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): An int tensor of shape `(N, C, ...)`
    

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

*   `mlr` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): The returned shape depends on the `average` and `multidim_average` arguments:
    
    *   If `multidim_average` is set to `global`:
        
        *   If `average='micro'/'macro'/'weighted'`, the output will be a scalar tensor
            
        *   If `average=None/'none'`, the shape will be `(C,)`
            
    *   If `multidim_average` is set to `samplewise`:
        
        *   If `average='micro'/'macro'/'weighted'`, the shape will be `(N,)`
            
        *   If `average=None/'none'`, the shape will be `(N, C)`
            

If `multidim_average` is set to `samplewise` we expect at least one additional dimension `...` to be present, which the reduction will then be applied over instead of the sample dimension `N`.

Parameters:

*   **num\_labels** ([`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")) – Integer specifying the number of labels
    
*   **threshold** ([`float`](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")) – Threshold for transforming probability to binary (0,1) predictions
    
*   **average** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'micro'`, `'macro'`, `'weighted'`, `'none'`\]\]) –
    
    Defines the reduction that is applied over labels. Should be one of the following:
    
    *   `micro`: Sum statistics over all labels
        
    *   `macro`: Calculate statistics for each label and average them
        
    *   `weighted`: calculates statistics for each label and computes weighted average using their support
        
    *   `"none"` or `None`: calculates statistic for each label and applies no reduction
        
    
*   **multidim\_average** ([`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'global'`, `'samplewise'`\]) –
    
    Defines how additionally dimensions `...` should be handled. Should be one of the following:
    
    *   `global`: Additional dimensions are flatted along the batch dimension
        
    *   `samplewise`: Statistic will be calculated independently for each sample on the `N` axis. The statistics in this case are calculated over the additional dimensions.
        
    
*   **ignore\_index** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")\]) – Specifies a target value that is ignored and does not contribute to the metric calculation
    
*   **validate\_args** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – bool indicating if input arguments and tensors should be validated for correctness. Set to `False` for faster computations.
    
*   **zero\_division** – Should be 0 or 1. The value returned when $`\text{TP} + \text{FN} = 0`$.
    

Example (preds is int tensor):

```python
>>> from torch import tensor
>>> from torchmetrics.classification import MultilabelRecall
>>> target = tensor([[0, 1, 0], [1, 0, 1]])
>>> preds = tensor([[0, 0, 1], [1, 0, 1]])
>>> metric = MultilabelRecall(num_labels=3)
>>> metric(preds, target)
tensor(0.6667)
>>> mlr = MultilabelRecall(num_labels=3, average=None)
>>> mlr(preds, target)
tensor([1., 0., 1.])
```

Example (preds is float tensor):

```python
>>> from torchmetrics.classification import MultilabelRecall
>>> target = tensor([[0, 1, 0], [1, 0, 1]])
>>> preds = tensor([[0.11, 0.22, 0.84], [0.73, 0.33, 0.92]])
>>> metric = MultilabelRecall(num_labels=3)
>>> metric(preds, target)
tensor(0.6667)
>>> mlr = MultilabelRecall(num_labels=3, average=None)
>>> mlr(preds, target)
tensor([1., 0., 1.])
```

Example (multidim tensors):

```python
>>> from torchmetrics.classification import MultilabelRecall
>>> target = tensor([[[0, 1], [1, 0], [0, 1]], [[1, 1], [0, 0], [1, 0]]])
>>> preds = tensor([[[0.59, 0.91], [0.91, 0.99], [0.63, 0.04]],
...                 [[0.38, 0.04], [0.86, 0.780], [0.45, 0.37]]])
>>> metric = MultilabelRecall(num_labels=3, multidim_average='samplewise')
>>> metric(preds, target)
tensor([0.6667, 0.0000])
>>> mlr = MultilabelRecall(num_labels=3, multidim_average='samplewise', average=None)
>>> mlr(preds, target)
tensor([[1., 1., 0.],
        [0., 0., 0.]])
```

#### `plot(val=None, ax=None)` {#torchmetrics.classification.MultilabelRecall.plot}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/classification/precision_recall.py#L916-L956)

Plot a single or multiple values from the metric.

Parameters:

*   **val** (`Union`\[[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)"), [`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.15)")\[[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")\], [`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")\]) – Either a single result from calling metric.forward or metric.compute or a list of these results. If no value is provided, will automatically call metric.compute and plot that result.
    
*   **ax** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Axes`](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.11.2)")\]) – An matplotlib axis object. If provided will add plot to that axis
    

Return type:

[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")\[[`Figure`](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html#matplotlib.figure.Figure "(in Matplotlib v3.11.2)"), `Union`\[[`Axes`](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.11.2)"), [`ndarray`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.5)")\]\]

Returns:

Figure object and Axes object

Raises:

[**ModuleNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#ModuleNotFoundError "(in Python v3.15)") – If matplotlib is not installed

```python
>>> from torch import rand, randint
>>> # Example plotting a single value
>>> from torchmetrics.classification import MultilabelRecall
>>> metric = MultilabelRecall(num_labels=3)
>>> metric.update(randint(2, (20, 3)), randint(2, (20, 3)))
>>> fig_, ax_ = metric.plot()
```

[![../../\_images/recall-5.png](/docs/torchmetrics/1.9.0/static/_images/recall-5.png)](/docs/torchmetrics/1.9.0/static/_images/recall-5.png)

```python
>>> from torch import rand, randint
>>> # Example plotting multiple values
>>> from torchmetrics.classification import MultilabelRecall
>>> metric = MultilabelRecall(num_labels=3)
>>> values = [ ]
>>> for _ in range(10):
...     values.append(metric(randint(2, (20, 3)), randint(2, (20, 3))))
>>> fig_, ax_ = metric.plot(values)
```

[![../../\_images/recall-6.png](/docs/torchmetrics/1.9.0/static/_images/recall-6.png)](/docs/torchmetrics/1.9.0/static/_images/recall-6.png)

## Functional Interface {#functional-interface}

### `torchmetrics.functional.recall(preds, target, task, threshold=0.5, num_classes=None, num_labels=None, average='micro', multidim_average='global', top_k=1, ignore_index=None, validate_args=True, zero_division=0)` {#torchmetrics.functional.recall}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/functional/classification/precision_recall.py#L742-L798)

Compute [Recall](https://en.wikipedia.org/wiki/Precision_and_recall). :rtype: [`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")

```math
\text{Recall} = \frac{\text{TP}}{\text{TP} + \text{FN}}
```

Where $`\text{TP}`$ and $`\text{FN}`$ represent the number of true positives and false negatives respecitively.

This function is a simple wrapper to get the task specific versions of this metric, which is done by setting the `task` argument to either `'binary'`, `'multiclass'` or `'multilabel'`. See the documentation of [`binary_recall()`](#torchmetrics.functional.classification.binary_recall "torchmetrics.functional.classification.binary_recall"), [`multiclass_recall()`](#torchmetrics.functional.classification.multiclass_recall "torchmetrics.functional.classification.multiclass_recall") and [`multilabel_recall()`](#torchmetrics.functional.classification.multilabel_recall "torchmetrics.functional.classification.multilabel_recall") for the specific details of each argument influence and examples.

Legacy Example:

```python
>>> from torch import tensor
>>> preds  = tensor([2, 0, 2, 1])
>>> target = tensor([1, 1, 2, 0])
>>> recall(preds, target, task="multiclass", average='macro', num_classes=3)
tensor(0.3333)
>>> recall(preds, target, task="multiclass", average='micro', num_classes=3)
tensor(0.2500)
```

### binary_recall {#binary-recall}

### `torchmetrics.functional.classification.binary_recall(preds, target, threshold=0.5, multidim_average='global', ignore_index=None, validate_args=True, zero_division=0)` {#torchmetrics.functional.classification.binary_recall}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/functional/classification/precision_recall.py#L372-L447)

Compute [Recall](https://en.wikipedia.org/wiki/Precision_and_recall) for binary tasks.

```math
\text{Recall} = \frac{\text{TP}}{\text{TP} + \text{FN}}
```

Where $`\text{TP}`$ and $`\text{FN}`$ represent the number of true positives and false negatives respecitively.

Accepts the following input tensors:

*   `preds` (int or float tensor): `(N, ...)`. If preds is a floating point tensor with values outside \[0,1\] range we consider the input to be logits and will auto apply sigmoid per element. Additionally, we convert to int tensor with thresholding using the value in `threshold`.
    
*   `target` (int tensor): `(N, ...)`
    

Parameters:

*   **preds** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – Tensor with predictions
    
*   **target** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – Tensor with true labels
    
*   **threshold** ([`float`](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")) – Threshold for transforming probability to binary {0,1} predictions
    
*   **multidim\_average** ([`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'global'`, `'samplewise'`\]) –
    
    Defines how additionally dimensions `...` should be handled. Should be one of the following:
    
    *   `global`: Additional dimensions are flatted along the batch dimension
        
    *   `samplewise`: Statistic will be calculated independently for each sample on the `N` axis. The statistics in this case are calculated over the additional dimensions.
        
    
*   **ignore\_index** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")\]) – Specifies a target value that is ignored and does not contribute to the metric calculation
    
*   **validate\_args** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – bool indicating if input arguments and tensors should be validated for correctness. Set to `False` for faster computations.
    
*   **zero\_division** ([`float`](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")) – Should be 0 or 1. The value returned when $`\text{TP} + \text{FN} = 0`$.
    

Return type:

[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")

Returns:

If `multidim_average` is set to `global`, the metric returns a scalar value. If `multidim_average` is set to `samplewise`, the metric returns `(N,)` vector consisting of a scalar value per sample.

Example (preds is int tensor):

```python
>>> from torch import tensor
>>> from torchmetrics.functional.classification import binary_recall
>>> target = tensor([0, 1, 0, 1, 0, 1])
>>> preds = tensor([0, 0, 1, 1, 0, 1])
>>> binary_recall(preds, target)
tensor(0.6667)
```

Example (preds is float tensor):

```python
>>> from torchmetrics.functional.classification import binary_recall
>>> target = tensor([0, 1, 0, 1, 0, 1])
>>> preds = tensor([0.11, 0.22, 0.84, 0.73, 0.33, 0.92])
>>> binary_recall(preds, target)
tensor(0.6667)
```

Example (multidim tensors):

```python
>>> from torchmetrics.functional.classification import binary_recall
>>> target = tensor([[[0, 1], [1, 0], [0, 1]], [[1, 1], [0, 0], [1, 0]]])
>>> preds = tensor([[[0.59, 0.91], [0.91, 0.99], [0.63, 0.04]],
...                 [[0.38, 0.04], [0.86, 0.780], [0.45, 0.37]]])
>>> binary_recall(preds, target, multidim_average='samplewise')
tensor([0.6667, 0.0000])
```

### multiclass_recall {#multiclass-recall}

### `torchmetrics.functional.classification.multiclass_recall(preds, target, num_classes, average='macro', top_k=1, multidim_average='global', ignore_index=None, validate_args=True, zero_division=0)` {#torchmetrics.functional.classification.multiclass_recall}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/functional/classification/precision_recall.py#L450-L566)

Compute [Recall](https://en.wikipedia.org/wiki/Precision_and_recall) for multiclass tasks.

```math
\text{Recall} = \frac{\text{TP}}{\text{TP} + \text{FN}}
```

Where $`\text{TP}`$ and $`\text{FN}`$ represent the number of true positives and false negatives respecitively.

Accepts the following input tensors:

*   `preds`: `(N, ...)` (int tensor) or `(N, C, ..)` (float tensor). If preds is a floating point we apply `torch.argmax` along the `C` dimension to automatically convert probabilities/logits into an int tensor.
    
*   `target` (int tensor): `(N, ...)`
    

Parameters:

*   **preds** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – Tensor with predictions
    
*   **target** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – Tensor with true labels
    
*   **num\_classes** ([`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")) – Integer specifying the number of classes
    
*   **average** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'micro'`, `'macro'`, `'weighted'`, `'none'`\]\]) –
    
    Defines the reduction that is applied over labels. Should be one of the following:
    
    *   `micro`: Sum statistics over all labels
        
    *   `macro`: Calculate statistics for each label and average them
        
    *   `weighted`: calculates statistics for each label and computes weighted average using their support
        
    *   `"none"` or `None`: calculates statistic for each label and applies no reduction
        
    
*   **top\_k** ([`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")) – Number of highest probability or logit score predictions considered to find the correct label. Only works when `preds` contain probabilities/logits.
    
*   **multidim\_average** ([`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'global'`, `'samplewise'`\]) –
    
    Defines how additionally dimensions `...` should be handled. Should be one of the following:
    
    *   `global`: Additional dimensions are flatted along the batch dimension
        
    *   `samplewise`: Statistic will be calculated independently for each sample on the `N` axis. The statistics in this case are calculated over the additional dimensions.
        
    
*   **ignore\_index** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")\]) – Specifies a target value that is ignored and does not contribute to the metric calculation
    
*   **validate\_args** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – bool indicating if input arguments and tensors should be validated for correctness. Set to `False` for faster computations.
    
*   **zero\_division** ([`float`](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")) – Should be 0 or 1. The value returned when $`\text{TP} + \text{FN} = 0`$.
    

Returns:

*   If `multidim_average` is set to `global`:
    
    *   If `average='micro'/'macro'/'weighted'`, the output will be a scalar tensor
        
    *   If `average=None/'none'`, the shape will be `(C,)`
        
*   If `multidim_average` is set to `samplewise`:
    
    *   If `average='micro'/'macro'/'weighted'`, the shape will be `(N,)`
        
    *   If `average=None/'none'`, the shape will be `(N, C)`
        

Return type:

The returned shape depends on the `average` and `multidim_average` arguments

Example (preds is int tensor):

```python
>>> from torch import tensor
>>> from torchmetrics.functional.classification import multiclass_recall
>>> target = tensor([2, 1, 0, 0])
>>> preds = tensor([2, 1, 0, 1])
>>> multiclass_recall(preds, target, num_classes=3)
tensor(0.8333)
>>> multiclass_recall(preds, target, num_classes=3, average=None)
tensor([0.5000, 1.0000, 1.0000])
```

Example (preds is float tensor):

```python
>>> from torchmetrics.functional.classification import multiclass_recall
>>> target = tensor([2, 1, 0, 0])
>>> preds = tensor([[0.16, 0.26, 0.58],
...                 [0.22, 0.61, 0.17],
...                 [0.71, 0.09, 0.20],
...                 [0.05, 0.82, 0.13]])
>>> multiclass_recall(preds, target, num_classes=3)
tensor(0.8333)
>>> multiclass_recall(preds, target, num_classes=3, average=None)
tensor([0.5000, 1.0000, 1.0000])
```

Example (multidim tensors):

```python
>>> from torchmetrics.functional.classification import multiclass_recall
>>> target = tensor([[[0, 1], [2, 1], [0, 2]], [[1, 1], [2, 0], [1, 2]]])
>>> preds = tensor([[[0, 2], [2, 0], [0, 1]], [[2, 2], [2, 1], [1, 0]]])
>>> multiclass_recall(preds, target, num_classes=3, multidim_average='samplewise')
tensor([0.5000, 0.2778])
>>> multiclass_recall(preds, target, num_classes=3, multidim_average='samplewise', average=None)
tensor([[1.0000, 0.0000, 0.5000],
        [0.0000, 0.3333, 0.5000]])
```

### multilabel_recall {#multilabel-recall}

### `torchmetrics.functional.classification.multilabel_recall(preds, target, num_labels, threshold=0.5, average='macro', multidim_average='global', ignore_index=None, validate_args=True, zero_division=0)` {#torchmetrics.functional.classification.multilabel_recall}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/functional/classification/precision_recall.py#L569-L679)

Compute [Recall](https://en.wikipedia.org/wiki/Precision_and_recall) for multilabel tasks.

```math
\text{Recall} = \frac{\text{TP}}{\text{TP} + \text{FN}}
```

Where $`\text{TP}`$ and $`\text{FN}`$ represent the number of true positives and false negatives respecitively.

Accepts the following input tensors:

*   `preds` (int or float tensor): `(N, C, ...)`. If preds is a floating point tensor with values outside \[0,1\] range we consider the input to be logits and will auto apply sigmoid per element. Additionally, we convert to int tensor with thresholding using the value in `threshold`.
    
*   `target` (int tensor): `(N, C, ...)`
    

Parameters:

*   **preds** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – Tensor with predictions
    
*   **target** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – Tensor with true labels
    
*   **num\_labels** ([`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")) – Integer specifying the number of labels
    
*   **threshold** ([`float`](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")) – Threshold for transforming probability to binary (0,1) predictions
    
*   **average** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'micro'`, `'macro'`, `'weighted'`, `'none'`\]\]) –
    
    Defines the reduction that is applied over labels. Should be one of the following:
    
    *   `micro`: Sum statistics over all labels
        
    *   `macro`: Calculate statistics for each label and average them
        
    *   `weighted`: calculates statistics for each label and computes weighted average using their support
        
    *   `"none"` or `None`: calculates statistic for each label and applies no reduction
        
    
*   **multidim\_average** ([`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'global'`, `'samplewise'`\]) –
    
    Defines how additionally dimensions `...` should be handled. Should be one of the following:
    
    *   `global`: Additional dimensions are flatted along the batch dimension
        
    *   `samplewise`: Statistic will be calculated independently for each sample on the `N` axis. The statistics in this case are calculated over the additional dimensions.
        
    
*   **ignore\_index** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")\]) – Specifies a target value that is ignored and does not contribute to the metric calculation
    
*   **validate\_args** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – bool indicating if input arguments and tensors should be validated for correctness. Set to `False` for faster computations.
    
*   **zero\_division** ([`float`](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")) – Should be 0 or 1. The value returned when $`\text{TP} + \text{FN} = 0`$.
    

Returns:

*   If `multidim_average` is set to `global`:
    
    *   If `average='micro'/'macro'/'weighted'`, the output will be a scalar tensor
        
    *   If `average=None/'none'`, the shape will be `(C,)`
        
*   If `multidim_average` is set to `samplewise`:
    
    *   If `average='micro'/'macro'/'weighted'`, the shape will be `(N,)`
        
    *   If `average=None/'none'`, the shape will be `(N, C)`
        

Return type:

The returned shape depends on the `average` and `multidim_average` arguments

Example (preds is int tensor):

```python
>>> from torch import tensor
>>> from torchmetrics.functional.classification import multilabel_recall
>>> target = tensor([[0, 1, 0], [1, 0, 1]])
>>> preds = tensor([[0, 0, 1], [1, 0, 1]])
>>> multilabel_recall(preds, target, num_labels=3)
tensor(0.6667)
>>> multilabel_recall(preds, target, num_labels=3, average=None)
tensor([1., 0., 1.])
```

Example (preds is float tensor):

```python
>>> from torchmetrics.functional.classification import multilabel_recall
>>> target = tensor([[0, 1, 0], [1, 0, 1]])
>>> preds = tensor([[0.11, 0.22, 0.84], [0.73, 0.33, 0.92]])
>>> multilabel_recall(preds, target, num_labels=3)
tensor(0.6667)
>>> multilabel_recall(preds, target, num_labels=3, average=None)
tensor([1., 0., 1.])
```

Example (multidim tensors):

```python
>>> from torchmetrics.functional.classification import multilabel_recall
>>> target = tensor([[[0, 1], [1, 0], [0, 1]], [[1, 1], [0, 0], [1, 0]]])
>>> preds = tensor([[[0.59, 0.91], [0.91, 0.99], [0.63, 0.04]],
...                 [[0.38, 0.04], [0.86, 0.780], [0.45, 0.37]]])
>>> multilabel_recall(preds, target, num_labels=3, multidim_average='samplewise')
tensor([0.6667, 0.0000])
>>> multilabel_recall(preds, target, num_labels=3, multidim_average='samplewise', average=None)
tensor([[1., 1., 0.],
        [0., 0., 0.]])
```

---

**Navigation**

- Parent: [Classification](/docs/torchmetrics/1.9.0/classification.md)