Address review: docs entry, docstring caveats, formatting

- Add AbsoluteVolumeDifferenceMetric + compute_absolute_volume_difference
  to docs/source/metrics.rst
- Note in the class docstring that 2D inputs yield surface areas and that
  values are raw voxel/pixel counts, not scaled by spacing
- Drop the unnecessary __init__ docstring
- Remove the redundant top-level import test
- Assert ValueError (not bare Exception) on aggregate after reset
- Apply black/isort formatting

Signed-off-by: Md Salman Shams <salmanshams67@gmail.com>

Author: MDSALMANSHAMS

docs/source/metrics.rst

@@ -116,6 +116,13 @@ Metrics
 .. autoclass:: SurfaceDiceMetric
     :members:
 
+`Absolute volume difference`
+----------------------------
+.. autofunction:: compute_absolute_volume_difference
+
+.. autoclass:: AbsoluteVolumeDifferenceMetric
+    :members:
+
 `PanopticQualityMetric`
 -----------------------
 .. autofunction:: compute_panoptic_quality

monai/metrics/absolute_volume_difference.py

@@ -31,6 +31,12 @@ class AbsoluteVolumeDifferenceMetric(CumulativeIterationMetric):
     segmentation (e.g. retinal fluid in OCT volumes) where Dice score is known to be
     overly sensitive to volume size and does not directly reflect volume discrepancies.
 
+    .. note::
+        For 2D inputs this computes the difference in foreground **areas** rather than
+        volumes.  In all cases the returned values are raw voxel/pixel counts and are
+        **not** scaled by the voxel/pixel spacing, so they are not expressed in the
+        physical units of the original image.
+
     Reference:
         Bogunovic et al. (2019). RETOUCH: The Retinal OCT Fluid Detection and
         Segmentation Benchmark and Challenge.
@@ -84,7 +90,6 @@ def __init__(
         get_not_nans: bool = False,
         ignore_empty: bool = True,
     ) -> None:
-        """Initialize AbsoluteVolumeDifferenceMetric. See class docstring for argument descriptions."""
         super().__init__()
         self.include_background = include_background
         self.reduction = reduction
@@ -105,10 +110,7 @@ def _compute_tensor(self, y_pred: torch.Tensor, y: torch.Tensor) -> torch.Tensor
                 f"y_pred should have at least 3 dimensions (batch, channel, spatial), got {y_pred.ndimension()}."
             )
         return compute_absolute_volume_difference(
-            y_pred=y_pred,
-            y=y,
-            include_background=self.include_background,
-            ignore_empty=self.ignore_empty,
+            y_pred=y_pred, y=y, include_background=self.include_background, ignore_empty=self.ignore_empty
         )
 
     def aggregate(
@@ -129,10 +131,7 @@ def aggregate(
 
 
 def compute_absolute_volume_difference(
-    y_pred: torch.Tensor,
-    y: torch.Tensor,
-    include_background: bool = True,
-    ignore_empty: bool = True,
+    y_pred: torch.Tensor, y: torch.Tensor, include_background: bool = True, ignore_empty: bool = True
 ) -> torch.Tensor:
     """
     Compute the Absolute Volume Difference (AVD) for a batch of segmentation predictions.
@@ -159,9 +158,7 @@ def compute_absolute_volume_difference(
         ValueError: when ``y_pred`` and ``y`` have different shapes.
     """
     if y_pred.ndim < 3:
-        raise ValueError(
-            f"y_pred should have at least 3 dimensions (batch, channel, spatial), got {y_pred.ndim}."
-        )
+        raise ValueError(f"y_pred should have at least 3 dimensions (batch, channel, spatial), got {y_pred.ndim}.")
 
     if not include_background:
         y_pred, y = ignore_background(y_pred=y_pred, y=y)

tests/metrics/test_absolute_volume_difference.py

@@ -78,18 +78,12 @@ def test_ignore_empty_false_returns_pred_volume(self):
     def test_shape_mismatch_raises(self):
         """Mismatched y_pred and y shapes should raise a ValueError."""
         with self.assertRaises(ValueError):
-            compute_absolute_volume_difference(
-                y_pred=torch.zeros(2, 3, 8, 8),
-                y=torch.zeros(2, 3, 4, 4),
-            )
+            compute_absolute_volume_difference(y_pred=torch.zeros(2, 3, 8, 8), y=torch.zeros(2, 3, 4, 4))
 
     def test_too_few_dims_raises(self):
         """Input tensors with fewer than 3 dimensions should raise a ValueError."""
         with self.assertRaises(ValueError):
-            compute_absolute_volume_difference(
-                y_pred=torch.zeros(2, 3),
-                y=torch.zeros(2, 3),
-            )
+            compute_absolute_volume_difference(y_pred=torch.zeros(2, 3), y=torch.zeros(2, 3))
 
     def test_3d_volumes(self):
         """AVD should correctly count voxel differences in 3-D spatial inputs."""
@@ -159,16 +153,9 @@ def test_reset_clears_buffer(self):
         metric(y, y)
         metric.reset()
         # after reset the buffer should be empty; calling aggregate raises
-        with self.assertRaises(Exception):
+        with self.assertRaises(ValueError):
             metric.aggregate()
 
-    def test_imported_from_top_level(self):
-        """AbsoluteVolumeDifferenceMetric should be importable from the monai.metrics top-level namespace."""
-        # ensure the class is accessible from monai.metrics top-level
-        from monai.metrics import AbsoluteVolumeDifferenceMetric as _AVD
-
-        self.assertIs(_AVD, AbsoluteVolumeDifferenceMetric)
-
 
 if __name__ == "__main__":
     unittest.main()