document exceptions for metrics/functional (PL^6273)

* document exceptions for metrics/functional

* Apply suggestions from code review

Co-authored-by: Rohit Gupta <rohitgr1998@gmail.com>

* Apply suggestions from code review

Co-authored-by: Jirka Borovec <Borda@users.noreply.github.com>
Co-authored-by: Rohit Gupta <rohitgr1998@gmail.com>
Co-authored-by: Akihiro Nitta <nitta@akihironitta.com>

torchmetrics/functional/classification/accuracy.py

@@ -109,6 +109,10 @@ def accuracy(
               ``preds = preds.flatten()`` and same for ``target``). Note that the ``top_k`` parameter
               still applies in both cases, if set.
 
+    Raises:
+        ValueError:
+            If ``top_k`` parameter is set for ``multi-label`` inputs.
+
     Example:
         >>> from torchmetrics.functional import accuracy
         >>> target = torch.tensor([0, 1, 2, 3])

torchmetrics/functional/classification/auc.py

@@ -64,6 +64,14 @@ def auc(x: Tensor, y: Tensor, reorder: bool = False) -> Tensor:
     Return:
         Tensor containing AUC score (float)
 
+    Raises:
+        ValueError:
+            If both ``x`` and ``y`` tensors are not ``1d``.
+        ValueError:
+            If both ``x`` and ``y`` don't have the same numnber of elements.
+        ValueError:
+            If ``x`` tesnsor is neither increasing or decreasing.
+
     Example:
         >>> from torchmetrics.functional import auc
         >>> x = torch.tensor([0, 1, 2, 3])

torchmetrics/functional/classification/auroc.py

@@ -159,6 +159,18 @@ def auroc(
             range [0, max_fpr]. Should be a float between 0 and 1.
         sample_weights: sample weights for each data point
 
+    Raises:
+        ValueError:
+            If ``max_fpr`` is not a ``float`` in the range ``(0, 1]``.
+        RuntimeError:
+            If ``PyTorch version`` is ``below 1.6`` since max_fpr requires `torch.bucketize`
+            which is not available below 1.6.
+        ValueError:
+            If ``max_fpr`` is not set to ``None`` and the mode is ``not binary``
+            since partial AUC computation is not available in multilabel/multiclass.
+        ValueError:
+            If ``average`` is none of ``None``, ``"macro"`` or ``"weighted"``.
+
     Example:
         >>> # binary case
         >>> from torchmetrics.functional import auroc

torchmetrics/functional/classification/precision_recall.py

@@ -130,6 +130,18 @@ def precision(
         - If ``average in ['none', None]``, the shape will be ``(C,)``, where ``C`` stands  for the number
           of classes
 
+    Raises:
+        ValueError:
+            If ``average`` is not one of ``"micro"``, ``"macro"``, ``"weighted"``,
+            ``"samples"``, ``"none"`` or ``None``.
+        ValueError:
+            If ``mdmc_average`` is not one of ``None``, ``"samplewise"``, ``"global"``.
+        ValueError:
+            If ``average`` is set but ``num_classes`` is not provided.
+        ValueError:
+            If ``num_classes`` is set
+            and ``ignore_index`` is not in the range ``[0, num_classes)``.
+
     Example:
         >>> from torchmetrics.functional import precision
         >>> preds  = torch.tensor([2, 0, 2, 1])
@@ -281,6 +293,18 @@ def recall(
         - If ``average in ['none', None]``, the shape will be ``(C,)``, where ``C`` stands  for the number
           of classes
 
+    Raises:
+        ValueError:
+            If ``average`` is not one of ``"micro"``, ``"macro"``, ``"weighted"``,
+            ``"samples"``, ``"none"`` or ``None``.
+        ValueError:
+            If ``mdmc_average`` is not one of ``None``, ``"samplewise"``, ``"global"``.
+        ValueError:
+            If ``average`` is set but ``num_classes`` is not provided.
+        ValueError:
+            If ``num_classes`` is set
+            and ``ignore_index`` is not in the range ``[0, num_classes)``.
+
     Example:
         >>> from torchmetrics.functional import recall
         >>> preds  = torch.tensor([2, 0, 2, 1])
@@ -417,6 +441,18 @@ def precision_recall(
         - If ``average in ['none', None]``, they are a tensor of shape ``(C, )``, where ``C`` stands for
           the number of classes
 
+    Raises:
+        ValueError:
+            If ``average`` is not one of ``"micro"``, ``"macro"``, ``"weighted"``,
+            ``"samples"``, ``"none"`` or ``None``.
+        ValueError:
+            If ``mdmc_average`` is not one of ``None``, ``"samplewise"``, ``"global"``.
+        ValueError:
+            If ``average`` is set but ``num_classes`` is not provided.
+        ValueError:
+            If ``num_classes`` is set
+            and ``ignore_index`` is not in the range ``[0, num_classes)``.
+
     Example:
         >>> from torchmetrics.functional import precision_recall
         >>> preds  = torch.tensor([2, 0, 2, 1])

torchmetrics/functional/classification/precision_recall_curve.py

@@ -183,6 +183,14 @@ def precision_recall_curve(
         thresholds:
             Thresholds used for computing precision/recall scores
 
+    Raises:
+        ValueError:
+            If ``preds`` and ``target`` don't have the same number of dimensions,
+            or one additional dimension for ``preds``.
+        ValueError:
+            If the number of classes deduced from ``preds`` is not the same as the
+            ``num_classes`` provided.
+
     Example:
         >>> # binary case
         >>> from torchmetrics.functional import precision_recall_curve

torchmetrics/functional/classification/stat_scores.py

@@ -245,6 +245,21 @@ def stat_scores(
           - If ``reduce='macro'``, the shape will be ``(N, C, 5)``
           - If ``reduce='samples'``, the shape will be ``(N, X, 5)``
 
+    Raises:
+        ValueError:
+            If ``reduce`` is none of ``"micro"``, ``"macro"`` or ``"samples"``.
+        ValueError:
+            If ``mdmc_reduce`` is none of ``None``, ``"samplewise"``, ``"global"``.
+        ValueError:
+            If ``reduce`` is set to ``"macro"`` and ``num_classes`` is not provided.
+        ValueError:
+            If ``num_classes`` is set
+            and ``ignore_index`` is not in the range ``[0, num_classes)``.
+        ValueError:
+            If ``ignore_index`` is used with ``binary data``.
+        ValueError:
+            If inputs are ``multi-dimensional multi-class`` and ``mdmc_reduce`` is not provided.
+
     Example:
         >>> from torchmetrics.functional import stat_scores
         >>> preds  = torch.tensor([1, 0, 2, 1])

torchmetrics/functional/image_gradients.py

@@ -55,6 +55,12 @@ def image_gradients(img: Tensor) -> Tuple[Tensor, Tensor]:
     Return:
         Tuple of (dy, dx) with each gradient of shape ``[N, C, H, W]``
 
+    Raises:
+        TypeError:
+            If ``img`` is not of the type <torch.Tensor>.
+        RuntimeError:
+            If ``img`` is not a 4D tensor.
+
     Example:
         >>> from torchmetrics.functional import image_gradients
         >>> image = torch.arange(0, 1*1*5*5, dtype=torch.float32)

torchmetrics/functional/regression/psnr.py

@@ -86,6 +86,10 @@ def psnr(
     Return:
         Tensor with PSNR score
 
+    Raises:
+        ValueError:
+            If ``dim`` is not ``None`` and ``data_range`` is not provided.
+
     Example:
         >>> from torchmetrics.functional import psnr
         >>> pred = torch.tensor([[0.0, 1.0], [2.0, 3.0]])

torchmetrics/functional/regression/r2score.py

@@ -112,6 +112,18 @@ def r2score(
             * ``'uniform_average'`` scores are uniformly averaged
             * ``'variance_weighted'`` scores are weighted by their individual variances
 
+    Raises:
+        ValueError:
+            If both ``preds`` and ``targets`` are not ``1D`` or ``2D`` tensors.
+        ValueError:
+            If ``len(preds)`` is less than ``2``
+            since at least ``2`` sampels are needed to calculate r2 score.
+        ValueError:
+            If ``multioutput`` is not one of ``raw_values``,
+            ``uniform_average`` or ``variance_weighted``.
+        ValueError:
+            If ``adjusted`` is not an ``integer`` greater than ``0``.
+
     Example:
         >>> from torchmetrics.functional import r2score
         >>> target = torch.tensor([3, -0.5, 2, 7])

torchmetrics/functional/regression/ssim.py

@@ -142,6 +142,18 @@ def ssim(
     Return:
         Tensor with SSIM score
 
+    Raises:
+        TypeError:
+            If ``preds`` and ``target`` don't have the same data type.
+        ValueError:
+            If ``preds`` and ``target`` don't have ``BxCxHxW shape``.
+        ValueError:
+            If the length of ``kernel_size`` or ``sigma`` is not ``2``.
+        ValueError:
+            If one of the elements of ``kernel_size`` is not an ``odd positive number``.
+        ValueError:
+            If one of the elements of ``sigma`` is not a ``positive number``.
+
     Example:
         >>> from torchmetrics.functional import ssim
         >>> preds = torch.rand([16, 1, 16, 16])