rename IoU -> Jaccard Index

CHANGELOG.md

@@ -40,6 +40,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Deprecated
 
+- Renamed IoU -> Jaccard Index ([#662](https://github.com/PyTorchLightning/metrics/pull/662))
+
 
 ### Removed
 

docs/source/references/functional.rst

@@ -144,10 +144,10 @@ hinge [func]
 .. autofunction:: torchmetrics.functional.hinge
     :noindex:
 
-iou [func]
-~~~~~~~~~~
+jaccard_index [func]
+~~~~~~~~~~~~~~~~~~~~
 
-.. autofunction:: torchmetrics.functional.iou
+.. autofunction:: torchmetrics.functional.jaccard_index
     :noindex:
 
 kl_divergence [func]

docs/source/references/modules.rst

@@ -302,10 +302,10 @@ Hinge
 .. autoclass:: torchmetrics.Hinge
     :noindex:
 
-IoU
-~~~
+JaccardIndex
+~~~~~~~~~~~~
 
-.. autoclass:: torchmetrics.IoU
+.. autoclass:: torchmetrics.JaccardIndex
     :noindex:
 
 KLDivergence

tests/classification/test_iou.py → tests/classification/test_jaccard.py

@@ -27,60 +27,60 @@
 from tests.classification.inputs import _input_multilabel as _input_mlb
 from tests.classification.inputs import _input_multilabel_prob as _input_mlb_prob
 from tests.helpers.testers import NUM_CLASSES, THRESHOLD, MetricTester
-from torchmetrics.classification.iou import IoU
-from torchmetrics.functional import iou
+from torchmetrics.classification.jaccard import JaccardIndex
+from torchmetrics.functional import jaccard_index
 
 
-def _sk_iou_binary_prob(preds, target, average=None):
+def _sk_jaccard_binary_prob(preds, target, average=None):
     sk_preds = (preds.view(-1).numpy() >= THRESHOLD).astype(np.uint8)
     sk_target = target.view(-1).numpy()
 
     return sk_jaccard_score(y_true=sk_target, y_pred=sk_preds, average=average)
 
 
-def _sk_iou_binary(preds, target, average=None):
+def _sk_jaccard_binary(preds, target, average=None):
     sk_preds = preds.view(-1).numpy()
     sk_target = target.view(-1).numpy()
 
     return sk_jaccard_score(y_true=sk_target, y_pred=sk_preds, average=average)
 
 
-def _sk_iou_multilabel_prob(preds, target, average=None):
+def _sk_jaccard_multilabel_prob(preds, target, average=None):
     sk_preds = (preds.view(-1).numpy() >= THRESHOLD).astype(np.uint8)
     sk_target = target.view(-1).numpy()
 
     return sk_jaccard_score(y_true=sk_target, y_pred=sk_preds, average=average)
 
 
-def _sk_iou_multilabel(preds, target, average=None):
+def _sk_jaccard_multilabel(preds, target, average=None):
     sk_preds = preds.view(-1).numpy()
     sk_target = target.view(-1).numpy()
 
     return sk_jaccard_score(y_true=sk_target, y_pred=sk_preds, average=average)
 
 
-def _sk_iou_multiclass_prob(preds, target, average=None):
+def _sk_jaccard_multiclass_prob(preds, target, average=None):
     sk_preds = torch.argmax(preds, dim=len(preds.shape) - 1).view(-1).numpy()
     sk_target = target.view(-1).numpy()
 
     return sk_jaccard_score(y_true=sk_target, y_pred=sk_preds, average=average)
 
 
-def _sk_iou_multiclass(preds, target, average=None):
+def _sk_jaccard_multiclass(preds, target, average=None):
     sk_preds = preds.view(-1).numpy()
     sk_target = target.view(-1).numpy()
 
     return sk_jaccard_score(y_true=sk_target, y_pred=sk_preds, average=average)
 
 
-def _sk_iou_multidim_multiclass_prob(preds, target, average=None):
+def _sk_jaccard_multidim_multiclass_prob(preds, target, average=None):
     sk_preds = torch.argmax(preds, dim=len(preds.shape) - 2).view(-1).numpy()
     sk_target = target.view(-1).numpy()
 
     return sk_jaccard_score(y_true=sk_target, y_pred=sk_preds, average=average)
 
 
-def _sk_iou_multidim_multiclass(preds, target, average=None):
+def _sk_jaccard_multidim_multiclass(preds, target, average=None):
     sk_preds = preds.view(-1).numpy()
     sk_target = target.view(-1).numpy()
 
@@ -91,47 +91,47 @@ def _sk_iou_multidim_multiclass(preds, target, average=None):
 @pytest.mark.parametrize(
     "preds, target, sk_metric, num_classes",
     [
-        (_input_binary_prob.preds, _input_binary_prob.target, _sk_iou_binary_prob, 2),
-        (_input_binary.preds, _input_binary.target, _sk_iou_binary, 2),
-        (_input_mlb_prob.preds, _input_mlb_prob.target, _sk_iou_multilabel_prob, 2),
-        (_input_mlb.preds, _input_mlb.target, _sk_iou_multilabel, 2),
-        (_input_mcls_prob.preds, _input_mcls_prob.target, _sk_iou_multiclass_prob, NUM_CLASSES),
-        (_input_mcls.preds, _input_mcls.target, _sk_iou_multiclass, NUM_CLASSES),
-        (_input_mdmc_prob.preds, _input_mdmc_prob.target, _sk_iou_multidim_multiclass_prob, NUM_CLASSES),
-        (_input_mdmc.preds, _input_mdmc.target, _sk_iou_multidim_multiclass, NUM_CLASSES),
+        (_input_binary_prob.preds, _input_binary_prob.target, _sk_jaccard_binary_prob, 2),
+        (_input_binary.preds, _input_binary.target, _sk_jaccard_binary, 2),
+        (_input_mlb_prob.preds, _input_mlb_prob.target, _sk_jaccard_multilabel_prob, 2),
+        (_input_mlb.preds, _input_mlb.target, _sk_jaccard_multilabel, 2),
+        (_input_mcls_prob.preds, _input_mcls_prob.target, _sk_jaccard_multiclass_prob, NUM_CLASSES),
+        (_input_mcls.preds, _input_mcls.target, _sk_jaccard_multiclass, NUM_CLASSES),
+        (_input_mdmc_prob.preds, _input_mdmc_prob.target, _sk_jaccard_multidim_multiclass_prob, NUM_CLASSES),
+        (_input_mdmc.preds, _input_mdmc.target, _sk_jaccard_multidim_multiclass, NUM_CLASSES),
     ],
 )
-class TestIoU(MetricTester):
+class TestJaccardIndex(MetricTester):
     @pytest.mark.parametrize("ddp", [True, False])
     @pytest.mark.parametrize("dist_sync_on_step", [True, False])
-    def test_iou(self, reduction, preds, target, sk_metric, num_classes, ddp, dist_sync_on_step):
+    def test_jaccard(self, reduction, preds, target, sk_metric, num_classes, ddp, dist_sync_on_step):
         average = "macro" if reduction == "elementwise_mean" else None  # convert tags
         self.run_class_metric_test(
             ddp=ddp,
             preds=preds,
             target=target,
-            metric_class=IoU,
+            metric_class=JaccardIndex,
             sk_metric=partial(sk_metric, average=average),
             dist_sync_on_step=dist_sync_on_step,
             metric_args={"num_classes": num_classes, "threshold": THRESHOLD, "reduction": reduction},
         )
 
-    def test_iou_functional(self, reduction, preds, target, sk_metric, num_classes):
+    def test_jaccard_functional(self, reduction, preds, target, sk_metric, num_classes):
         average = "macro" if reduction == "elementwise_mean" else None  # convert tags
         self.run_functional_metric_test(
             preds,
             target,
-            metric_functional=iou,
+            metric_functional=jaccard_index,
             sk_metric=partial(sk_metric, average=average),
             metric_args={"num_classes": num_classes, "threshold": THRESHOLD, "reduction": reduction},
         )
 
-    def test_iou_differentiability(self, reduction, preds, target, sk_metric, num_classes):
+    def test_jaccard_differentiability(self, reduction, preds, target, sk_metric, num_classes):
         self.run_differentiability_test(
             preds=preds,
             target=target,
-            metric_module=IoU,
-            metric_functional=iou,
+            metric_module=JaccardIndex,
+            metric_functional=jaccard_index,
             metric_args={"num_classes": num_classes, "threshold": THRESHOLD, "reduction": reduction},
         )
 
@@ -147,18 +147,18 @@ def test_iou_differentiability(self, reduction, preds, target, sk_metric, num_cl
         (True, "none", 0, Tensor([2 / 3, 1 / 2])),
     ],
 )
-def test_iou(half_ones, reduction, ignore_index, expected):
+def test_jaccard(half_ones, reduction, ignore_index, expected):
     preds = (torch.arange(120) % 3).view(-1, 1)
     target = (torch.arange(120) % 3).view(-1, 1)
     if half_ones:
         preds[:60] = 1
-    iou_val = iou(
+    jaccard_val = jaccard_index(
         preds=preds,
         target=target,
         ignore_index=ignore_index,
         reduction=reduction,
     )
-    assert torch.allclose(iou_val, expected, atol=1e-9)
+    assert torch.allclose(jaccard_val, expected, atol=1e-9)
 
 
 # test `absent_score`
@@ -194,16 +194,16 @@ def test_iou(half_ones, reduction, ignore_index, expected):
         ([0, 2], [0, 2], 0, 1.0, 3, [1.0, 1.0]),
     ],
 )
-def test_iou_absent_score(pred, target, ignore_index, absent_score, num_classes, expected):
-    iou_val = iou(
+def test_jaccard_absent_score(pred, target, ignore_index, absent_score, num_classes, expected):
+    jaccard_val = jaccard_index(
         preds=tensor(pred),
         target=tensor(target),
         ignore_index=ignore_index,
         absent_score=absent_score,
         num_classes=num_classes,
         reduction="none",
     )
-    assert torch.allclose(iou_val, tensor(expected).to(iou_val))
+    assert torch.allclose(jaccard_val, tensor(expected).to(jaccard_val))
 
 
 # example data taken from
@@ -224,12 +224,12 @@ def test_iou_absent_score(pred, target, ignore_index, absent_score, num_classes,
         ([0, 1, 1, 2, 2], [0, 1, 2, 2, 2], 0, 3, "sum", [7 / 6]),
     ],
 )
-def test_iou_ignore_index(pred, target, ignore_index, num_classes, reduction, expected):
-    iou_val = iou(
+def test_jaccard_ignore_index(pred, target, ignore_index, num_classes, reduction, expected):
+    jaccard_val = jaccard_index(
         preds=tensor(pred),
         target=tensor(target),
         ignore_index=ignore_index,
         num_classes=num_classes,
         reduction=reduction,
     )
-    assert torch.allclose(iou_val, tensor(expected).to(iou_val))
+    assert torch.allclose(jaccard_val, tensor(expected).to(jaccard_val))

torchmetrics/__init__.py

@@ -14,7 +14,7 @@
 from torchmetrics import functional  # noqa: E402
 from torchmetrics.aggregation import CatMetric, MaxMetric, MeanMetric, MinMetric, SumMetric  # noqa: E402
 from torchmetrics.audio import PIT, SDR, SI_SDR, SI_SNR, SNR  # noqa: E402
-from torchmetrics.classification import (  # noqa: E402
+from torchmetrics.classification import (  # noqa: E402, F401
     AUC,
     AUROC,
     F1,
@@ -31,6 +31,7 @@
     HammingDistance,
     Hinge,
     IoU,
+    JaccardIndex,
     KLDivergence,
     MatthewsCorrcoef,
     Precision,
@@ -101,7 +102,7 @@
     "FBeta",
     "HammingDistance",
     "Hinge",
-    "IoU",
+    "JaccardIndex",
     "KLDivergence",
     "MatthewsCorrcoef",
     "MaxMetric",

torchmetrics/classification/__init__.py

@@ -25,6 +25,7 @@
 from torchmetrics.classification.hamming_distance import HammingDistance  # noqa: F401
 from torchmetrics.classification.hinge import Hinge  # noqa: F401
 from torchmetrics.classification.iou import IoU  # noqa: F401
+from torchmetrics.classification.jaccard import JaccardIndex  # noqa: F401
 from torchmetrics.classification.kl_divergence import KLDivergence  # noqa: F401
 from torchmetrics.classification.matthews_corrcoef import MatthewsCorrcoef  # noqa: F401
 from torchmetrics.classification.precision_recall import Precision, Recall  # noqa: F401

torchmetrics/classification/iou.py

@@ -12,60 +12,19 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 from typing import Any, Optional
+from warnings import warn
 
 import torch
-from torch import Tensor
 
-from torchmetrics.classification.confusion_matrix import ConfusionMatrix
-from torchmetrics.functional.classification.iou import _iou_from_confmat
+from torchmetrics.classification.jaccard import JaccardIndex
 
 
-class IoU(ConfusionMatrix):
+class IoU(JaccardIndex):
     r"""
     Computes Intersection over union, or `Jaccard index`_:
 
-    .. math:: J(A,B) = \frac{|A\cap B|}{|A\cup B|}
-
-    Where: :math:`A` and :math:`B` are both tensors of the same size, containing integer class values.
-    They may be subject to conversion from input data (see description below). Note that it is different from box IoU.
-
-    Works with binary, multiclass and multi-label data.
-    Accepts probabilities from a model output or integer class values in prediction.
-    Works with multi-dimensional preds and target.
-
-    Forward accepts
-
-    - ``preds`` (float or long tensor): ``(N, ...)`` or ``(N, C, ...)`` where C is the number of classes
-    - ``target`` (long tensor): ``(N, ...)``
-
-    If preds and target are the same shape and preds is a float tensor, we use the ``self.threshold`` argument
-    to convert into integer labels. This is the case for binary and multi-label probabilities.
-
-    If preds has an extra dimension as in the case of multi-class scores we perform an argmax on ``dim=1``.
-
-    Args:
-        num_classes: Number of classes in the dataset.
-        ignore_index: optional int specifying a target class to ignore. If given, this class index does not contribute
-            to the returned score, regardless of reduction method. Has no effect if given an int that is not in the
-            range [0, num_classes-1]. By default, no index is ignored, and all classes are used.
-        absent_score: score to use for an individual class, if no instances of the class index were present in
-            `pred` AND no instances of the class index were present in `target`. For example, if we have 3 classes,
-            [0, 0] for `pred`, and [0, 2] for `target`, then class 1 would be assigned the `absent_score`.
-        threshold:
-            Threshold value for binary or multi-label probabilities.
-        reduction: a method to reduce metric score over labels.
-
-            - ``'elementwise_mean'``: takes the mean (default)
-            - ``'sum'``: takes the sum
-            - ``'none'``: no reduction will be applied
-
-        compute_on_step:
-            Forward only calls ``update()`` and return None if this is set to False.
-        dist_sync_on_step:
-            Synchronize metric state across processes at each ``forward()``
-            before returning the value at the step.
-        process_group:
-            Specify the process group on which synchronization is called. default: None (which selects the entire world)
+    .. deprecated:: v0.7
+        Use :class:`torchmetrics.JaccardIndex`. Will be removed in v0.8.
 
     Example:
         >>> from torchmetrics import IoU
@@ -77,8 +36,6 @@ class IoU(ConfusionMatrix):
         tensor(0.9660)
 
     """
-    is_differentiable = False
-    higher_is_better = True
 
     def __init__(
         self,
@@ -91,18 +48,14 @@ def __init__(
         dist_sync_on_step: bool = False,
         process_group: Optional[Any] = None,
     ) -> None:
+        warn("`IoU` was renamed to `JaccardIndex` in v0.7 and it will be removed in v0.8", DeprecationWarning)
         super().__init__(
             num_classes=num_classes,
-            normalize=None,
+            ignore_index=ignore_index,
+            absent_score=absent_score,
             threshold=threshold,
+            reduction=reduction,
             compute_on_step=compute_on_step,
             dist_sync_on_step=dist_sync_on_step,
             process_group=process_group,
         )
-        self.reduction = reduction
-        self.ignore_index = ignore_index
-        self.absent_score = absent_score
-
-    def compute(self) -> Tensor:
-        """Computes intersection over union (IoU)"""
-        return _iou_from_confmat(self.confmat, self.num_classes, self.ignore_index, self.absent_score, self.reduction)