---
title: Retrieval Precision Recall Curve
description: Compute precision-recall pairs for different k (from 1 to max_k).
canonical: 'https://lightning.ai/docs/torchmetrics/stable/retrieval/precision_recall_curve'
---
# Retrieval Precision Recall Curve {#retrieval-precision-recall-curve}

## Module Interface {#module-interface}

### `class torchmetrics.retrieval.RetrievalPrecisionRecallCurve(max_k=None, adaptive_k=False, empty_target_action='neg', ignore_index=None, aggregation='mean', **kwargs)` {#torchmetrics.retrieval.RetrievalPrecisionRecallCurve}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/retrieval/precision_recall_curve.py#L64-L294)

Compute precision-recall pairs for different k (from 1 to max\_k).

In a ranked retrieval context, appropriate sets of retrieved documents are naturally given by the top k retrieved documents. Recall is the fraction of relevant documents retrieved among all the relevant documents. Precision is the fraction of relevant documents among all the retrieved documents. For each such set, precision and recall values can be plotted to give a recall-precision curve.

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)")): A float tensor of shape `(N, ...)`
    
*   `target` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): A long or bool tensor of shape `(N, ...)`
    
*   `indexes` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): A long tensor of shape `(N, ...)` which indicate to which query a prediction belongs
    

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

*   `precisions` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): A tensor with the fraction of relevant documents among all the retrieved documents.
    
*   `recalls` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): A tensor with the fraction of relevant documents retrieved among all the relevant documents
    
*   `top_k` ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")): A tensor with k from 1 to max\_k
    

All `indexes`, `preds` and `target` must have the same dimension and will be flatten at the beginning, so that for example, a tensor of shape `(N, M)` is treated as `(N * M, )`. Predictions will be first grouped by `indexes` and then will be computed as the mean of the metric over each query.

Parameters:

*   **max\_k** ([`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)")\]) – Calculate recall and precision for all possible top k from 1 to max\_k (default: None, which considers all possible top k)
    
*   **adaptive\_k** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – adjust k to min(k, number of documents) for each query
    
*   **empty\_target\_action** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) –
    
    Specify what to do with queries that do not have at least a positive `target`. Choose from:
    
    *   `'neg'`: those queries count as `0.0` (default)
        
    *   `'pos'`: those queries count as `1.0`
        
    *   `'skip'`: skip those queries; if all queries are skipped, `0.0` is returned
        
    *   `'error'`: raise a `ValueError`
        
    
*   **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)")\]) – Ignore predictions where the target is equal to this number.
    
*   **aggregation** (`Union`\[[`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'mean'`, `'median'`, `'min'`, `'max'`\], [`Callable`](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.15)")\]) –
    
    Specify how to aggregate over indexes. Can either a custom callable function that takes in a single tensor and returns a scalar value or one of the following strings:
    
    *   `'mean'`: average value is returned
        
    *   `'median'`: median value is returned
        
    *   `'max'`: max value is returned
        
    *   `'min'`: min value is returned
        
    
*   **kwargs** ([`Any`](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.15)")) – Additional keyword arguments, see [Advanced metric settings](/docs/torchmetrics/1.9.0/user-guide/overview.md#metric-kwargs) for more info.
    

Raises:

*   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If `empty_target_action` is not one of `error`, `skip`, `neg` or `pos`.
    
*   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If `ignore_index` is not None or an integer.
    
*   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If `max_k` parameter is not None or not an integer larger than 0.
    

Example

```python
>>> from torch import tensor
>>> from torchmetrics.retrieval import RetrievalPrecisionRecallCurve
>>> indexes = tensor([0, 0, 0, 0, 1, 1, 1])
>>> preds = tensor([0.4, 0.01, 0.5, 0.6, 0.2, 0.3, 0.5])
>>> target = tensor([True, False, False, True, True, False, True])
>>> r = RetrievalPrecisionRecallCurve(max_k=4)
>>> precisions, recalls, top_k = r(preds, target, indexes=indexes)
>>> precisions
tensor([1.0000, 0.5000, 0.6667, 0.5000])
>>> recalls
tensor([0.5000, 0.5000, 1.0000, 1.0000])
>>> top_k
tensor([1, 2, 3, 4])
```

#### `plot(curve=None, ax=None)` {#torchmetrics.retrieval.RetrievalPrecisionRecallCurve.plot}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/retrieval/precision_recall_curve.py#L258-L294)

Plot a single or multiple values from the metric.

Parameters:

*   **curve** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")\[[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)"), [`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)"), [`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")\]\]) – the output of either metric.compute or metric.forward. 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 and Axes object

Raises:

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

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

[![../../\_images/precision\_recall\_curve-11.png](/docs/torchmetrics/1.9.0/static/_images/precision_recall_curve-11.png)](/docs/torchmetrics/1.9.0/static/_images/precision_recall_curve-11.png)

## Functional Interface {#functional-interface}

### `torchmetrics.functional.retrieval.retrieval_precision_recall_curve(preds, target, max_k=None, adaptive_k=False)` {#torchmetrics.functional.retrieval.retrieval_precision_recall_curve}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/functional/retrieval/precision_recall_curve.py#L24-L100)

Compute precision-recall pairs for different k (from 1 to max\_k).

In a ranked retrieval context, appropriate sets of retrieved documents are naturally given by the top k retrieved documents.

Recall is the fraction of relevant documents retrieved among all the relevant documents. Precision is the fraction of relevant documents among all the retrieved documents.

For each such set, precision and recall values can be plotted to give a recall-precision curve.

`preds` and `target` should be of the same shape and live on the same device. If no `target` is `True`, `0` is returned. `target` must be either bool or integers and `preds` must be `float`, otherwise an error is raised.

Parameters:

*   **preds** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – estimated probabilities of each document to be relevant.
    
*   **target** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – ground truth about each document being relevant or not.
    
*   **max\_k** ([`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)")\]) – Calculate recall and precision for all possible top k from 1 to max\_k (default: None, which considers all possible top k)
    
*   **adaptive\_k** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – adjust max\_k to min(max\_k, number of documents) for each query
    

Return type:

[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")\[[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)"), [`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)"), [`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")\]

Returns:

Tensor with the precision values for each k (at `top_k`) from 1 to max\_k Tensor with the recall values for each k (at `top_k`) from 1 to max\_k Tensor with all possibles k

Raises:

*   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If `max_k` is not None or an integer larger than 0.
    
*   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If `adaptive_k` is not boolean.
    

Example

```python
>>> from torch import tensor
>>> from  torchmetrics.functional import retrieval_precision_recall_curve
>>> preds = tensor([0.2, 0.3, 0.5])
>>> target = tensor([True, False, True])
>>> precisions, recalls, top_k = retrieval_precision_recall_curve(preds, target, max_k=2)
>>> precisions
tensor([1.0000, 0.5000])
>>> recalls
tensor([0.5000, 0.5000])
>>> top_k
tensor([1, 2])
```

---

**Navigation**

- Parent: [Retrieval](/docs/torchmetrics/1.9.0/retrieval.md)