torcheval.metrics.functional.retrieval_recall

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

Retrieval Recall is a metric that measures the proportion of relevant items retrieved out of the all relevant items.

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

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

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_recall calculation.
• value – 1): Number of tasks that need retrieval_recall calculation.

Returns:

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

Return type:

(Tensor)

Examples

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

>>> input = torch.Tensor([0.2, 0.3, 0.5, 0.1, 0.3, 0.5, 0.2])
>>> target = torch.Ttensor([0, 0, 1, 1, 1, 0, 1])
>>> retrieval_recall(input, target)
torch.Tensor(1.0)
>>> retrieval_recall(input, target, k=2)
torch.Tensor(0.25)

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_recall_compute are Tensors with dimension 0 or > 2.