Repository: Project-MONAI/MONAI

Issue:
Documentation for DiceLoss is misleading
The [documentation for `DiceLoss`](https://docs.monai.io/en/latest/losses.html?highlight=dice%20loss#diceloss) says (my bold):

> Compute average Dice loss between two tensors. It can support both multi-classes and multi-labels tasks. Input **logits** _input_ (BNHW[D] where N is number of classes) is compared with ground truth _target_ (BNHW[D]). Axis N of _input_ is expected to have **logit** predictions for each class rather than being image channels, while the same axis of target can be 1 or N (one-hot format)...

The term "logit" here doesn't seem to match how `DiceLoss` [actually works](https://github.com/Project-MONAI/MONAI/blob/dev/monai/losses/dice.py#L162-L176); it expects class probabilities and not logit values. That can change for one of the inputs if the parameters `sigmoid` or `softmax` are set to `True`, but those parameters are `False` by default.


Discussion:

Resolving patch:
diff --git a/monai/losses/dice.py b/monai/losses/dice.py
--- a/monai/losses/dice.py
+++ b/monai/losses/dice.py
@@ -27,16 +27,17 @@
 class DiceLoss(_Loss):
     """
     Compute average Dice loss between two tensors. It can support both multi-classes and multi-labels tasks.
-    Input logits `input` (BNHW[D] where N is number of classes) is compared with ground truth `target` (BNHW[D]).
-    Axis N of `input` is expected to have logit predictions for each class rather than being image channels,
-    while the same axis of `target` can be 1 or N (one-hot format). The `smooth_nr` and `smooth_dr` parameters are
-    values added to the intersection and union components of the inter-over-union calculation to smooth results
-    respectively, these values should be small. The `include_background` class attribute can be set to False for
-    an instance of DiceLoss to exclude the first category (channel index 0) which is by convention assumed to be
-    background. If the non-background segmentations are small compared to the total image size they can get
-    overwhelmed by the signal from the background so excluding it in such cases helps convergence.
+    The data `input` (BNHW[D] where N is number of classes) is compared with ground truth `target` (BNHW[D]).
 
-    Milletari, F. et. al. (2016) V-Net: Fully Convolutional Neural Networks forVolumetric Medical Image Segmentation, 3DV, 2016.
+    Note that axis N of `input` is expected to be logits or probabilities for each class, if passing logits as input,
+    must set `sigmoid=True` or `softmax=True`, or specifying `other_act`. And the same axis of `target`
+    can be 1 or N (one-hot format).
+
+    The `smooth_nr` and `smooth_dr` parameters are values added to the intersection and union components of
+    the inter-over-union calculation to smooth results respectively, these values should be small.
+
+    The original paper: Milletari, F. et. al. (2016) V-Net: Fully Convolutional Neural Networks forVolumetric
+    Medical Image Segmentation, 3DV, 2016.
 
     """
 
@@ -57,6 +58,8 @@ def __init__(
         """
         Args:
             include_background: if False, channel index 0 (background category) is excluded from the calculation.
+                if the non-background segmentations are small compared to the total image size they can get overwhelmed
+                by the signal from the background so excluding it in such cases helps convergence.
             to_onehot_y: whether to convert `y` into the one-hot format. Defaults to False.
             sigmoid: if True, apply a sigmoid function to the prediction.
             softmax: if True, apply a softmax function to the prediction.


Test patch: