valor-lite 0.33.7__py3-none-any.whl → 0.33.8__py3-none-any.whl

valor_lite/classification/metric.py

@@ -35,7 +35,7 @@ class Counts:
     tn: list[int]
     score_thresholds: list[float]
     hardmax: bool
-    label: tuple[str, str]
+    label: str
 
     @property
     def metric(self) -> Metric:
@@ -50,10 +50,7 @@ class Counts:
             parameters={
                 "score_thresholds": self.score_thresholds,
                 "hardmax": self.hardmax,
-                "label": {
-                    "key": self.label[0],
-                    "value": self.label[1],
-                },
+                "label": self.label,
             },
         )
 
@@ -66,7 +63,7 @@ class _ThresholdValue:
     value: list[float]
     score_thresholds: list[float]
     hardmax: bool
-    label: tuple[str, str]
+    label: str
 
     @property
     def metric(self) -> Metric:
@@ -76,10 +73,7 @@ class _ThresholdValue:
             parameters={
                 "score_thresholds": self.score_thresholds,
                 "hardmax": self.hardmax,
-                "label": {
-                    "key": self.label[0],
-                    "value": self.label[1],
-                },
+                "label": self.label,
             },
         )
 
@@ -106,19 +100,14 @@ class F1(_ThresholdValue):
 @dataclass
 class ROCAUC:
     value: float
-    label: tuple[str, str]
+    label: str
 
     @property
     def metric(self) -> Metric:
         return Metric(
             type=type(self).__name__,
             value=self.value,
-            parameters={
-                "label": {
-                    "key": self.label[0],
-                    "value": self.label[1],
-                },
-            },
+            parameters={"label": self.label},
         )
 
     def to_dict(self) -> dict:
@@ -128,16 +117,13 @@ class ROCAUC:
 @dataclass
 class mROCAUC:
     value: float
-    label_key: str
 
     @property
     def metric(self) -> Metric:
         return Metric(
             type=type(self).__name__,
             value=self.value,
-            parameters={
-                "label_key": self.label_key,
-            },
+            parameters={},
         )
 
     def to_dict(self) -> dict:
@@ -170,7 +156,6 @@ class ConfusionMatrix:
         ],
     ]
     score_threshold: float
-    label_key: str
     number_of_examples: int
 
     @property
@@ -183,7 +168,6 @@ class ConfusionMatrix:
             },
             parameters={
                 "score_threshold": self.score_threshold,
-                "label_key": self.label_key,
             },
         )
 

valor_lite/detection/annotation.py

@@ -11,10 +11,14 @@ class BoundingBox:
     xmax: float
     ymin: float
     ymax: float
-    labels: list[tuple[str, str]]
+    labels: list[str]
     scores: list[float] = field(default_factory=list)
 
     def __post_init__(self):
+        if len(self.scores) == 0 and len(self.labels) != 1:
+            raise ValueError(
+                "Ground truths must be defined with no scores and a single label. If you meant to define a prediction, then please include one score for every label provided."
+            )
         if len(self.scores) > 0 and len(self.labels) != len(self.scores):
             raise ValueError(
                 "If scores are defined, there must be a 1:1 pairing with labels."
@@ -22,66 +26,97 @@ class BoundingBox:
 
     @property
     def extrema(self) -> tuple[float, float, float, float]:
+        """
+        Returns annotation extrema in the form (xmin, xmax, ymin, ymax).
+        """
         return (self.xmin, self.xmax, self.ymin, self.ymax)
 
+    @property
+    def annotation(self) -> tuple[float, float, float, float]:
+        """
+        Returns the annotation's data representation.
+        """
+        return self.extrema
+
 
 @dataclass
 class Polygon:
     shape: ShapelyPolygon
-    labels: list[tuple[str, str]]
+    labels: list[str]
     scores: list[float] = field(default_factory=list)
 
     def __post_init__(self):
         if not isinstance(self.shape, ShapelyPolygon):
             raise TypeError("shape must be of type shapely.geometry.Polygon.")
+        if self.shape.is_empty:
+            raise ValueError("Polygon is empty.")
+
+        if len(self.scores) == 0 and len(self.labels) != 1:
+            raise ValueError(
+                "Ground truths must be defined with no scores and a single label. If you meant to define a prediction, then please include one score for every label provided."
+            )
         if len(self.scores) > 0 and len(self.labels) != len(self.scores):
             raise ValueError(
                 "If scores are defined, there must be a 1:1 pairing with labels."
             )
 
-    def to_box(self) -> BoundingBox | None:
-
-        if self.shape.is_empty:
-            return None
-
+    @property
+    def extrema(self) -> tuple[float, float, float, float]:
+        """
+        Returns annotation extrema in the form (xmin, xmax, ymin, ymax).
+        """
         xmin, ymin, xmax, ymax = self.shape.bounds
+        return (xmin, xmax, ymin, ymax)
 
-        return BoundingBox(
-            xmin=xmin,
-            xmax=xmax,
-            ymin=ymin,
-            ymax=ymax,
-            labels=self.labels,
-            scores=self.scores,
-        )
+    @property
+    def annotation(self) -> ShapelyPolygon:
+        """
+        Returns the annotation's data representation.
+        """
+        return self.shape
 
 
 @dataclass
 class Bitmask:
     mask: NDArray[np.bool_]
-    labels: list[tuple[str, str]]
+    labels: list[str]
     scores: list[float] = field(default_factory=list)
 
     def __post_init__(self):
+
+        if (
+            not isinstance(self.mask, np.ndarray)
+            or self.mask.dtype != np.bool_
+        ):
+            raise ValueError(
+                "Expected mask to be of type `NDArray[np.bool_]`."
+            )
+        elif not self.mask.any():
+            raise ValueError("Mask does not define any object instances.")
+
+        if len(self.scores) == 0 and len(self.labels) != 1:
+            raise ValueError(
+                "Ground truths must be defined with no scores and a single label. If you meant to define a prediction, then please include one score for every label provided."
+            )
         if len(self.scores) > 0 and len(self.labels) != len(self.scores):
             raise ValueError(
                 "If scores are defined, there must be a 1:1 pairing with labels."
             )
 
-    def to_box(self) -> BoundingBox | None:
-
-        if not self.mask.any():
-            return None
-
+    @property
+    def extrema(self) -> tuple[float, float, float, float]:
+        """
+        Returns annotation extrema in the form (xmin, xmax, ymin, ymax).
+        """
         rows, cols = np.nonzero(self.mask)
-        return BoundingBox(
-            xmin=cols.min(),
-            xmax=cols.max(),
-            ymin=rows.min(),
-            ymax=rows.max(),
-            labels=self.labels,
-            scores=self.scores,
-        )
+        return (cols.min(), cols.max(), rows.min(), rows.max())
+
+    @property
+    def annotation(self) -> NDArray[np.bool_]:
+        """
+        Returns the annotation's data representation.
+        """
+        return self.mask
 
 
 @dataclass

valor_lite/detection/computation.py

@@ -1,8 +1,9 @@
 import numpy as np
+import shapely
 from numpy.typing import NDArray
 
 
-def compute_bbox_iou(data: NDArray[np.floating]) -> NDArray[np.floating]:
+def compute_bbox_iou(data: NDArray[np.float64]) -> NDArray[np.float64]:
     """
     Computes intersection-over-union (IoU) for axis-aligned bounding boxes.
 
@@ -23,26 +24,30 @@ def compute_bbox_iou(data: NDArray[np.floating]) -> NDArray[np.floating]:
 
     Parameters
     ----------
-    data : NDArray[np.floating]
+    data : NDArray[np.float64]
         A sorted array of bounding box pairs.
 
     Returns
     -------
-    NDArray[np.floating]
+    NDArray[np.float64]
         Computed IoU's.
     """
+    if data.size == 0:
+        return np.array([], dtype=np.float64)
+
+    n_pairs = data.shape[0]
 
     xmin1, xmax1, ymin1, ymax1 = (
-        data[:, 0],
-        data[:, 1],
-        data[:, 2],
-        data[:, 3],
+        data[:, 0, 0],
+        data[:, 0, 1],
+        data[:, 0, 2],
+        data[:, 0, 3],
     )
     xmin2, xmax2, ymin2, ymax2 = (
-        data[:, 4],
-        data[:, 5],
-        data[:, 6],
-        data[:, 7],
+        data[:, 1, 0],
+        data[:, 1, 1],
+        data[:, 1, 2],
+        data[:, 1, 3],
     )
 
     xmin = np.maximum(xmin1, xmin2)
@@ -59,15 +64,17 @@ def compute_bbox_iou(data: NDArray[np.floating]) -> NDArray[np.floating]:
 
     union_area = area1 + area2 - intersection_area
 
-    iou = np.zeros(data.shape[0])
-    valid_union_mask = union_area >= 1e-9
-    iou[valid_union_mask] = (
-        intersection_area[valid_union_mask] / union_area[valid_union_mask]
+    ious = np.zeros(n_pairs, dtype=np.float64)
+    np.divide(
+        intersection_area,
+        union_area,
+        where=union_area >= 1e-9,
+        out=ious,
     )
-    return iou
+    return ious
 
 
-def compute_bitmask_iou(data: NDArray[np.floating]) -> NDArray[np.floating]:
+def compute_bitmask_iou(data: NDArray[np.bool_]) -> NDArray[np.float64]:
     """
     Computes intersection-over-union (IoU) for bitmasks.
 
@@ -82,23 +89,41 @@ def compute_bitmask_iou(data: NDArray[np.floating]) -> NDArray[np.floating]:
 
     Parameters
     ----------
-    data : NDArray[np.floating]
+    data : NDArray[np.float64]
         A sorted array of bitmask pairs.
 
     Returns
     -------
-    NDArray[np.floating]
+    NDArray[np.float64]
         Computed IoU's.
     """
-    intersection_ = np.array([np.logical_and(x, y).sum() for x, y in data])
-    union_ = np.array([np.logical_or(x, y).sum() for x, y in data])
 
-    return intersection_ / union_
+    if data.size == 0:
+        return np.array([], dtype=np.float64)
+
+    n_pairs = data.shape[0]
+    lhs = data[:, 0, :, :].reshape(n_pairs, -1)
+    rhs = data[:, 1, :, :].reshape(n_pairs, -1)
+
+    lhs_sum = lhs.sum(axis=1)
+    rhs_sum = rhs.sum(axis=1)
+
+    intersection_ = np.logical_and(lhs, rhs).sum(axis=1)
+    union_ = lhs_sum + rhs_sum - intersection_
+
+    ious = np.zeros(n_pairs, dtype=np.float64)
+    np.divide(
+        intersection_,
+        union_,
+        where=union_ >= 1e-9,
+        out=ious,
+    )
+    return ious
 
 
 def compute_polygon_iou(
-    data: NDArray[np.floating],
-) -> NDArray[np.floating]:
+    data: NDArray[np.float64],
+) -> NDArray[np.float64]:
     """
     Computes intersection-over-union (IoU) for shapely polygons.
 
@@ -113,31 +138,43 @@ def compute_polygon_iou(
 
     Parameters
     ----------
-    data : NDArray[np.floating]
+    data : NDArray[np.float64]
         A sorted array of polygon pairs.
 
     Returns
     -------
-    NDArray[np.floating]
+    NDArray[np.float64]
         Computed IoU's.
     """
-    intersection_ = np.array(
-        [poly1.intersection(poly2).area for poly1, poly2 in data]
-    )
-    union_ = np.array(
-        [
-            poly1.area + poly2.area - intersection_[i]
-            for i, (poly1, poly2) in enumerate(data)
-        ]
-    )
 
-    return intersection_ / union_
+    if data.size == 0:
+        return np.array([], dtype=np.float64)
+
+    n_pairs = data.shape[0]
+
+    lhs = data[:, 0]
+    rhs = data[:, 1]
+
+    intersections = shapely.intersection(lhs, rhs)
+    intersection_areas = shapely.area(intersections)
+
+    unions = shapely.union(lhs, rhs)
+    union_areas = shapely.area(unions)
+
+    ious = np.zeros(n_pairs, dtype=np.float64)
+    np.divide(
+        intersection_areas,
+        union_areas,
+        where=union_areas >= 1e-9,
+        out=ious,
+    )
+    return ious
 
 
 def _compute_ranked_pairs_for_datum(
-    data: NDArray[np.floating],
+    data: NDArray[np.float64],
     label_metadata: NDArray[np.int32],
-) -> NDArray[np.floating]:
+) -> NDArray[np.float64]:
     """
     Computes ranked pairs for a datum.
     """
@@ -177,9 +214,9 @@ def _compute_ranked_pairs_for_datum(
 
 
 def compute_ranked_pairs(
-    data: list[NDArray[np.floating]],
+    data: list[NDArray[np.float64]],
     label_metadata: NDArray[np.int32],
-) -> NDArray[np.floating]:
+) -> NDArray[np.float64]:
     """
     Performs pair ranking on input data.
 
@@ -197,14 +234,14 @@ def compute_ranked_pairs(
 
     Parameters
     ----------
-    data : NDArray[np.floating]
+    data : NDArray[np.float64]
         A sorted array summarizing the IOU calculations of one or more pairs.
     label_metadata : NDArray[np.int32]
         An array containing metadata related to labels.
 
     Returns
     -------
-    NDArray[np.floating]
+    NDArray[np.float64]
         A filtered array containing only ranked pairs.
     """
 
@@ -226,25 +263,25 @@ def compute_ranked_pairs(
 
 
 def compute_metrics(
-    data: NDArray[np.floating],
+    data: NDArray[np.float64],
     label_metadata: NDArray[np.int32],
-    iou_thresholds: NDArray[np.floating],
-    score_thresholds: NDArray[np.floating],
+    iou_thresholds: NDArray[np.float64],
+    score_thresholds: NDArray[np.float64],
 ) -> tuple[
     tuple[
-        NDArray[np.floating],
-        NDArray[np.floating],
-        NDArray[np.floating],
-        NDArray[np.floating],
+        NDArray[np.float64],
+        NDArray[np.float64],
+        NDArray[np.float64],
+        float,
     ],
     tuple[
-        NDArray[np.floating],
-        NDArray[np.floating],
-        NDArray[np.floating],
-        NDArray[np.floating],
+        NDArray[np.float64],
+        NDArray[np.float64],
+        NDArray[np.float64],
+        float,
     ],
-    NDArray[np.floating],
-    NDArray[np.floating],
+    NDArray[np.float64],
+    NDArray[np.float64],
 ]:
     """
     Computes Object Detection metrics.
@@ -261,20 +298,20 @@ def compute_metrics(
 
     Parameters
     ----------
-    data : NDArray[np.floating]
+    data : NDArray[np.float64]
         A sorted array summarizing the IOU calculations of one or more pairs.
     label_metadata : NDArray[np.int32]
         An array containing metadata related to labels.
-    iou_thresholds : NDArray[np.floating]
+    iou_thresholds : NDArray[np.float64]
         A 1-D array containing IoU thresholds.
-    score_thresholds : NDArray[np.floating]
+    score_thresholds : NDArray[np.float64]
         A 1-D array containing score thresholds.
 
     Returns
     -------
-    tuple[NDArray, NDArray, NDArray NDArray]
+    tuple[NDArray, NDArray, NDArray, float]
         Average Precision results.
-    tuple[NDArray, NDArray, NDArray NDArray]
+    tuple[NDArray, NDArray, NDArray, float]
         Average Recall results.
     np.ndarray
         Precision, Recall, TP, FP, FN, F1 Score, Accuracy.
@@ -287,6 +324,11 @@ def compute_metrics(
     n_ious = iou_thresholds.shape[0]
     n_scores = score_thresholds.shape[0]
 
+    if n_ious == 0:
+        raise ValueError("At least one IoU threshold must be passed.")
+    elif n_scores == 0:
+        raise ValueError("At least one score threshold must be passed.")
+
     average_precision = np.zeros((n_ious, n_labels))
     average_recall = np.zeros((n_scores, n_labels))
     counts = np.zeros((n_ious, n_scores, n_labels, 7))
@@ -450,26 +492,23 @@ def compute_metrics(
     average_precision = average_precision / 101.0
 
     # calculate average recall
-    average_recall /= n_ious
+    average_recall = average_recall / n_ious
 
     # calculate mAP and mAR
-    label_key_mapping = label_metadata[unique_pd_labels, 2]
-    label_keys = np.unique(label_metadata[:, 2])
-    mAP = np.ones((n_ious, label_keys.shape[0])) * -1.0
-    mAR = np.ones((n_scores, label_keys.shape[0])) * -1.0
-    for key in np.unique(label_key_mapping):
-        labels = unique_pd_labels[label_key_mapping == key]
-        key_idx = int(key)
-        mAP[:, key_idx] = average_precision[:, labels].mean(axis=1)
-        mAR[:, key_idx] = average_recall[:, labels].mean(axis=1)
-
-    # calculate AP and mAP averaged over iou thresholds
+    if unique_pd_labels.size > 0:
+        mAP = average_precision[:, unique_pd_labels].mean(axis=1)
+        mAR = average_recall[:, unique_pd_labels].mean(axis=1)
+    else:
+        mAP = np.zeros(n_ious, dtype=np.float64)
+        mAR = np.zeros(n_scores, dtype=np.float64)
+
+    # calculate AR and AR averaged over thresholds
     APAveragedOverIoUs = average_precision.mean(axis=0)
-    mAPAveragedOverIoUs = mAP.mean(axis=0)
+    ARAveragedOverScores = average_recall.mean(axis=0)
 
-    # calculate AR and mAR averaged over score thresholds
-    ARAveragedOverIoUs = average_recall.mean(axis=0)
-    mARAveragedOverIoUs = mAR.mean(axis=0)
+    # calculate mAP and mAR averaged over thresholds
+    mAPAveragedOverIoUs = mAP.mean(axis=0)
+    mARAveragedOverScores = mAR.mean(axis=0)
 
     ap_results = (
         average_precision,
@@ -480,8 +519,8 @@ def compute_metrics(
     ar_results = (
         average_recall,
         mAR,
-        ARAveragedOverIoUs,
-        mARAveragedOverIoUs,
+        ARAveragedOverScores,
+        mARAveragedOverScores,
     )
 
     return (
@@ -493,16 +532,16 @@ def compute_metrics(
 
 
 def _count_with_examples(
-    data: NDArray[np.floating],
+    data: NDArray[np.float64],
     unique_idx: int | list[int],
     label_idx: int | list[int],
-) -> tuple[NDArray[np.floating], NDArray[np.int32], NDArray[np.int32]]:
+) -> tuple[NDArray[np.float64], NDArray[np.int32], NDArray[np.int32]]:
     """
     Helper function for counting occurences of unique detailed pairs.
 
     Parameters
     ----------
-    data : NDArray[np.floating]
+    data : NDArray[np.float64]
         A masked portion of a detailed pairs array.
     unique_idx : int | list[int]
         The index or indices upon which uniqueness is constrained.
@@ -511,7 +550,7 @@ def _count_with_examples(
 
     Returns
     -------
-    NDArray[np.floating]
+    NDArray[np.float64]
         Examples drawn from the data input.
     NDArray[np.int32]
         Unique label indices.
@@ -531,13 +570,12 @@ def _count_with_examples(
 
 
 def compute_confusion_matrix(
-    data: NDArray[np.floating],
+    data: NDArray[np.float64],
     label_metadata: NDArray[np.int32],
-    iou_thresholds: NDArray[np.floating],
-    score_thresholds: NDArray[np.floating],
+    iou_thresholds: NDArray[np.float64],
+    score_thresholds: NDArray[np.float64],
     n_examples: int,
-) -> tuple[NDArray[np.floating], NDArray[np.floating], NDArray[np.int32]]:
-
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.int32]]:
     """
     Compute detailed counts.
 
@@ -553,22 +591,22 @@ def compute_confusion_matrix(
 
     Parameters
     ----------
-    data : NDArray[np.floating]
+    data : NDArray[np.float64]
         A sorted array summarizing the IOU calculations of one or more pairs.
     label_metadata : NDArray[np.int32]
         An array containing metadata related to labels.
-    iou_thresholds : NDArray[np.floating]
+    iou_thresholds : NDArray[np.float64]
         A 1-D array containing IoU thresholds.
-    score_thresholds : NDArray[np.floating]
+    score_thresholds : NDArray[np.float64]
         A 1-D array containing score thresholds.
     n_examples : int
         The maximum number of examples to return per count.
 
     Returns
     -------
-    NDArray[np.floating]
+    NDArray[np.float64]
         Confusion matrix.
-    NDArray[np.floating]
+    NDArray[np.float64]
         Hallucinations.
     NDArray[np.int32]
         Missing Predictions.