Fix per_component Dice silently ignoring ignore_index (#9171)

### Description
`DiceHelper`/`DiceMetric`'s `per_component=True` path never received the
spatial mask `create_ignore_mask` builds from `ignore_index` —
`compute_cc_dice` has no mask parameter at all, so combining
`per_component=True` with `ignore_index` silently computed TP/FP/FN over
the "ignored" voxels as if nothing were ignored. The regular per-channel
path already applies this mask correctly; only the per-component path
was missing it.

Fix threads the mask into `compute_cc_dice`: ignored voxels are forced
to agree as background in both `y` and `y_pred` before the
connected-component assignment and histogram, so they never contribute
to any component's score — consistent with how the non-per_component
path already handles masking.

Reachable via the public API: `DiceMetric(per_component=True,
ignore_index=N)(y_pred, y)`. No existing test exercised this combination
(checked `tests/metrics/test_compute_meandice.py` — separate
`per_component` and `ignore_index` cases, never together).

### Types of changes
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] New tests added to cover the changes
- [ ] Integration tests passed locally by running `./runtests.sh -f -u
--net --coverage`
- [ ] Quick tests passed locally by running `./runtests.sh --quick
--unittests --disttests` (ran the targeted test file directly via pytest
instead: `pytest tests/metrics/test_compute_meandice.py`, 22/22 passed;
did not run the full repo test runner)
- [ ] In-line docstrings updated
- [ ] Documentation updated

---------

Signed-off-by: Siddhardha Nanda <99672439+SID-6921@users.noreply.github.com>
Signed-off-by: Eric Kerfoot <17726042+ericspod@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Eric Kerfoot <17726042+ericspod@users.noreply.github.com>

Author: 3 people

monai/metrics/meandice.py

@@ -331,23 +331,34 @@ def __init__(
         self.per_component = per_component
         self.ignore_index = ignore_index
 
-    def compute_cc_dice(self, y_pred: torch.Tensor, y: torch.Tensor) -> torch.Tensor:
+    def compute_cc_dice(self, y_pred: torch.Tensor, y: torch.Tensor, mask: torch.Tensor | None = None) -> torch.Tensor:
         """
         Compute per-component Dice for a single batch item.
 
         Args:
             y_pred (torch.Tensor): Predictions with shape (1, 2, D, H, W) or (1, 2, H, W).
             y (torch.Tensor): Ground truth with shape (1, 2, D, H, W) or (1, 2, H, W).
+            mask (torch.Tensor, optional): spatial mask (1, D, H, W) or (1, H, W) from
+                ``create_ignore_mask``, 1=valid, 0=ignore. Ignored voxels are forced to
+                agree as background in both `y` and `y_pred`, so they never contribute to
+                a component's TP/FP/FN, matching how `ignore_index` is handled elsewhere.
 
         Returns:
             torch.Tensor: Mean Dice over connected components.
+        Raises:
+            OptionalImportError: If the ground truth contains foreground voxels
+                after masking, is on the CPU, and SciPy is unavailable.
         """
         if y_pred.ndim == y.ndim:
             y_pred_idx = torch.argmax(y_pred, dim=1)
             y_idx = torch.argmax(y, dim=1)
         else:
             y_pred_idx = y_pred
             y_idx = y
+        if mask is not None:
+            ignore = mask == 0
+            y_idx = y_idx.masked_fill(ignore, 0)
+            y_pred_idx = y_pred_idx.masked_fill(ignore, 0)
         if y_idx[0].sum() == 0:
             if self.ignore_empty:
                 data = torch.tensor(float("nan"), device=y_idx.device)
@@ -445,7 +456,10 @@ def __call__(self, y_pred: torch.Tensor, y: torch.Tensor) -> torch.Tensor | tupl
         data = []
         for b in range(y_pred.shape[0]):
             if self.per_component:
-                data.append(self.compute_cc_dice(y_pred=y_pred[b].unsqueeze(0), y=y[b].unsqueeze(0)).reshape(-1))
+                b_mask = mask[b, 0] if mask is not None else None
+                data.append(
+                    self.compute_cc_dice(y_pred=y_pred[b].unsqueeze(0), y=y[b].unsqueeze(0), mask=b_mask).reshape(-1)
+                )
                 continue
             c_list = []
             for c in range(first_ch, n_pred_ch) if n_pred_ch > 1 else [1]:

tests/metrics/test_compute_meandice.py

@@ -290,6 +290,19 @@
     [[0.6400], [1.0], [1.0], [1.0], [1.0]],
 ]
 
+# Testcase for per_component DiceMetric with ignore_index: a disagreement confined
+# entirely to the ignored (sentinel, all-zero one-hot) region must not affect the score.
+y = torch.zeros((1, 2, 8, 8))
+y_hat = torch.zeros((1, 2, 8, 8))
+y[0, 1, :, :4] = 1
+y_hat[0, 1, :, :4] = 1
+y_hat[0, 1, :, 4:] = 1  # disagreement, but this region is ignored below
+y[0, 0] = 1 - y[0, 1]
+y[0, 0, :, 4:] = 0  # sentinel: both channels 0 -> ignored by ignore_index=2
+y_hat[0, 0] = 1 - y_hat[0, 1]
+
+TEST_CASE_18 = [{"per_component": True, "ignore_empty": False, "ignore_index": 2}, {"y": y, "y_pred": y_hat}, [[1.0]]]
+
 
 class TestComputeMeanDice(unittest.TestCase):
 
@@ -342,7 +355,7 @@ def test_nans_class(self, params, input_data, expected_value):
             np.testing.assert_allclose(result.cpu().numpy(), expected_value, atol=1e-4)
 
     # CC DiceMetric  tests
-    @parameterized.expand([TEST_CASE_16, TEST_CASE_17])
+    @parameterized.expand([TEST_CASE_16, TEST_CASE_17, TEST_CASE_18])
     @unittest.skipUnless(has_ndimage, "Requires scipy.ndimage.")
     def test_cc_dice_value_nogpu(self, params, input_data, expected_value):
         dice_metric = DiceMetric(**params)