dataeval 0.76.1__py3-none-any.whl → 0.82.0__py3-none-any.whl

dataeval/utils/{image.py → _image.py}

@@ -2,17 +2,19 @@ from __future__ import annotations
 
 __all__ = []
 
-from typing import Any, NamedTuple
+from dataclasses import dataclass
+from typing import Any
 
 import numpy as np
-from numpy.typing import ArrayLike, NDArray
+from numpy.typing import NDArray
 from scipy.signal import convolve2d
 
 EDGE_KERNEL = np.array([[-1, -1, -1], [-1, 8, -1], [-1, -1, -1]], dtype=np.int8)
 BIT_DEPTH = (1, 8, 12, 16, 32)
 
 
-class BitDepth(NamedTuple):
+@dataclass
+class BitDepth:
     depth: int
     pmin: float | int
     pmax: float | int
@@ -59,7 +61,7 @@ def normalize_image_shape(image: NDArray[Any]) -> NDArray[Any]:
         raise ValueError("Images must have 2 or more dimensions.")
 
 
-def edge_filter(image: ArrayLike, offset: float = 0.5) -> NDArray[np.uint8]:
+def edge_filter(image: NDArray[Any], offset: float = 0.5) -> NDArray[np.uint8]:
     """
     Returns the image filtered using a 3x3 edge detection kernel:
     [[ -1, -1, -1 ],

dataeval/utils/_method.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Callable, TypeVar
+
+from typing_extensions import ParamSpec
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def get_method(method_map: dict[str, Callable[P, R]], method: str) -> Callable[P, R]:
+    if method not in method_map:
+        raise ValueError(f"Specified method {method} is not a valid method: {method_map}.")
+    return method_map[method]

dataeval/utils/{shared.py → _mst.py}

@@ -2,53 +2,17 @@ from __future__ import annotations
 
 __all__ = []
 
-import sys
-from typing import Any, Callable, Literal, TypeVar
+from typing import Any, Literal
 
-import numpy as np
-from numpy.typing import ArrayLike, NDArray
+from numpy.typing import NDArray
 from scipy.sparse import csr_matrix
 from scipy.sparse.csgraph import minimum_spanning_tree as mst
 from scipy.spatial.distance import pdist, squareform
 from sklearn.neighbors import NearestNeighbors
 
-if sys.version_info >= (3, 10):
-    from typing import ParamSpec
-else:
-    from typing_extensions import ParamSpec
-
-from dataeval.interop import as_numpy
+from dataeval.utils._array import flatten
 
 EPSILON = 1e-5
-HASH_SIZE = 8
-MAX_FACTOR = 4
-
-
-P = ParamSpec("P")
-R = TypeVar("R")
-
-
-def get_method(method_map: dict[str, Callable[P, R]], method: str) -> Callable[P, R]:
-    if method not in method_map:
-        raise ValueError(f"Specified method {method} is not a valid method: {method_map}.")
-    return method_map[method]
-
-
-def flatten(array: ArrayLike) -> NDArray[Any]:
-    """
-    Flattens input array from (N, ... ) to (N, -1) where all samples N have all data in their last dimension
-
-    Parameters
-    ----------
-    X : NDArray, shape - (N, ... )
-        Input array
-
-    Returns
-    -------
-    NDArray, shape - (N, -1)
-    """
-    nparr = as_numpy(array)
-    return nparr.reshape((nparr.shape[0], -1))
 
 
 def minimum_spanning_tree(X: NDArray[Any]) -> Any:
@@ -73,32 +37,6 @@ def minimum_spanning_tree(X: NDArray[Any]) -> Any:
     return mst(eudist_csr)
 
 
-def get_classes_counts(labels: NDArray[np.int_]) -> tuple[int, int]:
-    """
-    Returns the classes and counts of from an array of labels
-
-    Parameters
-    ----------
-    label : NDArray
-        Numpy labels array
-
-    Returns
-    -------
-        Classes and counts
-
-    Raises
-    ------
-    ValueError
-        If the number of unique classes is less than 2
-    """
-    classes, counts = np.unique(labels, return_counts=True)
-    M = len(classes)
-    if M < 2:
-        raise ValueError("Label vector contains less than 2 classes!")
-    N = int(np.sum(counts))
-    return M, N
-
-
 def compute_neighbors(
     A: NDArray[Any],
     B: NDArray[Any],

dataeval/utils/{plot.py → _plot.py}

@@ -6,9 +6,9 @@ import contextlib
 from typing import Any
 
 import numpy as np
-from numpy.typing import ArrayLike
 
-from dataeval.interop import to_numpy
+from dataeval.typing import ArrayLike
+from dataeval.utils._array import to_numpy
 
 with contextlib.suppress(ImportError):
     from matplotlib.figure import Figure
@@ -49,8 +49,8 @@ def heatmap(
     from matplotlib.ticker import FuncFormatter
 
     np_data = to_numpy(data)
-    rows = row_labels if isinstance(row_labels, list) else to_numpy(row_labels)
-    cols = col_labels if isinstance(col_labels, list) else to_numpy(col_labels)
+    rows: list[str] = [str(n) for n in to_numpy(row_labels)]
+    cols: list[str] = [str(n) for n in to_numpy(col_labels)]
 
     fig, ax = plt.subplots(figsize=(10, 10))
 
@@ -171,7 +171,7 @@ def histogram_plot(
         data_dict,
     ):
         # Plot the histogram for the chosen metric
-        ax.hist(data_dict[metric], bins=20, log=log)
+        ax.hist(data_dict[metric].astype(np.float64), bins=20, log=log)
 
         # Add labels to the histogram
         ax.set_title(metric)
@@ -229,7 +229,7 @@ def channel_histogram_plot(
         # Plot the histogram for the chosen metric
         data = data_dict[metric][ch_mask].reshape(-1, max_channels)
         ax.hist(
-            data,
+            data.astype(np.float64),
             bins=20,
             density=True,
             log=log,

dataeval/utils/data/__init__.py

@@ -0,0 +1,26 @@
+"""Provides utility functions for interacting with Computer Vision datasets."""
+
+__all__ = [
+    "collate",
+    "datasets",
+    "Embeddings",
+    "Images",
+    "Metadata",
+    "Select",
+    "SplitDatasetOutput",
+    "Targets",
+    "split_dataset",
+    "to_image_classification_dataset",
+    "to_object_detection_dataset",
+]
+
+from dataeval.outputs._utils import SplitDatasetOutput
+from dataeval.utils.data._dataset import to_image_classification_dataset, to_object_detection_dataset
+from dataeval.utils.data._embeddings import Embeddings
+from dataeval.utils.data._images import Images
+from dataeval.utils.data._metadata import Metadata
+from dataeval.utils.data._selection import Select
+from dataeval.utils.data._split import split_dataset
+from dataeval.utils.data._targets import Targets
+
+from . import collate, datasets

dataeval/utils/data/_dataset.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+__all__ = []
+
+from typing import Any, Generic, Iterable, Literal, Sequence, TypeVar
+
+from dataeval.typing import (
+    Array,
+    ArrayLike,
+    DatasetMetadata,
+    ImageClassificationDataset,
+    ObjectDetectionDataset,
+)
+from dataeval.utils._array import as_numpy
+
+
+def _validate_data(
+    datum_type: Literal["ic", "od"],
+    images: Array | Sequence[Array],
+    labels: Sequence[int] | Sequence[Sequence[int]],
+    bboxes: Sequence[Sequence[Sequence[float]]] | None,
+    metadata: Sequence[dict[str, Any]] | None,
+) -> None:
+    # Validate inputs
+    dataset_len = len(images)
+
+    if not isinstance(images, (Sequence, Array)) or len(images[0].shape) != 3:
+        raise ValueError("Images must be a sequence or array of 3 dimensional arrays (H, W, C).")
+    if len(labels) != dataset_len:
+        raise ValueError(f"Number of labels ({len(labels)}) does not match number of images ({dataset_len}).")
+    if bboxes is not None and len(bboxes) != dataset_len:
+        raise ValueError(f"Number of bboxes ({len(bboxes)}) does not match number of images ({dataset_len}).")
+    if metadata is not None and len(metadata) != dataset_len:
+        raise ValueError(f"Number of metadata ({len(metadata)}) does not match number of images ({dataset_len}).")
+
+    if datum_type == "ic":
+        if not isinstance(labels, Sequence) or not isinstance(labels[0], int):
+            raise TypeError("Labels must be a sequence of integers for image classification.")
+    elif datum_type == "od":
+        if not isinstance(labels, Sequence) or not isinstance(labels[0], Sequence) or not isinstance(labels[0][0], int):
+            raise TypeError("Labels must be a sequence of sequences of integers for object detection.")
+        if (
+            bboxes is None
+            or not isinstance(bboxes, (Sequence, Array))
+            or not isinstance(bboxes[0], (Sequence, Array))
+            or not isinstance(bboxes[0][0], (Sequence, Array))
+            or not len(bboxes[0][0]) == 4
+        ):
+            raise TypeError("Boxes must be a sequence of sequences of (x0, y0, x1, y1) for object detection.")
+
+
+def _find_max(arr: ArrayLike) -> Any:
+    if isinstance(arr[0], (Iterable, Sequence, Array)):
+        return max([_find_max(x) for x in arr])  # type: ignore
+    else:
+        return max(arr)
+
+
+_TLabels = TypeVar("_TLabels", Sequence[int], Sequence[Sequence[int]])
+
+
+class BaseAnnotatedDataset(Generic[_TLabels]):
+    def __init__(
+        self,
+        datum_type: Literal["ic", "od"],
+        images: Array | Sequence[Array],
+        labels: _TLabels,
+        metadata: Sequence[dict[str, Any]] | None,
+        classes: Sequence[str] | None,
+        name: str | None = None,
+    ) -> None:
+        self._classes = classes if classes is not None else [str(i) for i in range(_find_max(labels) + 1)]
+        self._index2label = dict(enumerate(self._classes))
+        self._images = images
+        self._labels = labels
+        self._metadata = metadata
+        self._id = name or f"{len(self._images)}_image_{len(self._index2label)}_class_{datum_type}_dataset"
+
+    @property
+    def metadata(self) -> DatasetMetadata:
+        return DatasetMetadata(id=self._id, index2label=self._index2label)
+
+    def __len__(self) -> int:
+        return len(self._images)
+
+
+class CustomImageClassificationDataset(BaseAnnotatedDataset[Sequence[int]], ImageClassificationDataset):
+    def __init__(
+        self,
+        images: Array | Sequence[Array],
+        labels: Sequence[int],
+        metadata: Sequence[dict[str, Any]] | None,
+        classes: Sequence[str] | None,
+        name: str | None = None,
+    ) -> None:
+        super().__init__("ic", images, labels, metadata, classes)
+        if name is not None:
+            self.__name__ = name
+            self.__class__.__name__ = name
+            self.__class__.__qualname__ = name
+
+    def __getitem__(self, idx: int, /) -> tuple[Array, Array, dict[str, Any]]:
+        one_hot = [0.0] * len(self._index2label)
+        one_hot[self._labels[idx]] = 1.0
+        return (
+            self._images[idx],
+            as_numpy(one_hot),
+            self._metadata[idx] if self._metadata is not None else {},
+        )
+
+
+class CustomObjectDetectionDataset(BaseAnnotatedDataset[Sequence[Sequence[int]]], ObjectDetectionDataset):
+    class ObjectDetectionTarget:
+        def __init__(self, labels: Sequence[int], bboxes: Sequence[Sequence[float]]) -> None:
+            self._labels = labels
+            self._bboxes = bboxes
+            self._scores = [1.0] * len(labels)
+
+        @property
+        def labels(self) -> Sequence[int]:
+            return self._labels
+
+        @property
+        def boxes(self) -> Sequence[Sequence[float]]:
+            return self._bboxes
+
+        @property
+        def scores(self) -> Sequence[float]:
+            return self._scores
+
+    def __init__(
+        self,
+        images: Array | Sequence[Array],
+        labels: Sequence[Sequence[int]],
+        bboxes: Sequence[Sequence[Sequence[float]]],
+        metadata: Sequence[dict[str, Any]] | None,
+        classes: Sequence[str] | None,
+        name: str | None = None,
+    ) -> None:
+        super().__init__("od", images, labels, metadata, classes)
+        if name is not None:
+            self.__name__ = name
+            self.__class__.__name__ = name
+            self.__class__.__qualname__ = name
+        self._bboxes = bboxes
+
+    @property
+    def metadata(self) -> DatasetMetadata:
+        return DatasetMetadata(id=self._id, index2label=self._index2label)
+
+    def __getitem__(self, idx: int, /) -> tuple[Array, ObjectDetectionTarget, dict[str, Any]]:
+        return (
+            self._images[idx],
+            self.ObjectDetectionTarget(self._labels[idx], self._bboxes[idx]),
+            self._metadata[idx] if self._metadata is not None else {},
+        )
+
+
+def to_image_classification_dataset(
+    images: Array | Sequence[Array],
+    labels: Sequence[int],
+    metadata: Sequence[dict[str, Any]] | None,
+    classes: Sequence[str] | None,
+    name: str | None = None,
+) -> ImageClassificationDataset:
+    """
+    Helper function to create custom ImageClassificationDataset classes.
+
+    Parameters
+    ----------
+    images : Array | Sequence[Array]
+        The images to use in the dataset.
+    labels : Sequence[int]
+        The labels to use in the dataset.
+    metadata : Sequence[dict[str, Any]] | None
+        The metadata to use in the dataset.
+    classes : Sequence[str] | None
+        The classes to use in the dataset.
+
+    Returns
+    -------
+    ImageClassificationDataset
+    """
+    _validate_data("ic", images, labels, None, metadata)
+    return CustomImageClassificationDataset(images, labels, metadata, classes, name)
+
+
+def to_object_detection_dataset(
+    images: Array | Sequence[Array],
+    labels: Sequence[Sequence[int]],
+    bboxes: Sequence[Sequence[Sequence[float]]],
+    metadata: Sequence[dict[str, Any]] | None,
+    classes: Sequence[str] | None,
+    name: str | None = None,
+) -> ObjectDetectionDataset:
+    """
+    Helper function to create custom ObjectDetectionDataset classes.
+
+    Parameters
+    ----------
+    images : Array | Sequence[Array]
+        The images to use in the dataset.
+    labels : Sequence[Sequence[int]]
+        The labels to use in the dataset.
+    bboxes : Sequence[Sequence[Sequence[float]]]
+        The bounding boxes (x0,y0,x1,y0) to use in the dataset.
+    metadata : Sequence[dict[str, Any]] | None
+        The metadata to use in the dataset.
+    classes : Sequence[str] | None
+        The classes to use in the dataset.
+
+    Returns
+    -------
+    ObjectDetectionDataset
+    """
+    _validate_data("od", images, labels, bboxes, metadata)
+    return CustomObjectDetectionDataset(images, labels, bboxes, metadata, classes, name)

dataeval/utils/data/_embeddings.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+__all__ = []
+
+import math
+from typing import Any, Iterator, Sequence
+
+import torch
+from torch.utils.data import DataLoader, Subset
+from tqdm import tqdm
+
+from dataeval.config import get_device
+from dataeval.typing import Array, Dataset
+from dataeval.utils.torch.models import SupportsEncode
+
+
+class Embeddings:
+    """
+    Collection of image embeddings from a dataset.
+
+    Embeddings are accessed by index or slice and are only loaded on-demand.
+
+    Parameters
+    ----------
+    dataset : ImageClassificationDataset or ObjectDetectionDataset
+        Dataset to access original images from.
+    batch_size : int, optional
+        Batch size to use when encoding images.
+    model : torch.nn.Module, optional
+        Model to use for encoding images.
+    device : torch.device, optional
+        Device to use for encoding images.
+    verbose : bool, optional
+        Whether to print progress bar when encoding images.
+    """
+
+    device: torch.device
+    batch_size: int
+    verbose: bool
+
+    def __init__(
+        self,
+        dataset: Dataset[tuple[Array, Any, Any]],
+        batch_size: int,
+        indices: Sequence[int] | None = None,
+        model: torch.nn.Module | None = None,
+        device: torch.device | str | None = None,
+        verbose: bool = False,
+    ) -> None:
+        self.device = get_device(device)
+        self.batch_size = batch_size
+        self.verbose = verbose
+
+        self._dataset = dataset
+        self._indices = indices if indices is not None else range(len(dataset))
+        model = torch.nn.Flatten() if model is None else model
+        self._model = model.to(self.device).eval()
+        self._encoder = model.encode if isinstance(model, SupportsEncode) else model
+        self._collate_fn = lambda datum: [torch.as_tensor(i) for i, _, _ in datum]
+
+    def to_tensor(self) -> torch.Tensor:
+        """
+        Converts entire dataset to embeddings.
+
+        Warning
+        -------
+        Will process the entire dataset in batches and return
+        embeddings as a single Tensor in memory.
+
+        Returns
+        -------
+        torch.Tensor
+        """
+        return self[:]
+
+    # Reduce overhead cost by not tracking tensor gradients
+    @torch.no_grad
+    def _batch(self, indices: Sequence[int]) -> Iterator[torch.Tensor]:
+        # manual batching
+        dataloader = DataLoader(Subset(self._dataset, indices), batch_size=self.batch_size, collate_fn=self._collate_fn)  # type: ignore
+        for i, images in (
+            tqdm(enumerate(dataloader), total=math.ceil(len(indices) / self.batch_size), desc="Batch processing")
+            if self.verbose
+            else enumerate(dataloader)
+        ):
+            embeddings = self._encoder(torch.stack(images).to(self.device))
+            yield embeddings
+
+    def __getitem__(self, key: int | slice | list[int], /) -> torch.Tensor:
+        if isinstance(key, list):
+            return torch.vstack(list(self._batch(key))).to(self.device)
+        if isinstance(key, slice):
+            return torch.vstack(list(self._batch(range(len(self._dataset))[key]))).to(self.device)
+        elif isinstance(key, int):
+            return self._encoder(torch.as_tensor(self._dataset[key][0]).to(self.device))
+        raise TypeError("Invalid argument type.")
+
+    def __iter__(self) -> Iterator[torch.Tensor]:
+        # process in batches while yielding individual embeddings
+        for batch in self._batch(range(len(self._dataset))):
+            yield from batch
+
+    def __len__(self) -> int:
+        return len(self._dataset)

dataeval/utils/data/_images.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+__all__ = []
+
+from typing import Any, Generic, Iterator, Sequence, TypeVar, cast, overload
+
+from dataeval.typing import Dataset
+
+T = TypeVar("T")
+
+
+class Images(Generic[T]):
+    """
+    Collection of image data from a dataset.
+
+    Images are accessed by index or slice and are only loaded on-demand.
+
+    Parameters
+    ----------
+    dataset : Dataset[tuple[T, ...]] or Dataset[T]
+        Dataset to access images from.
+    """
+
+    def __init__(self, dataset: Dataset[tuple[T, Any, Any] | T]) -> None:
+        self._is_tuple_datum = isinstance(dataset[0], tuple)
+        self._dataset = dataset
+
+    def to_list(self) -> Sequence[T]:
+        """
+        Converts entire dataset to a sequence of images.
+
+        Warning
+        -------
+        Will load the entire dataset and return the images as a
+        single sequence of images in memory.
+
+        Returns
+        -------
+        list[T]
+        """
+        return self[:]
+
+    @overload
+    def __getitem__(self, key: int, /) -> T: ...
+    @overload
+    def __getitem__(self, key: slice, /) -> Sequence[T]: ...
+
+    def __getitem__(self, key: int | slice, /) -> Sequence[T] | T:
+        if self._is_tuple_datum:
+            dataset = cast(Dataset[tuple[T, Any, Any]], self._dataset)
+            if isinstance(key, slice):
+                return [dataset[k][0] for k in range(len(self._dataset))[key]]
+            elif isinstance(key, int):
+                return dataset[key][0]
+        else:
+            dataset = cast(Dataset[T], self._dataset)
+            if isinstance(key, slice):
+                return [dataset[k] for k in range(len(self._dataset))[key]]
+            elif isinstance(key, int):
+                return dataset[key]
+        raise TypeError(f"Key must be integers or slices, not {type(key)}")
+
+    def __iter__(self) -> Iterator[T]:
+        for i in range(len(self._dataset)):
+            yield self[i]
+
+    def __len__(self) -> int:
+        return len(self._dataset)