torcheval.metrics.functional.retrieval_precision

torcheval.metrics.functional.retrieval_precision(input: Tensor, target: Tensor, k: Optional[int] = None, limit_k_to_size: bool = False, num_tasks: int = 1) → Tensor

Retrieval Precision is a metric that measures the proportion of relevant items retrieved out of the total items retrieved by an information retrieval system.

It is defined as: Retrieval Precision = (Number of Relevant Items Retrieved) / (Total Number of Items Retrieved) This metric is also known as Precision at k, where k is the number of elements considered as being retrieved.

Its class version is torcheval.metrics.ranking.RetrievalPrecision.

Parameters:

• input (Tensor) – Predicted scores for each document (the higher the more relevant), with shape (num_sample,) or (num_tasks, num_samples).
• target (Tensor) – 0 and 1 valued Tensor of ground truth identifying relevant element, with shape (num_sample,) or (num_tasks, num_samples).
• k (int, optional) – the number of elements considered as being retrieved. Only the top (sorted in decreasing order) k elements of input are considered. if k is None, all the input elements are considered.
• (bool (limit_k_to_size) – False): When set to True, limits k to be at most the length of input, i.e. replaces k by k=min(k, len(input)). This parameter can only be set to True if k is not None.
• value (default) – False): When set to True, limits k to be at most the length of input, i.e. replaces k by k=min(k, len(input)). This parameter can only be set to True if k is not None.
• (int (num_tasks) – 1): Number of tasks that need retrieval_precision calculation.
• value – 1): Number of tasks that need retrieval_precision calculation.

Returns:

• If input and target are 1D: returns a tensor of dimension 0, containing the retrieval precision value.
• When input and target are 2D with shape (num_tasks, num_samples): returns a tensor of shape (num_tasks,) containing the retrieval precision, computed row by row.

Return type:

(Tensor)

Examples (one dimension):

>>> import torch
>>> from torcheval.metrics.functional.ranking import retrieval_precision

>>> input = tensor([0.2, 0.3, 0.5, 0.1, 0.3, 0.5, 0.2])
>>> target = tensor([0, 0, 1, 1, 1, 0, 1])
>>> retrieval_precision(input, target)
tensor(0.571)
>>> retrieval_precision(input, target, k=2)
tensor(0.5)
>>> retrieval_precision(input, target, k=4)
tensor(0.5)
>>> retrieval_precision(input, target, k=10)
tensor(0.400)
>>> retrieval_precision(input, target, k=10, limit_k_to_size=True)
tensor(0.571)

Examples (two dimensions):

>>> import torch
>>> from torcheval.metrics.functional.ranking import retrieval_precision

>>> input = tensor([[0.1, 0.2, 0.3], [0.1, 0.2, 0.3]])
>>> target = tensor([[0, 0, 1], [1, 0, 0]])
>>> retrieval_precision(input, target, k=2)
tensor([0.5000, 0.0000])

Raises:

• ValueError – if limit_k_to_size is True and k is None.
• ValueError – if k is not a positive integer.
• ValueError – if input or target arguments of self._retrieval_precision_compute are Tensors with dimension 0 or > 2.