📝 Add Examples to utils/metrics.py (#921)

- Add examples to `utils/metrics.py`.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Shan E Ahmed Raza <13048456+shaneahmed@users.noreply.github.com>

Author: 3 people

tiatoolbox/utils/metrics.py

@@ -41,6 +41,20 @@ def pair_coordinates(
             - :class:`numpy.ndarray` - Unpaired B:
                     Indices of unpaired points in set B.
 
+
+    Examples:
+        >>> from tiatoolbox.utils.metrics import pair_coordinates
+        >>> # Generate two random example sets; replace with your own data
+        >>> import numpy as np
+        >>> np.random.seed(6)
+        >>> set_a_num_points = np.random.randint(low=10, high=30)
+        >>> set_b_num_points = np.random.randint(low=10, high=30)
+        >>> set_a = np.random.randint(low=0, high=25, size=(set_a_num_points, 2))
+        >>> set_b = np.random.randint(low=0, high=25, size=(set_b_num_points, 2))
+        >>> radius = 2.0
+        >>> # Example usage of pair_coordinates
+        >>> pairing, unpaired_a, unpaired_b = pair_coordinates(set_a, set_b, radius)
+
     """
     # * Euclidean distance as the cost matrix
     pair_distance = distance.cdist(set_a, set_b, metric="euclidean")
@@ -65,7 +79,22 @@ def pair_coordinates(
 
 
 def f1_detection(true: np.ndarray, pred: np.ndarray, radius: float) -> float:
-    """Calculate the F1-score for predicted set of coordinates."""
+    """Calculate the F1-score for predicted set of coordinates.
+
+    Examples:
+        >>> from tiatoolbox.utils.metrics import f1_detection
+        >>> # Generate two random example sets; replace with your own data
+        >>> import numpy as np
+        >>> np.random.seed(6)
+        >>> true_num_points = np.random.randint(low=10, high=30)
+        >>> pred_num_points = np.random.randint(low=10, high=30)
+        >>> true = np.random.randint(low=0, high=25, size=(true_num_points, 2))
+        >>> pred = np.random.randint(low=0, high=25, size=(pred_num_points, 2))
+        >>> radius = 2.0
+        >>> # Example usage of f1_detection
+        >>> f1_score = f1_detection(true, pred, radius)
+
+    """
     (paired_true, unpaired_true, unpaired_pred) = pair_coordinates(true, pred, radius)
 
     tp = len(paired_true)
@@ -94,6 +123,16 @@ def dice(gt_mask: np.ndarray, pred_mask: np.ndarray) -> float:
         :class:`float`:
             An estimate of Sørensen-Dice coefficient value.
 
+    Examples:
+        >>> from tiatoolbox.utils.metrics import dice
+        >>> # Generate two random example masks; replace with your own data
+        >>> import numpy as np
+        >>> np.random.seed(6)
+        >>> gt_mask = (np.random.rand(256, 256) > 0.8).astype(np.uint8)
+        >>> pred_mask = (np.random.rand(256, 256) > 0.8).astype(np.uint8)
+        >>> # Example usage of dice
+        >>> dice_score = dice(gt_mask, pred_mask)
+
     """
     if gt_mask.shape != pred_mask.shape:
         msg = f"{'Shape mismatch between the two masks.'}"