Merge branch 'master' into feature/clip_warning

.github/workflows/ci-rtfd.yml

@@ -0,0 +1,16 @@
+name: RTFD Preview
+on:
+  pull_request_target:
+    types:
+      - opened
+
+permissions:
+  pull-requests: write
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "torchmetrics"

.github/workflows/docs-build.yml

@@ -21,6 +21,7 @@ env:
   PYPI_CACHE: "_ci-cache_PyPI"
   PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION: 'python'
   TOKENIZERS_PARALLELISM: false
+  SPHINX_FETCH_ASSETS: 1  # todo: consider not downloading on PRs
 
 jobs:
   docs-check:

docs/source/conf.py

@@ -264,9 +264,11 @@ def _set_root_image_path(page_path: str):
     "python": ("https://docs.python.org/3", None),
     "torch": ("https://pytorch.org/docs/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
+    "matplotlib": ("http://matplotlib.org/stable", None),
 }
+nitpicky = True
 
-# -- Options for todo extension ----------------------------------------------
+# -- Options for to-do extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True

docs/source/image/perceptual_path_length.rst

@@ -15,6 +15,8 @@ ________________
 .. autoclass:: torchmetrics.image.perceptual_path_length.PerceptualPathLength
     :exclude-members: update, compute
 
+.. autoclass:: torchmetrics.image.perceptual_path_length.GeneratorType
+
 Functional Interface
 ____________________
 

docs/source/links.rst

@@ -105,7 +105,7 @@
 .. _Pearson's Contingency Coefficient: https://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/pearcont.htm
 .. _CLIP score: https://arxiv.org/pdf/2104.08718.pdf
 .. _Huggingface OpenAI: https://huggingface.co/openai
-.. _Theil's U: https://en.wikipedia.org/wiki/Uncertainty_coefficient
+.. _Theils Uncertainty coefficient: https://en.wikipedia.org/wiki/Uncertainty_coefficient
 .. _Perceptual Evaluation of Speech Quality: https://en.wikipedia.org/wiki/Perceptual_Evaluation_of_Speech_Quality
 .. _pesq package: https://github.com/ludlows/python-pesq
 .. _Cees Taal's website: http://www.ceestaal.nl/code/

docs/source/pages/lightning.rst

@@ -51,10 +51,12 @@ The example below shows how to use a metric in your `LightningModule <https://py
 
 Metric logging in Lightning happens through the ``self.log`` or ``self.log_dict`` method. Both methods only support the
 logging of *scalar-tensors*. While the vast majority of metrics in torchmetrics returns a scalar tensor, some metrics
-such as :class:`~torchmetrics.ConfusionMatrix`, :class:`~torchmetrics.ROC`, :class:`~torchmetrics.MeanAveragePrecision`,
-:class:`~torchmetrics.ROUGEScore` return outputs that are non-scalar tensors (often dicts or list of tensors) and should
-therefore be dealt with separately. For info about the return type and shape please look at the documentation for the
-``compute`` method for each metric you want to log.
+such as :class:`~torchmetrics.classification.confusion_matrix.ConfusionMatrix`,
+:class:`~torchmetrics.classification.roc.ROC`,
+:class:`~torchmetrics.detection.mean_ap.MeanAveragePrecision`, :class:`~torchmetrics.text.rouge.ROUGEScore` return
+outputs that are non-scalar tensors (often dicts or list of tensors) and should therefore be dealt with separately.
+For info about the return type and shape please look at the documentation for the ``compute`` method for each metric
+you want to log.
 
 ********************
 Logging TorchMetrics

docs/source/pages/overview.rst

@@ -96,8 +96,8 @@ be moved to the same device as the input of the metric:
     print(out.device) # cuda:0
 
 However, when **properly defined** inside a :class:`~torch.nn.Module` or
-:class:`~lightning.LightningModule` the metric will be automatically moved
-to the same device as the module when using ``.to(device)``.  Being
+`LightningModule <https://pytorch-lightning.readthedocs.io/en/stable/common/lightning_module.html>`_ the metric will
+be automatically moved to the same device as the module when using ``.to(device)``.  Being
 **properly defined** means that the metric is correctly identified as a child module of the
 model (check ``.children()`` attribute of the model). Therefore, metrics cannot be placed
 in native python ``list`` and ``dict``, as they will not be correctly identified

docs/source/references/utilities.rst

@@ -19,3 +19,17 @@ to_onehot
 ~~~~~~~~~
 
 .. autofunction:: torchmetrics.utilities.data.to_onehot
+
+#################################
+torchmetrics.utilities.exceptions
+#################################
+
+TorchMetricsUserError
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: torchmetrics.utilities.exceptions.TorchMetricsUserError
+
+TorchMetricsUserWarning
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: torchmetrics.utilities.exceptions.TorchMetricsUserWarning

src/torchmetrics/classification/accuracy.py

@@ -456,8 +456,9 @@ class Accuracy(_ClassificationTaskWrapper):
 
     This module 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
-    :mod:`BinaryAccuracy`, :mod:`MulticlassAccuracy` and :mod:`MultilabelAccuracy` for the specific details of
-    each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryAccuracy`, :class:`~torchmetrics.classification.MulticlassAccuracy` and
+    :class:`~torchmetrics.classification.MultilabelAccuracy` for the specific details of each argument influence and
+    examples.
 
     Legacy Example:
         >>> from torch import tensor

src/torchmetrics/classification/auroc.py

@@ -470,8 +470,9 @@ class AUROC(_ClassificationTaskWrapper):
 
     This module 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
-    :mod:`BinaryAUROC`, :mod:`MulticlassAUROC` and :mod:`MultilabelAUROC` for the specific details of
-    each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryAUROC`, :class:`~torchmetrics.classification.MulticlassAUROC` and
+    :class:`~torchmetrics.classification.MultilabelAUROC` for the specific details of each argument influence and
+    examples.
 
     Legacy Example:
         >>> from torch import tensor

src/torchmetrics/classification/average_precision.py

@@ -480,8 +480,10 @@ class AveragePrecision(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryAveragePrecision`, :mod:`MulticlassAveragePrecision` and :mod:`MultilabelAveragePrecision`
-    for the specific details of each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryAveragePrecision`,
+    :class:`~torchmetrics.classification.MulticlassAveragePrecision` and
+    :class:`~torchmetrics.classification.MultilabelAveragePrecision` for the specific details of each argument
+    influence and examples.
 
     Legacy Example:
         >>> from torch import tensor

src/torchmetrics/classification/calibration_error.py

@@ -361,8 +361,9 @@ class CalibrationError(_ClassificationTaskWrapper):
 
     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'`` or ``'multiclass'``. See the documentation of
-    :mod:`BinaryCalibrationError` and :mod:`MulticlassCalibrationError` for the specific details of
-    each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryCalibrationError` and
+    :class:`~torchmetrics.classification.MulticlassCalibrationError` for the specific details of each argument influence
+    and examples.
 
     """
 

src/torchmetrics/classification/cohen_kappa.py

@@ -297,8 +297,9 @@ class labels.
 
     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'`` or ``'multiclass'``. See the documentation of
-    :mod:`BinaryCohenKappa` and :mod:`MulticlassCohenKappa` for the specific details of
-    each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryCohenKappa` and
+    :class:`~torchmetrics.classification.MulticlassCohenKappa` for the specific details of each argument influence and
+    examples.
 
     Legacy Example:
         >>> from torch import tensor

src/torchmetrics/classification/confusion_matrix.py

@@ -472,8 +472,10 @@ class ConfusionMatrix(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryConfusionMatrix`, :mod:`MulticlassConfusionMatrix` and :func:`MultilabelConfusionMatrix` for
-    the specific details of each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryConfusionMatrix`,
+    :class:`~torchmetrics.classification.MulticlassConfusionMatrix` and
+    :class:`~torchmetrics.classification.MultilabelConfusionMatrix` for the specific details of each argument influence
+    and examples.
 
     Legacy Example:
         >>> from torch import tensor

src/torchmetrics/classification/exact_match.py

@@ -368,8 +368,9 @@ class ExactMatch(_ClassificationTaskWrapper):
 
     This module is a simple wrapper to get the task specific versions of this metric, which is done by setting the
     ``task`` argument to either ``'multiclass'`` or ``multilabel``. See the documentation of
-    :mod:`MulticlassExactMatch` and :mod:`MultilabelExactMatch` for the specific details of
-    each argument influence and examples.
+    :class:`~torchmetrics.classification.MulticlassExactMatch` and
+    :class:`~torchmetrics.classification.MultilabelExactMatch` for the specific details of each argument influence and
+    examples.
 
     Legacy Example:
         >>> from torch import tensor

src/torchmetrics/classification/f_beta.py

@@ -1021,8 +1021,10 @@ class FBetaScore(_ClassificationTaskWrapper):
 
     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
-    :func:`binary_fbeta_score`, :func:`multiclass_fbeta_score` and :func:`multilabel_fbeta_score` for the specific
-    details of each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryFBetaScore`,
+    :class:`~torchmetrics.classification.MulticlassFBetaScore` and
+    :class:`~torchmetrics.classification.MultilabelFBetaScore` for the specific details of each argument influence
+    and examples.
 
     Legcy Example:
         >>> from torch import tensor
@@ -1082,8 +1084,9 @@ class F1Score(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryF1Score`, :mod:`MulticlassF1Score` and :mod:`MultilabelF1Score` for the specific
-    details of each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryF1Score`, :class:`~torchmetrics.classification.MulticlassF1Score` and
+    :class:`~torchmetrics.classification.MultilabelF1Score` for the specific details of each argument influence and
+    examples.
 
     Legacy Example:
         >>> from torch import tensor

src/torchmetrics/classification/hamming.py

@@ -470,8 +470,10 @@ class HammingDistance(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryHammingDistance`, :mod:`MulticlassHammingDistance` and :mod:`MultilabelHammingDistance` for the
-    specific details of each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryHammingDistance`,
+    :class:`~torchmetrics.classification.MulticlassHammingDistance` and
+    :class:`~torchmetrics.classification.MultilabelHammingDistance` for the specific details of each argument influence
+    and examples.
 
     Legacy Example:
         >>> from torch import tensor

src/torchmetrics/classification/hinge.py

@@ -325,8 +325,8 @@ class HingeLoss(_ClassificationTaskWrapper):
 
     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'`` or ``'multiclass'``. See the documentation of
-    :mod:`BinaryHingeLoss` and :mod:`MulticlassHingeLoss` for the specific details of
-    each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryHingeLoss` and :class:`~torchmetrics.classification.MulticlassHingeLoss`
+    for the specific details of each argument influence and examples.
 
     Legacy Example:
         >>> from torch import tensor

src/torchmetrics/classification/jaccard.py

@@ -425,8 +425,10 @@ class JaccardIndex(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryJaccardIndex`, :mod:`MulticlassJaccardIndex` and :mod:`MultilabelJaccardIndex` for
-    the specific details of each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryJaccardIndex`,
+    :class:`~torchmetrics.classification.MulticlassJaccardIndex` and
+    :class:`~torchmetrics.classification.MultilabelJaccardIndex` for the specific details of each argument influence
+    and examples.
 
     Legacy Example:
         >>> from torch import randint, tensor

src/torchmetrics/classification/matthews_corrcoef.py

@@ -374,8 +374,10 @@ class MatthewsCorrCoef(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryMatthewsCorrCoef`, :mod:`MulticlassMatthewsCorrCoef` and :mod:`MultilabelMatthewsCorrCoef` for
-    the specific details of each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryMatthewsCorrCoef`,
+    :class:`~torchmetrics.classification.MulticlassMatthewsCorrCoef` and
+    :class:`~torchmetrics.classification.MultilabelMatthewsCorrCoef` for the specific details of each argument influence
+    and examples.
 
     Legacy Example:
         >>> from torch import tensor

src/torchmetrics/classification/precision_fixed_recall.py

@@ -474,8 +474,10 @@ class PrecisionAtFixedRecall(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryPrecisionAtFixedRecall`, :func:`MulticlassPrecisionAtFixedRecall` and
-    :func:`MultilabelPrecisionAtFixedRecall` for the specific details of each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryPrecisionAtFixedRecall`,
+    :class:`~torchmetrics.classification.MulticlassPrecisionAtFixedRecall` and
+    :class:`~torchmetrics.classification.MultilabelPrecisionAtFixedRecall` for the specific details of each argument
+    influence and examples.
 
     """
 

src/torchmetrics/classification/precision_recall.py

@@ -889,8 +889,9 @@ class Precision(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryPrecision`, :func:`MulticlassPrecision` and :func:`MultilabelPrecision` for the specific details of
-    each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryPrecision`, :class:`~torchmetrics.classification.MulticlassPrecision` and
+    :class:`~torchmetrics.classification.MultilabelPrecision` for the specific details of each argument influence and
+    examples.
 
     Legacy Example:
         >>> from torch import tensor
@@ -951,8 +952,9 @@ class Recall(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryRecall`, :mod:`MulticlassRecall` and :mod:`MultilabelRecall` for the specific details of
-    each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryRecall`,
+    :class:`~torchmetrics.classification.MulticlassRecall` and :class:`~torchmetrics.classification.MultilabelRecall`
+    for the specific details of each argument influence and examples.
 
     Legacy Example:
         >>> from torch import tensor

src/torchmetrics/classification/precision_recall_curve.py

@@ -593,8 +593,10 @@ class PrecisionRecallCurve(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryPrecisionRecallCurve`, :mod:`MulticlassPrecisionRecallCurve` and
-    :mod:`MultilabelPrecisionRecallCurve` for the specific details of each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryPrecisionRecallCurve`,
+    :class:`~torchmetrics.classification.MulticlassPrecisionRecallCurve` and
+    :class:`~torchmetrics.classification.MultilabelPrecisionRecallCurve` for the specific details of each argument
+    influence and examples.
 
     Legacy Example:
         >>> pred = torch.tensor([0, 0.1, 0.8, 0.4])

src/torchmetrics/classification/recall_fixed_precision.py

@@ -469,8 +469,10 @@ class RecallAtFixedPrecision(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryRecallAtFixedPrecision`, :func:`MulticlassRecallAtFixedPrecision` and
-    :func:`MultilabelRecallAtFixedPrecision` for the specific details of each argument influence and examples.
+    :class:`~torchmetrics.classification.BinaryRecallAtFixedPrecision`,
+    :class:`~torchmetrics.classification.MulticlassRecallAtFixedPrecision` and
+    :class:`~torchmetrics.classification.MultilabelRecallAtFixedPrecision` for the specific details of each argument
+    influence and examples.
 
     """
 

src/torchmetrics/classification/roc.py

@@ -484,7 +484,9 @@ class ROC(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinaryROC`, :mod:`MulticlassROC` and :mod:`MultilabelROC` for the specific details of each argument
+    :class:`~torchmetrics.classification.BinaryROC`,
+    :class:`~torchmetrics.classification.MulticlassROC` and
+    :class:`~torchmetrics.classification.MultilabelROC` for the specific details of each argument
     influence and examples.
 
     Legacy Example:

src/torchmetrics/classification/specificity.py

@@ -448,8 +448,9 @@ class Specificity(_ClassificationTaskWrapper):
 
     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
-    :mod:`BinarySpecificity`, :mod:`MulticlassSpecificity` and :mod:`MultilabelSpecificity` for the specific
-    details of each argument influence and examples.
+    :class:`~torchmetrics.classification.BinarySpecificity`, :class:`~torchmetrics.classification.MulticlassSpecificity`
+    and :class:`~torchmetrics.classification.MultilabelSpecificity` for the specific details of each argument influence
+    and examples.
 
     Legacy Example:
         >>> from torch import tensor