Dice score as metric

CHANGELOG.md

@@ -26,6 +26,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added support for nested metric collections ([#1003](https://github.com/PyTorchLightning/metrics/pull/1003))
 
 
+- Added `Dice` to classification package ([#1021](https://github.com/PyTorchLightning/metrics/pull/1021))
+
+
 ### Changed
 
 -

docs/source/classification/dice.rst

@@ -0,0 +1,33 @@
+.. customcarditem::
+   :header: Dice
+   :image: https://pl-flash-data.s3.amazonaws.com/assets/thumbnails/tabular_classification.svg
+   :tags: Classification
+
+.. include:: ../links.rst
+
+####
+Dice
+####
+
+Module Interface
+________________
+
+.. autoclass:: torchmetrics.Dice
+    :noindex:
+
+Functional Interface
+____________________
+
+.. autofunction:: torchmetrics.functional.dice
+    :noindex:
+
+
+##########
+Dice Score
+##########
+
+Functional Interface (was deprecated in v0.9)
+_____________________________________________
+
+.. autofunction:: torchmetrics.functional.dice_score
+    :noindex:

docs/source/links.rst

@@ -22,6 +22,7 @@
 .. _Matthews correlation coefficient: https://en.wikipedia.org/wiki/Matthews_correlation_coefficient
 .. _Precision: https://en.wikipedia.org/wiki/Precision_and_recall
 .. _Recall: https://en.wikipedia.org/wiki/Precision_and_recall
+.. _Dice: https://en.wikipedia.org/wiki/Sørensen–Dice_coefficient
 .. _Specificity: https://en.wikipedia.org/wiki/Sensitivity_and_specificity
 .. _Type I and Type II errors: https://en.wikipedia.org/wiki/Type_I_and_type_II_errors
 .. _confusion matrix: https://en.wikipedia.org/wiki/Confusion_matrix#Table_of_confusion

tests/classification/test_dice.py

@@ -11,10 +11,58 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+from functools import partial
+from typing import Optional
+
 import pytest
-from torch import tensor
+from scipy.spatial.distance import dice as _sc_dice
+from torch import Tensor, tensor
+
+from tests.classification.inputs import _input_binary, _input_binary_logits, _input_binary_prob
+from tests.classification.inputs import _input_multiclass as _input_mcls
+from tests.classification.inputs import _input_multiclass_logits as _input_mcls_logits
+from tests.classification.inputs import _input_multiclass_prob as _input_mcls_prob
+from tests.classification.inputs import _input_multiclass_with_missing_class as _input_miss_class
+from tests.classification.inputs import _input_multilabel as _input_mlb
+from tests.classification.inputs import _input_multilabel_logits as _input_mlb_logits
+from tests.classification.inputs import _input_multilabel_multidim as _input_mlmd
+from tests.classification.inputs import _input_multilabel_multidim_prob as _input_mlmd_prob
+from tests.classification.inputs import _input_multilabel_prob as _input_mlb_prob
+from tests.helpers import seed_all
+from tests.helpers.testers import MetricTester
+from torchmetrics import Dice
+from torchmetrics.functional import dice, dice_score
+from torchmetrics.functional.classification.stat_scores import _del_column
+from torchmetrics.utilities.checks import _input_format_classification
+from torchmetrics.utilities.enums import DataType
+
+seed_all(42)
+
+
+def _sk_dice(
+    preds: Tensor,
+    target: Tensor,
+    ignore_index: Optional[int] = None,
+) -> float:
+    """Compute dice score from prediction and target. Used scipy implementation of main dice logic.
 
-from torchmetrics.functional import dice_score
+    Args:
+        preds: prediction tensor
+        target: target tensor
+        ignore_index:
+            Integer specifying a target class to ignore. Recommend set to index of background class.
+    Return:
+        Float dice score
+    """
+    sk_preds, sk_target, mode = _input_format_classification(preds, target)
+
+    if ignore_index is not None and mode != DataType.BINARY:
+        sk_preds = _del_column(sk_preds, ignore_index)
+        sk_target = _del_column(sk_target, ignore_index)
+
+    sk_preds, sk_target = sk_preds.numpy(), sk_target.numpy()
+
+    return 1 - _sc_dice(sk_preds.reshape(-1), sk_target.reshape(-1))
 
 
 @pytest.mark.parametrize(
@@ -29,3 +77,89 @@
 def test_dice_score(pred, target, expected):
     score = dice_score(tensor(pred), tensor(target))
     assert score == expected
+
+
+@pytest.mark.parametrize(
+    ["pred", "target", "expected"],
+    [
+        ([[0, 0], [1, 1]], [[0, 0], [1, 1]], 1.0),
+        ([[1, 1], [0, 0]], [[0, 0], [1, 1]], 0.0),
+        ([[1, 1], [1, 1]], [[1, 1], [0, 0]], 2 / 3),
+        ([[1, 1], [0, 0]], [[1, 1], [0, 0]], 1.0),
+    ],
+)
+def test_dice(pred, target, expected):
+    score = dice(tensor(pred), tensor(target), ignore_index=0)
+    assert score == expected
+
+
+@pytest.mark.parametrize(
+    "preds, target",
+    [
+        (_input_binary.preds, _input_binary.target),
+        (_input_binary_logits.preds, _input_binary_logits.target),
+        (_input_binary_prob.preds, _input_binary_prob.target),
+    ],
+)
+@pytest.mark.parametrize("ignore_index", [None])
+class TestDiceBinary(MetricTester):
+    @pytest.mark.parametrize("ddp", [False])
+    @pytest.mark.parametrize("dist_sync_on_step", [False])
+    def test_dice_class(self, ddp, dist_sync_on_step, preds, target, ignore_index):
+        self.run_class_metric_test(
+            ddp=ddp,
+            preds=preds,
+            target=target,
+            metric_class=Dice,
+            sk_metric=partial(_sk_dice, ignore_index=ignore_index),
+            dist_sync_on_step=dist_sync_on_step,
+            metric_args={"ignore_index": ignore_index},
+        )
+
+    def test_dice_fn(self, preds, target, ignore_index):
+        self.run_functional_metric_test(
+            preds,
+            target,
+            metric_functional=dice,
+            sk_metric=partial(_sk_dice, ignore_index=ignore_index),
+            metric_args={"ignore_index": ignore_index},
+        )
+
+
+@pytest.mark.parametrize(
+    "preds, target",
+    [
+        (_input_mcls.preds, _input_mcls.target),
+        (_input_mcls_logits.preds, _input_mcls_logits.target),
+        (_input_mcls_prob.preds, _input_mcls_prob.target),
+        (_input_miss_class.preds, _input_miss_class.target),
+        (_input_mlb.preds, _input_mlb.target),
+        (_input_mlb_logits.preds, _input_mlb_logits.target),
+        (_input_mlmd.preds, _input_mlmd.target),
+        (_input_mlmd_prob.preds, _input_mlmd_prob.target),
+        (_input_mlb_prob.preds, _input_mlb_prob.target),
+    ],
+)
+@pytest.mark.parametrize("ignore_index", [None, 0])
+class TestDiceMulti(MetricTester):
+    @pytest.mark.parametrize("ddp", [False])
+    @pytest.mark.parametrize("dist_sync_on_step", [False])
+    def test_dice_class(self, ddp, dist_sync_on_step, preds, target, ignore_index):
+        self.run_class_metric_test(
+            ddp=ddp,
+            preds=preds,
+            target=target,
+            metric_class=Dice,
+            sk_metric=partial(_sk_dice, ignore_index=ignore_index),
+            dist_sync_on_step=dist_sync_on_step,
+            metric_args={"ignore_index": ignore_index},
+        )
+
+    def test_dice_fn(self, preds, target, ignore_index):
+        self.run_functional_metric_test(
+            preds,
+            target,
+            metric_functional=dice,
+            sk_metric=partial(_sk_dice, ignore_index=ignore_index),
+            metric_args={"ignore_index": ignore_index},
+        )

torchmetrics/__init__.py

@@ -33,6 +33,7 @@
     CohenKappa,
     ConfusionMatrix,
     CoverageError,
+    Dice,
     F1Score,
     FBetaScore,
     HammingDistance,
@@ -126,6 +127,7 @@
     "ConfusionMatrix",
     "CosineSimilarity",
     "CoverageError",
+    "Dice",
     "TweedieDevianceScore",
     "ErrorRelativeGlobalDimensionlessSynthesis",
     "ExplainedVariance",

torchmetrics/classification/__init__.py

@@ -21,6 +21,7 @@
 from torchmetrics.classification.calibration_error import CalibrationError  # noqa: F401
 from torchmetrics.classification.cohen_kappa import CohenKappa  # noqa: F401
 from torchmetrics.classification.confusion_matrix import ConfusionMatrix  # noqa: F401
+from torchmetrics.classification.dice import Dice  # noqa: F401
 from torchmetrics.classification.f_beta import F1Score, FBetaScore  # noqa: F401
 from torchmetrics.classification.hamming import HammingDistance  # noqa: F401
 from torchmetrics.classification.hinge import HingeLoss  # noqa: F401