dataeval 0.69.3__py3-none-any.whl → 0.70.0__py3-none-any.whl

dataeval/_internal/metrics/stats/labelstats.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+from typing import Any, Iterable, Mapping, TypeVar
+
+from numpy.typing import ArrayLike
+
+from dataeval._internal.interop import to_numpy
+from dataeval._internal.output import OutputMetadata, set_metadata
+
+
+@dataclass(frozen=True)
+class LabelStatsOutput(OutputMetadata):
+    """
+    Output class for `labelstats` metrics function
+
+    Attributes
+    ----------
+    label_counts_per_class : dict[str | int, int]
+        Dictionary whose keys are the different label classes and
+        values are total counts of each class
+    label_counts_per_image : list[int]
+        Number of labels per image
+    image_counts_per_label : dict[str | int, int]
+        Dictionary whose keys are the different label classes and
+        values are total counts of each image the class is present in
+    image_indices_per_label : dict[str | int, list]
+        Dictionary whose keys are the different label classes and
+        values are lists containing the images that have that label
+    image_count : int
+        Total number of images present
+    class_count : int
+        Total number of classes present
+    label_count : int
+        Total number of labels present
+    """
+
+    label_counts_per_class: dict[str | int, int]
+    label_counts_per_image: list[int]
+    image_counts_per_label: dict[str | int, int]
+    image_indices_per_label: dict[str | int, list[int]]
+    image_count: int
+    class_count: int
+    label_count: int
+
+
+TKey = TypeVar("TKey", int, str)
+
+
+def sort(d: Mapping[TKey, Any]) -> dict[TKey, Any]:
+    """
+    Sort mappings by key in increasing order
+    """
+    return dict(sorted(d.items(), key=lambda x: x[0]))
+
+
+@set_metadata("dataeval.metrics")
+def labelstats(
+    labels: Iterable[ArrayLike],
+) -> LabelStatsOutput:
+    """
+    Calculates statistics for data labels
+
+    This function computes counting metrics (e.g., total per class, total per image)
+    on the labels.
+
+    Parameters
+    ----------
+    labels : ArrayLike, shape - [label] | [[label]] or (N,M) | (N,)
+        Lists or numpy array of labels.
+        A set of lists where each list contains all labels per image -
+        (e.g. [[label1, label2], [label2], [label1, label3]] or [label1, label2, label1, label3]).
+        If a numpy array, N is the number of images, M is the number of labels per image.
+
+    Returns
+    -------
+    LabelStatsOutput
+        A dictionary-like object containing the computed counting metrics for the labels.
+
+    Examples
+    --------
+    Calculating the statistics on labels for a set of data
+
+    >>> stats = labelstats(labels)
+    >>> stats.label_counts_per_class
+    {'chicken': 3, 'cow': 8, 'horse': 9, 'pig': 7, 'sheep': 7}
+    >>> stats.label_counts_per_image
+    [3, 2, 3, 4, 1, 5, 4, 4, 4, 4]
+    >>> stats.image_counts_per_label
+    {'chicken': 2, 'cow': 6, 'horse': 7, 'pig': 5, 'sheep': 7}
+    >>> (stats.image_count, stats.class_count, stats.label_count)
+    (10, 5, 34)
+    """
+    label_counts = Counter()
+    image_counts = Counter()
+    index_location = defaultdict(list[int])
+    label_per_image: list[int] = []
+
+    for i, group in enumerate(labels):
+        # Count occurrences of each label in all sublists
+        group = to_numpy(group)
+
+        label_counts.update(group)
+
+        # Get the number of labels per image
+        label_per_image.append(len(group))
+
+        # Create a set of unique items in the current sublist
+        unique_items: set[int] = set(group)
+
+        # Update image counts and index locations
+        image_counts.update(unique_items)
+        for item in unique_items:
+            index_location[item].append(i)
+
+    return LabelStatsOutput(
+        label_counts_per_class=sort(label_counts),
+        label_counts_per_image=label_per_image,
+        image_counts_per_label=sort(image_counts),
+        image_indices_per_label=sort(index_location),
+        image_count=len(label_per_image),
+        class_count=len(label_counts),
+        label_count=sum(label_counts.values()),
+    )

dataeval/_internal/metrics/stats/pixelstats.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.stats import entropy, kurtosis, skew
+
+from dataeval._internal.metrics.stats.base import BaseStatsOutput, StatsProcessor, run_stats
+from dataeval._internal.output import set_metadata
+
+
+class PixelStatsProcessor(StatsProcessor):
+    cache_keys = ["histogram"]
+    image_function_map = {
+        "mean": lambda self: np.mean(self.scaled),
+        "std": lambda x: np.std(x.scaled),
+        "var": lambda x: np.var(x.scaled),
+        "skew": lambda x: np.nan_to_num(skew(x.scaled.ravel())),
+        "kurtosis": lambda x: np.nan_to_num(kurtosis(x.scaled.ravel())),
+        "histogram": lambda x: np.histogram(x.scaled, 256, (0, 1))[0],
+        "entropy": lambda x: entropy(x.get("histogram")),
+    }
+    channel_function_map = {
+        "mean": lambda x: np.mean(x.scaled, axis=1),
+        "std": lambda x: np.std(x.scaled, axis=1),
+        "var": lambda x: np.var(x.scaled, axis=1),
+        "skew": lambda x: np.nan_to_num(skew(x.scaled, axis=1)),
+        "kurtosis": lambda x: np.nan_to_num(kurtosis(x.scaled, axis=1)),
+        "histogram": lambda x: np.apply_along_axis(lambda y: np.histogram(y, 256, (0, 1))[0], 1, x.scaled),
+        "entropy": lambda x: entropy(x.get("histogram"), axis=1),
+    }
+
+
+@dataclass(frozen=True)
+class PixelStatsOutput(BaseStatsOutput):
+    """
+    Attributes
+    ----------
+    mean : NDArray[np.float16]
+        Mean of the pixel values of the images
+    std : NDArray[np.float16]
+        Standard deviation of the pixel values of the images
+    var : NDArray[np.float16]
+        Variance of the pixel values of the images
+    skew : NDArray[np.float16]
+        Skew of the pixel values of the images
+    kurtosis : NDArray[np.float16]
+        Kurtosis of the pixel values of the images
+    histogram : NDArray[np.uint32]
+        Histogram of the pixel values of the images across 256 bins scaled between 0 and 1
+    entropy : NDArray[np.float16]
+        Entropy of the pixel values of the images
+    """
+
+    mean: NDArray[np.float16]
+    std: NDArray[np.float16]
+    var: NDArray[np.float16]
+    skew: NDArray[np.float16]
+    kurtosis: NDArray[np.float16]
+    histogram: NDArray[np.uint32]
+    entropy: NDArray[np.float16]
+
+
+@set_metadata("dataeval.metrics")
+def pixelstats(
+    images: Iterable[ArrayLike],
+    bboxes: Iterable[ArrayLike] | None = None,
+    per_channel: bool = False,
+) -> PixelStatsOutput:
+    """
+    Calculates pixel statistics for each image
+
+    This function computes various statistical metrics (e.g., mean, standard deviation, entropy)
+    on the images as a whole.
+
+    Parameters
+    ----------
+    images : Iterable[ArrayLike]
+        Images to perform calculations on
+    bboxes : Iterable[ArrayLike] or None
+        Bounding boxes in `xyxy` format for each image to perform calculations
+
+    Returns
+    -------
+    PixelStatsOutput
+        A dictionary-like object containing the computed statistics for each image. The keys correspond
+        to the names of the statistics (e.g., 'mean', 'std'), and the values are lists of results for
+        each image or numpy arrays when the results are multi-dimensional.
+
+    See Also
+    --------
+    dimensionstats, visualstats, Outliers
+
+    Notes
+    -----
+    - All metrics are scaled based on the perceived bit depth (which is derived from the largest pixel value)
+      to allow for better comparison between images stored in different formats and different resolutions.
+
+    Examples
+    --------
+    Calculating the statistics on the images, whose shape is (C, H, W)
+
+    >>> results = pixelstats(images)
+    >>> print(results.mean)
+    [0.04828 0.562   0.06726 0.09937 0.1315  0.1636  0.1957  0.2278  0.26
+     0.292   0.3242  0.3562  0.3884  0.4204  0.4526  0.4846  0.5166  0.549
+     0.581   0.6133  0.6455  0.6772  0.7095  0.7417  0.774   0.8057  0.838
+     0.87    0.9023  0.934  ]
+    >>> print(results.entropy)
+    [3.238  3.303  0.8125 1.028  0.8223 1.046  0.8247 1.041  0.8203 1.012
+     0.812  0.9883 0.795  0.9243 0.9243 0.795  0.9907 0.8125 1.028  0.8223
+     1.046  0.8247 1.041  0.8203 1.012  0.812  0.9883 0.795  0.9243 0.9243]
+    """
+    output = run_stats(images, bboxes, per_channel, PixelStatsProcessor, PixelStatsOutput)
+    return PixelStatsOutput(**output)

dataeval/_internal/metrics/stats/visualstats.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from dataeval._internal.metrics.stats.base import BaseStatsOutput, StatsProcessor, run_stats
+from dataeval._internal.metrics.utils import edge_filter
+from dataeval._internal.output import set_metadata
+
+QUARTILES = (0, 25, 50, 75, 100)
+
+
+class VisualStatsProcessor(StatsProcessor):
+    cache_keys = ["percentiles"]
+    image_function_map = {
+        "brightness": lambda x: x.get("percentiles")[-2],
+        "blurriness": lambda x: np.std(edge_filter(np.mean(x.image, axis=0))),
+        "contrast": lambda x: np.nan_to_num(
+            (np.max(x.get("percentiles")) - np.min(x.get("percentiles"))) / np.mean(x.get("percentiles"))
+        ),
+        "darkness": lambda x: x.get("percentiles")[1],
+        "missing": lambda x: np.sum(np.isnan(x.image)) / np.prod(x.shape[-2:]),
+        "zeros": lambda x: np.count_nonzero(x.image == 0) / np.prod(x.shape[-2:]),
+        "percentiles": lambda x: np.nanpercentile(x.scaled, q=QUARTILES),
+    }
+    channel_function_map = {
+        "brightness": lambda x: x.get("percentiles")[:, -2],
+        "blurriness": lambda x: np.std(np.vectorize(edge_filter, signature="(m,n)->(m,n)")(x.image), axis=(1, 2)),
+        "contrast": lambda x: np.nan_to_num(
+            (np.max(x.get("percentiles"), axis=1) - np.min(x.get("percentiles"), axis=1))
+            / np.mean(x.get("percentiles"), axis=1)
+        ),
+        "darkness": lambda x: x.get("percentiles")[:, 1],
+        "missing": lambda x: np.sum(np.isnan(x.image), axis=(1, 2)) / np.prod(x.shape[-2:]),
+        "zeros": lambda x: np.count_nonzero(x.image == 0, axis=(1, 2)) / np.prod(x.shape[-2:]),
+        "percentiles": lambda x: np.nanpercentile(x.scaled, q=QUARTILES, axis=1).T,
+    }
+
+
+@dataclass(frozen=True)
+class VisualStatsOutput(BaseStatsOutput):
+    """
+    Attributes
+    ----------
+    brightness : NDArray[np.float16]
+        Brightness of the images
+    blurriness : NDArray[np.float16]
+        Blurriness of the images
+    contrast : NDArray[np.float16]
+        Image contrast ratio
+    darkness : NDArray[np.float16]
+        Darkness of the images
+    missing : NDArray[np.float16]
+        Percentage of the images with missing pixels
+    zeros : NDArray[np.float16]
+        Percentage of the images with zero value pixels
+    percentiles : NDArray[np.float16]
+        Percentiles of the pixel values of the images with quartiles of (0, 25, 50, 75, 100)
+    """
+
+    brightness: NDArray[np.float16]
+    blurriness: NDArray[np.float16]
+    contrast: NDArray[np.float16]
+    darkness: NDArray[np.float16]
+    missing: NDArray[np.float16]
+    zeros: NDArray[np.float16]
+    percentiles: NDArray[np.float16]
+
+
+@set_metadata("dataeval.metrics")
+def visualstats(
+    images: Iterable[ArrayLike],
+    bboxes: Iterable[ArrayLike] | None = None,
+    per_channel: bool = False,
+) -> VisualStatsOutput:
+    """
+    Calculates visual statistics for each image
+
+    This function computes various visual metrics (e.g., brightness, darkness, contrast, blurriness)
+    on the images as a whole.
+
+    Parameters
+    ----------
+    images : Iterable[ArrayLike]
+        Images to perform calculations on
+    bboxes : Iterable[ArrayLike] or None
+        Bounding boxes in `xyxy` format for each image to perform calculations on
+
+    Returns
+    -------
+    VisualStatsOutput
+        A dictionary-like object containing the computed visual statistics for each image. The keys correspond
+        to the names of the statistics (e.g., 'brightness', 'blurriness'), and the values are lists of results for
+        each image or numpy arrays when the results are multi-dimensional.
+
+    See Also
+    --------
+    dimensionstats, pixelstats, Outliers
+
+    Notes
+    -----
+    - `zeros` and `missing` are presented as a percentage of total pixel counts
+
+    Examples
+    --------
+    Calculating the statistics on the images, whose shape is (C, H, W)
+
+    >>> results = visualstats(images)
+    >>> print(results.brightness)
+    [0.0737 0.607  0.0713 0.1046 0.138  0.1713 0.2046 0.2379 0.2712 0.3047
+     0.338  0.3713 0.4045 0.438  0.4712 0.5044 0.538  0.5713 0.6045 0.638
+     0.6714 0.7046 0.738  0.7715 0.8047 0.838  0.871  0.905  0.938  0.971 ]
+    >>> print(results.contrast)
+    [2.041 1.332 1.293 1.279 1.272 1.268 1.265 1.263 1.261 1.26  1.259 1.258
+     1.258 1.257 1.257 1.256 1.256 1.255 1.255 1.255 1.255 1.254 1.254 1.254
+     1.254 1.254 1.254 1.253 1.253 1.253]
+    """
+    output = run_stats(images, bboxes, per_channel, VisualStatsProcessor, VisualStatsOutput)
+    return VisualStatsOutput(**output)

dataeval/_internal/metrics/uap.py

@@ -9,7 +9,7 @@ from dataclasses import dataclass
 from numpy.typing import ArrayLike
 from sklearn.metrics import average_precision_score
 
-from dataeval._internal.interop import to_numpy
+from dataeval._internal.interop import as_numpy
 from dataeval._internal.output import OutputMetadata, set_metadata
 
 
@@ -75,5 +75,5 @@ def uap(labels: ArrayLike, scores: ArrayLike) -> UAPOutput:
     UAPOutput(uap=0.7777777777777777)
     """
 
-    precision = float(average_precision_score(to_numpy(labels), to_numpy(scores), average="weighted"))
+    precision = float(average_precision_score(as_numpy(labels), as_numpy(scores), average="weighted"))
     return UAPOutput(precision)

dataeval/_internal/metrics/utils.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-from typing import Any, Callable, Literal, NamedTuple, Sequence
+from typing import Any, Callable, Literal, Mapping, NamedTuple
 
 import numpy as np
 import xxhash as xxh
-from numpy.typing import NDArray
+from numpy.typing import ArrayLike, NDArray
 from PIL import Image
 from scipy.fftpack import dct
 from scipy.signal import convolve2d
@@ -14,6 +14,8 @@ from scipy.spatial.distance import pdist, squareform
 from scipy.stats import entropy as sp_entropy
 from sklearn.neighbors import NearestNeighbors
 
+from dataeval._internal.interop import to_numpy
+
 EPSILON = 1e-5
 EDGE_KERNEL = np.array([[-1, -1, -1], [-1, 8, -1], [-1, -1, -1]], dtype=np.int8)
 BIT_DEPTH = (1, 8, 12, 16, 32)
@@ -162,26 +164,26 @@ def infer_categorical(X: NDArray, threshold: float = 0.2) -> NDArray:
 
 
 def preprocess_metadata(
-    class_labels: Sequence[int], metadata: list[dict], cat_thresh: float = 0.2
+    class_labels: ArrayLike, metadata: Mapping[str, ArrayLike], cat_thresh: float = 0.2
 ) -> tuple[NDArray, list[str], list[bool]]:
-    # convert class_labels and list of metadata dicts to dict of ndarrays
-    metadata_dict: dict[str, NDArray] = {
-        "class_label": np.asarray(class_labels, dtype=int),
-        **{k: np.array([d[k] for d in metadata]) for k in metadata[0]},
-    }
+    # convert class_labels and dict of lists to matrix of metadata values
+    preprocessed_metadata = {"class_label": np.asarray(class_labels, dtype=int)}
 
     # map columns of dict that are not numeric (e.g. string) to numeric values
     # that mutual information and diversity functions can accommodate.  Each
     # unique string receives a unique integer value.
-    for k, v in metadata_dict.items():
+    for k, v in metadata.items():
         # if not numeric
+        v = to_numpy(v)
         if not np.issubdtype(v.dtype, np.number):
             _, mapped_vals = np.unique(v, return_inverse=True)
-            metadata_dict[k] = mapped_vals
+            preprocessed_metadata[k] = mapped_vals
+        else:
+            preprocessed_metadata[k] = v
 
-    data = np.stack(list(metadata_dict.values()), axis=-1)
-    names = list(metadata_dict.keys())
-    is_categorical = [infer_categorical(metadata_dict[var], cat_thresh)[0] for var in names]
+    data = np.stack(list(preprocessed_metadata.values()), axis=-1)
+    names = list(preprocessed_metadata.keys())
+    is_categorical = [infer_categorical(preprocessed_metadata[var], cat_thresh)[0] for var in names]
 
     return data, names, is_categorical
 
@@ -350,6 +352,19 @@ def normalize_image_shape(image: NDArray) -> NDArray:
         raise ValueError("Images must have 2 or more dimensions.")
 
 
+def normalize_box_shape(bounding_box: NDArray) -> NDArray:
+    """
+    Normalizes the bounding box shape into (N,4).
+    """
+    ndim = bounding_box.ndim
+    if ndim == 1:
+        return np.expand_dims(bounding_box, axis=0)
+    elif ndim > 2:
+        raise ValueError("Bounding boxes must have 2 dimensions: (# of boxes in an image, [X,Y,W,H]) -> (N,4)")
+    else:
+        return bounding_box
+
+
 def edge_filter(image: NDArray, offset: float = 0.5) -> NDArray:
     """
     Returns the image filtered using a 3x3 edge detection kernel:

dataeval/_internal/output.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import inspect
 from datetime import datetime, timezone
 from functools import wraps
+from typing import Any
 
 import numpy as np
 
@@ -17,10 +18,10 @@ class OutputMetadata:
     _state: dict[str, str]
     _version: str
 
-    def dict(self) -> dict:
+    def dict(self) -> dict[str, Any]:
         return {k: v for k, v in self.__dict__.items() if not k.startswith("_")}
 
-    def meta(self) -> dict:
+    def meta(self) -> dict[str, Any]:
         return {k.removeprefix("_"): v for k, v in self.__dict__.items() if k.startswith("_")}
 
 
@@ -67,19 +68,3 @@ def set_metadata(module_name: str = "", state_attr: list[str] | None = None):
         return wrapper
 
     return decorator
-
-
-def populate_defaults(d: dict, c: type) -> dict:
-    def default(t):
-        t = (
-            t if isinstance(t, str) else t._name if hasattr(t, "_name") else t.__name__
-        ).lower()  # py3.9 : _name, py3.10 : __name__
-        if t.startswith("dict"):
-            return {}
-        if t.startswith("list"):
-            return []
-        if t.startswith("ndarray"):
-            return np.array([])
-        raise TypeError("Unrecognized annotation type")
-
-    return {k: d[k] if k in d else default(t) for k, t in c.__annotations__.items()}