diff --git a/docs/source/links.rst b/docs/source/links.rst index e39f37bb7ea..5a199b4d4c2 100644 --- a/docs/source/links.rst +++ b/docs/source/links.rst @@ -142,3 +142,7 @@ .. _Equal opportunity: https://proceedings.neurips.cc/paper/2016/hash/9d2682367c3935defcb1f9e247a97c0d-Abstract.html .. _Seamless Scene Segmentation paper: https://arxiv.org/abs/1905.01220 .. _Fleiss kappa: https://en.wikipedia.org/wiki/Fleiss%27_kappa +.. _CIOU: https://arxiv.org/abs/2005.03572 +.. _DIOU: https://arxiv.org/abs/1911.08287v1 +.. _GIOU: https://arxiv.org/abs/1902.09630 +.. _pycocotools: https://github.com/cocodataset/cocoapi/tree/master/PythonAPI/pycocotools diff --git a/src/torchmetrics/aggregation.py b/src/torchmetrics/aggregation.py index d15325fedbe..5042a2f3877 100644 --- a/src/torchmetrics/aggregation.py +++ b/src/torchmetrics/aggregation.py @@ -657,7 +657,7 @@ def __init__( class RunningSum(Running): """Aggregate a stream of value into their sum over a running window. - Using this metric compared to `MeanMetric` allows for calculating metrics over a running window of values, instead + Using this metric compared to `SumMetric` allows for calculating metrics over a running window of values, instead of the whole history of values. This is beneficial when you want to get a better estimate of the metric during training and don't want to wait for the whole training to finish to get epoch level estimates. diff --git a/src/torchmetrics/audio/sdr.py b/src/torchmetrics/audio/sdr.py index c2bf6d00bb9..23026ca177b 100644 --- a/src/torchmetrics/audio/sdr.py +++ b/src/torchmetrics/audio/sdr.py @@ -168,11 +168,11 @@ class ScaleInvariantSignalDistortionRatio(Metric): As input to `forward` and `update` the metric accepts the following input - ``preds`` (:class:`~torch.Tensor`): float tensor with shape ``(...,time)`` - - ``target`` (: :class:`~torch.Tensor`): float tensor with shape ``(...,time)`` + - ``target`` (:class:`~torch.Tensor`): float tensor with shape ``(...,time)`` As output of `forward` and `compute` the metric returns the following output - - ``si_sdr`` (: :class:`~torch.Tensor`): float scalar tensor with average SI-SDR value over samples + - ``si_sdr`` (:class:`~torch.Tensor`): float scalar tensor with average SI-SDR value over samples Args: zero_mean: if to zero mean target and preds or not diff --git a/src/torchmetrics/audio/snr.py b/src/torchmetrics/audio/snr.py index 8954914ebf9..b1ed39d3055 100644 --- a/src/torchmetrics/audio/snr.py +++ b/src/torchmetrics/audio/snr.py @@ -145,11 +145,11 @@ class ScaleInvariantSignalNoiseRatio(Metric): As input to `forward` and `update` the metric accepts the following input - ``preds`` (:class:`~torch.Tensor`): float tensor with shape ``(...,time)`` - - ``target`` (: :class:`~torch.Tensor`): float tensor with shape ``(...,time)`` + - ``target`` (:class:`~torch.Tensor`): float tensor with shape ``(...,time)`` As output of `forward` and `compute` the metric returns the following output - - ``si_snr`` (: :class:`~torch.Tensor`): float scalar tensor with average SI-SNR value over samples + - ``si_snr`` (:class:`~torch.Tensor`): float scalar tensor with average SI-SNR value over samples Args: kwargs: Additional keyword arguments, see :ref:`Metric kwargs` for more info. @@ -241,15 +241,15 @@ class ComplexScaleInvariantSignalNoiseRatio(Metric): As input to `forward` and `update` the metric accepts the following input - - ``preds`` (:class:`~torch.Tensor`): real/complex float tensor with shape ``(..., frequency, time, 2)``\ - / ``(..., frequency, time)`` + - ``preds`` (:class:`~torch.Tensor`): real float tensor with shape ``(...,frequency,time,2)`` or complex float + tensor with shape ``(..., frequency,time)`` - - ``target`` (: :class:`~torch.Tensor`): real/complex float tensor with shape ``(..., frequency, time, 2)``\ - / ``(..., frequency, time)`` + - ``target`` (:class:`~torch.Tensor`): real float tensor with shape ``(...,frequency,time,2)`` or complex float + tensor with shape ``(..., frequency,time)`` As output of `forward` and `compute` the metric returns the following output - - ``c_si_snr`` (: :class:`~torch.Tensor`): float scalar tensor with average C-SI-SNR value over samples + - ``c_si_snr`` (:class:`~torch.Tensor`): float scalar tensor with average C-SI-SNR value over samples Args: zero_mean: if to zero mean target and preds or not diff --git a/src/torchmetrics/detection/_mean_ap.py b/src/torchmetrics/detection/_mean_ap.py index 31ad5d6af06..b24a6ba8eaf 100644 --- a/src/torchmetrics/detection/_mean_ap.py +++ b/src/torchmetrics/detection/_mean_ap.py @@ -210,9 +210,8 @@ class MeanAveragePrecision(Metric): The default properties are also accessible via fields and will raise an ``AttributeError`` if not available. .. note:: - This metric is following the mAP implementation of - `pycocotools `_, - a standard implementation for the mAP metric for object detection. + This metric is following the mAP implementation of `pycocotools`_ a standard implementation for the mAP metric + for object detection. .. note:: This metric requires you to have `torchvision` version 0.8.0 or newer installed diff --git a/src/torchmetrics/detection/ciou.py b/src/torchmetrics/detection/ciou.py index f967a449b8c..8197fa2e5b1 100644 --- a/src/torchmetrics/detection/ciou.py +++ b/src/torchmetrics/detection/ciou.py @@ -27,7 +27,7 @@ class CompleteIntersectionOverUnion(IntersectionOverUnion): - r"""Computes Complete Intersection Over Union (CIoU) `_. + r"""Computes Complete Intersection Over Union (`CIoU`_). As input to ``forward`` and ``update`` the metric accepts the following input: @@ -55,7 +55,7 @@ class CompleteIntersectionOverUnion(IntersectionOverUnion): - ``ciou_dict``: A dictionary containing the following key-values: - ciou: (:class:`~torch.Tensor`) - - ciou/cl_{cl}: (:class:`~torch.Tensor`), if argument ``class metrics=True`` + - ciou/cl_{cl}: (:class:`~torch.Tensor`), if argument ``class_metrics=True`` Args: box_format: diff --git a/src/torchmetrics/detection/diou.py b/src/torchmetrics/detection/diou.py index f30ef869ec2..65724cf8a41 100644 --- a/src/torchmetrics/detection/diou.py +++ b/src/torchmetrics/detection/diou.py @@ -27,7 +27,7 @@ class DistanceIntersectionOverUnion(IntersectionOverUnion): - r"""Computes Distance Intersection Over Union (DIoU) `_. + r"""Computes Distance Intersection Over Union (`DIoU`_). As input to ``forward`` and ``update`` the metric accepts the following input: @@ -55,7 +55,7 @@ class DistanceIntersectionOverUnion(IntersectionOverUnion): - ``diou_dict``: A dictionary containing the following key-values: - diou: (:class:`~torch.Tensor`) - - diou/cl_{cl}: (:class:`~torch.Tensor`), if argument ``class metrics=True`` + - diou/cl_{cl}: (:class:`~torch.Tensor`), if argument ``class_metrics=True`` Args: box_format: diff --git a/src/torchmetrics/detection/giou.py b/src/torchmetrics/detection/giou.py index e06660ea751..8d3393b9f89 100644 --- a/src/torchmetrics/detection/giou.py +++ b/src/torchmetrics/detection/giou.py @@ -27,7 +27,7 @@ class GeneralizedIntersectionOverUnion(IntersectionOverUnion): - r"""Compute Generalized Intersection Over Union (GIoU) `_. + r"""Compute Generalized Intersection Over Union (`GIoU`_). As input to ``forward`` and ``update`` the metric accepts the following input: @@ -90,6 +90,7 @@ class GeneralizedIntersectionOverUnion(IntersectionOverUnion): Raises: ModuleNotFoundError: If torchvision is not installed with version 0.8.0 or newer. + """ _iou_type: str = "giou" _invalid_val: float = -1.0 diff --git a/src/torchmetrics/detection/panoptic_qualities.py b/src/torchmetrics/detection/panoptic_qualities.py index a913826af6b..0dde6eb9537 100644 --- a/src/torchmetrics/detection/panoptic_qualities.py +++ b/src/torchmetrics/detection/panoptic_qualities.py @@ -36,12 +36,12 @@ class PanopticQuality(Metric): r"""Compute the `Panoptic Quality`_ for panoptic segmentations. - .. math:: - PQ = \frac{IOU}{TP + 0.5 FP + 0.5 FN} + .. math:: + PQ = \frac{IOU}{TP + 0.5 FP + 0.5 FN} - where IOU, TP, FP and FN are respectively the sum of the intersection over union for true positives, - the number of true postitives, false positives and false negatives. This metric is inspired by the PQ - implementation of panopticapi, a standard implementation for the PQ metric for panoptic segmentation. + where IOU, TP, FP and FN are respectively the sum of the intersection over union for true positives, + the number of true postitives, false positives and false negatives. This metric is inspired by the PQ + implementation of panopticapi, a standard implementation for the PQ metric for panoptic segmentation. .. note: Points in the target tensor that do not map to a known category ID are automatically ignored in the metric @@ -224,8 +224,8 @@ class ModifiedPanopticQuality(Metric): .. math:: PQ^{\dagger}_c = \frac{IOU_c}{|S_c|} - where IOU_c is the sum of the intersection over union of all matching segments for a given class, and \|S_c| is - the overall number of segments in the ground truth for that class. + where :math:`IOU_c` is the sum of the intersection over union of all matching segments for a given class, and + :math:`|S_c|` is the overall number of segments in the ground truth for that class. .. note: Points in the target tensor that do not map to a known category ID are automatically ignored in the metric diff --git a/src/torchmetrics/functional/audio/snr.py b/src/torchmetrics/functional/audio/snr.py index 08c2880aecc..db15c0a8b3f 100644 --- a/src/torchmetrics/functional/audio/snr.py +++ b/src/torchmetrics/functional/audio/snr.py @@ -89,8 +89,10 @@ def complex_scale_invariant_signal_noise_ratio(preds: Tensor, target: Tensor, ze """`Complex scale-invariant signal-to-noise ratio`_ (C-SI-SNR). Args: - preds: real/complex float tensor with shape ``(..., frequency, time, 2)``/``(..., frequency, time)`` - target: real/complex float tensor with shape ``(..., frequency, time, 2)``/``(..., frequency, time)`` + preds: real float tensor with shape ``(...,frequency,time,2)`` or complex float tensor with + shape ``(..., frequency,time)`` + target: real float tensor with shape ``(...,frequency,time,2)`` or complex float tensor with + shape ``(..., frequency,time)`` zero_mean: When set to True, the mean of all signals is subtracted prior to computation of the metrics Returns: @@ -98,7 +100,7 @@ def complex_scale_invariant_signal_noise_ratio(preds: Tensor, target: Tensor, ze Raises: RuntimeError: - If ``preds`` is not the shape (..., frequency, time, 2) (after being converted to real if it is complex). + If ``preds`` is not the shape (...,frequency,time,2) (after being converted to real if it is complex). If ``preds`` and ``target`` does not have the same shape. Example: diff --git a/src/torchmetrics/functional/detection/ciou.py b/src/torchmetrics/functional/detection/ciou.py index f1f340f6726..d0f5533b802 100644 --- a/src/torchmetrics/functional/detection/ciou.py +++ b/src/torchmetrics/functional/detection/ciou.py @@ -48,7 +48,7 @@ def complete_intersection_over_union( replacement_val: float = 0, aggregate: bool = True, ) -> torch.Tensor: - r"""Compute `Complete Intersection over Union `_ between two sets of boxes. + r"""Compute Complete Intersection over Union (`CIOU`_) between two sets of boxes. Both sets of boxes are expected to be in (x1, y1, x2, y2) format with 0 <= x1 < x2 and 0 <= y1 < y2. @@ -71,6 +71,7 @@ def complete_intersection_over_union( >>> target = torch.Tensor([[110, 110, 210, 210]]) >>> complete_intersection_over_union(preds, target) tensor(0.6724) + """ if not _TORCHVISION_GREATER_EQUAL_0_13: raise ModuleNotFoundError( diff --git a/src/torchmetrics/functional/detection/diou.py b/src/torchmetrics/functional/detection/diou.py index 8cb641a00ec..42554df0f20 100644 --- a/src/torchmetrics/functional/detection/diou.py +++ b/src/torchmetrics/functional/detection/diou.py @@ -48,7 +48,7 @@ def distance_intersection_over_union( replacement_val: float = 0, aggregate: bool = True, ) -> torch.Tensor: - r"""Compute `Distance Intersection over Union `_ between two sets of boxes. + r"""Compute Distance Intersection over Union (`DIOU`_) between two sets of boxes. Both sets of boxes are expected to be in (x1, y1, x2, y2) format with 0 <= x1 < x2 and 0 <= y1 < y2. @@ -71,6 +71,7 @@ def distance_intersection_over_union( >>> target = torch.Tensor([[110, 110, 210, 210]]) >>> distance_intersection_over_union(preds, target) tensor(0.6724) + """ if not _TORCHVISION_GREATER_EQUAL_0_13: raise ModuleNotFoundError( diff --git a/src/torchmetrics/functional/detection/giou.py b/src/torchmetrics/functional/detection/giou.py index a46ab8ef99b..980784f7e4f 100644 --- a/src/torchmetrics/functional/detection/giou.py +++ b/src/torchmetrics/functional/detection/giou.py @@ -48,7 +48,7 @@ def generalized_intersection_over_union( replacement_val: float = 0, aggregate: bool = True, ) -> torch.Tensor: - r"""Compute `Generalized Intersection over Union `_ between two sets of boxes. + r"""Compute Generalized Intersection over Union (`GIOU`_) between two sets of boxes. Both sets of boxes are expected to be in (x1, y1, x2, y2) format with 0 <= x1 < x2 and 0 <= y1 < y2. @@ -71,6 +71,7 @@ def generalized_intersection_over_union( >>> target = torch.Tensor([[110, 110, 210, 210]]) >>> generalized_intersection_over_union(preds, target) tensor(0.6641) + """ if not _TORCHVISION_GREATER_EQUAL_0_8: raise ModuleNotFoundError( diff --git a/src/torchmetrics/functional/detection/panoptic_qualities.py b/src/torchmetrics/functional/detection/panoptic_qualities.py index 6fcb14960e1..e30c29555b7 100644 --- a/src/torchmetrics/functional/detection/panoptic_qualities.py +++ b/src/torchmetrics/functional/detection/panoptic_qualities.py @@ -43,7 +43,6 @@ def panoptic_quality( true postitives, false positives and false negatives. This metric is inspired by the PQ implementation of panopticapi, a standard implementation for the PQ metric for object detection. - .. note: Points in the target tensor that do not map to a known category ID are automatically ignored in the metric computation. @@ -120,8 +119,8 @@ def modified_panoptic_quality( .. math:: PQ^{\dagger}_c = \frac{IOU_c}{|S_c|} - where IOU_c is the sum of the intersection over union of all matching segments for a given class, and \|S_c| is - the overall number of segments in the ground truth for that class. + where :math:`IOU_c` is the sum of the intersection over union of all matching segments for a given class, and + :math:`|S_c|` is the overall number of segments in the ground truth for that class. .. note: Points in the target tensor that do not map to a known category ID are automatically ignored in the metric @@ -151,7 +150,7 @@ def modified_panoptic_quality( TypeError: If ``preds`` or ``target`` is not an ``torch.Tensor``. ValueError: - If ``preds`` or ``target`` has different shape. + If ``preds`` or ``target`` has different shape. ValueError: If ``preds`` has less than 3 dimensions. ValueError: diff --git a/src/torchmetrics/image/fid.py b/src/torchmetrics/image/fid.py index 2afbc62db0c..879e305771c 100644 --- a/src/torchmetrics/image/fid.py +++ b/src/torchmetrics/image/fid.py @@ -191,8 +191,8 @@ class FrechetInceptionDistance(Metric): The metric was originally proposed in `fid ref1`_. Using the default feature extraction (Inception v3 using the original weights from `fid ref2`_), the input is - expected to be mini-batches of 3-channel RGB images of shape ``(3 x H x W)``. If argument ``normalize`` - is ``True`` images are expected to be dtype ``float`` and have values in the ``[0, 1]`` range, else if + expected to be mini-batches of 3-channel RGB images of shape ``(3xHxW)``. If argument ``normalize`` + is ``True`` images are expected to be dtype ``float`` and have values in the ``[0,1]`` range, else if ``normalize`` is set to ``False`` images are expected to have dtype ``uint8`` and take values in the ``[0, 255]`` range. All images will be resized to 299 x 299 which is the size of the original training data. The boolian flag ``real`` determines if the images should update the statistics of the real distribution or the diff --git a/src/torchmetrics/image/inception.py b/src/torchmetrics/image/inception.py index 5aa39d09490..8b2885081af 100644 --- a/src/torchmetrics/image/inception.py +++ b/src/torchmetrics/image/inception.py @@ -44,8 +44,8 @@ class InceptionScore(Metric): `inception ref1`_. Using the default feature extraction (Inception v3 using the original weights from `inception ref2`_), the input - is expected to be mini-batches of 3-channel RGB images of shape ``(3 x H x W)``. If argument ``normalize`` - is ``True`` images are expected to be dtype ``float`` and have values in the ``[0, 1]`` range, else if + is expected to be mini-batches of 3-channel RGB images of shape ``(3xHxW)``. If argument ``normalize`` + is ``True`` images are expected to be dtype ``float`` and have values in the ``[0,1]`` range, else if ``normalize`` is set to ``False`` images are expected to have dtype uint8 and take values in the ``[0, 255]`` range. All images will be resized to 299 x 299 which is the size of the original training data. diff --git a/src/torchmetrics/image/kid.py b/src/torchmetrics/image/kid.py index 84cfd198191..5fbcf0ac68b 100644 --- a/src/torchmetrics/image/kid.py +++ b/src/torchmetrics/image/kid.py @@ -84,8 +84,8 @@ class KernelInceptionDistance(Metric): subsets to be able to both get the mean and standard deviation of KID. Using the default feature extraction (Inception v3 using the original weights from `kid ref2`_), the input is - expected to be mini-batches of 3-channel RGB images of shape ``(3 x H x W)``. If argument ``normalize`` - is ``True`` images are expected to be dtype ``float`` and have values in the ``[0, 1]`` range, else if + expected to be mini-batches of 3-channel RGB images of shape ``(3xHxW)``. If argument ``normalize`` + is ``True`` images are expected to be dtype ``float`` and have values in the ``[0,1]`` range, else if ``normalize`` is set to ``False`` images are expected to have dtype ``uint8`` and take values in the ``[0, 255]`` range. All images will be resized to 299 x 299 which is the size of the original training data. The boolian flag ``real`` determines if the images should update the statistics of the real distribution or the diff --git a/src/torchmetrics/image/ssim.py b/src/torchmetrics/image/ssim.py index b34c60cc893..50b36172afc 100644 --- a/src/torchmetrics/image/ssim.py +++ b/src/torchmetrics/image/ssim.py @@ -228,7 +228,7 @@ class MultiScaleStructuralSimilarityIndexMeasure(Metric): As output of `forward` and `compute` the metric returns the following output - - ``msssim`` (: :class:`~torch.Tensor`): if ``reduction!='none'`` returns float scalar tensor with average MSSSIM + - ``msssim`` (:class:`~torch.Tensor`): if ``reduction!='none'`` returns float scalar tensor with average MSSSIM value over sample else returns tensor of shape ``(N,)`` with SSIM values per sample Args: diff --git a/src/torchmetrics/regression/minkowski.py b/src/torchmetrics/regression/minkowski.py index 7563cb4b270..9921ce0e326 100644 --- a/src/torchmetrics/regression/minkowski.py +++ b/src/torchmetrics/regression/minkowski.py @@ -29,16 +29,17 @@ class MinkowskiDistance(Metric): r"""Compute `Minkowski Distance`_. - .. math:: d_{\text{Minkowski}} = \\sum_{i}^N (| y_i - \\hat{y_i} |^p)^\frac{1}{p} + .. math:: + d_{\text{Minkowski}} = \sum_{i}^N (| y_i - \hat{y_i} |^p)^\frac{1}{p} + + where + :math: `y` is a tensor of target values, + :math: `\hat{y}` is a tensor of predictions, + :math: `\p` is a non-negative integer or floating-point number This metric can be seen as generalized version of the standard euclidean distance which corresponds to minkowski distance with p=2. - where - :math:`y` is a tensor of target values, - :math:`\\hat{y}` is a tensor of predictions, - :math: `\\p` is a non-negative integer or floating-point number - Args: p: int or float larger than 1, exponent to which the difference between preds and target is to be raised kwargs: Additional keyword arguments, see :ref:`Metric kwargs` for more info.