dataeval 0.87.0__py3-none-any.whl → 0.88.0__py3-none-any.whl

dataeval/data/_metadata.py

@@ -3,12 +3,14 @@ from __future__ import annotations
 __all__ = []
 
 import warnings
+from collections.abc import Callable, Iterable, Mapping, Sequence, Sized
 from dataclasses import dataclass
-from typing import Any, Iterable, Literal, Mapping, Sequence, Sized
+from typing import Any, Literal
 
 import numpy as np
 import polars as pl
 from numpy.typing import NDArray
+from tqdm.auto import tqdm
 
 from dataeval.typing import (
     AnnotatedDataset,
@@ -17,7 +19,7 @@ from dataeval.typing import (
 )
 from dataeval.utils._array import as_numpy
 from dataeval.utils._bin import bin_data, digitize_data, is_continuous
-from dataeval.utils.data.metadata import merge
+from dataeval.utils.data._merge import merge
 
 
 def _binned(name: str) -> str:
@@ -44,21 +46,32 @@ def _to_col(name: str, info: FactorInfo, binned: bool = True) -> str:
 
 
 class Metadata:
-    """
-    Class containing binned metadata using Polars DataFrames.
+    """Collection of binned metadata using Polars DataFrames.
+
+    Processes dataset metadata by automatically binning continuous factors and digitizing
+    categorical factors for analysis and visualization workflows.
 
     Parameters
     ----------
     dataset : ImageClassificationDataset or ObjectDetectionDataset
-        Dataset to access original targets and metadata from.
+        Dataset that provides original targets and metadata for processing.
     continuous_factor_bins : Mapping[str, int | Sequence[float]] | None, default None
-        Mapping from continuous factor name to the number of bins or bin edges
+        Mapping from continuous factor names to bin counts or explicit bin edges.
+        When None, uses automatic discretization.
     auto_bin_method : Literal["uniform_width", "uniform_count", "clusters"], default "uniform_width"
-        Method for automatically determining the number of bins for continuous factors
+        Binning strategy for continuous factors without explicit bins. Default "uniform_width"
+        provides intuitive equal-width intervals for most distributions.
     exclude : Sequence[str] | None, default None
-        Filter metadata factors to exclude the specified factors, cannot be set with `include`
+        Factor names to exclude from processing. Cannot be used with `include` parameter.
+        When None, processes all available factors.
     include : Sequence[str] | None, default None
-        Filter metadata factors to include the specified factors, cannot be set with `exclude`
+        Factor names to include in processing. Cannot be used with `exclude` parameter.
+        When None, processes all available factors.
+
+    Raises
+    ------
+    ValueError
+        When both exclude and include parameters are specified simultaneously.
     """
 
     def __init__(
@@ -94,17 +107,48 @@ class Metadata:
 
     @property
     def raw(self) -> Sequence[Mapping[str, Any]]:
-        """The raw list of metadata dictionaries for the dataset."""
+        """Original metadata dictionaries extracted from the dataset.
+
+        Access the unprocessed metadata as it was provided in the original dataset before
+        any binning, filtering, or transformation operations.
+
+        Returns
+        -------
+        Sequence[Mapping[str, Any]]
+            List of metadata dictionaries, one per dataset item, containing the original key-value
+            pairs as provided in the source data
+
+        Notes
+        -----
+            This property triggers dataset structure analysis on first access.
+        """
         self._structure()
         return self._raw
 
     @property
     def exclude(self) -> set[str]:
-        """Factors to exclude from the metadata."""
+        """Factor names excluded from metadata processing.
+
+        Returns
+        -------
+        set[str]
+            Set of factor names that are filtered out during processing.
+            Empty set when no exclusions are active.
+
+        """
         return self._exclude
 
     @exclude.setter
     def exclude(self, value: Sequence[str]) -> None:
+        """Set factor names to exclude from processing.
+
+        Automatically clears include filter and resets binning state when exclusion list changes.
+
+        Parameters
+        ----------
+        value : Sequence[str]
+            Factor names to exclude from metadata analysis.
+        """
         exclude = set(value)
         if self._exclude != exclude:
             self._exclude = exclude
@@ -113,11 +157,27 @@ class Metadata:
 
     @property
     def include(self) -> set[str]:
-        """Factors to include from the metadata."""
+        """Factor names included in metadata processing.
+
+        Returns
+        -------
+        set[str]
+            Set of factor names that are processed during analysis. Empty set when no inclusion filter is active.
+        """
         return self._include
 
     @include.setter
     def include(self, value: Sequence[str]) -> None:
+        """Set factor names to include in processing.
+
+        Automatically clears exclude filter and resets binning state when
+        inclusion list changes.
+
+        Parameters
+        ----------
+        value : Sequence[str]
+            Factor names to include in metadata analysis.
+        """
         include = set(value)
         if self._include != include:
             self._include = include
@@ -126,41 +186,120 @@ class Metadata:
 
     @property
     def continuous_factor_bins(self) -> Mapping[str, int | Sequence[float]]:
-        """Map of factor names to bin counts or bin edges."""
+        """Binning configuration for continuous factors.
+
+        Returns
+        -------
+        Mapping[str, int | Sequence[float]]
+            Dictionary mapping factor names to either the number of bins
+            (int) or explicit bin edges (sequence of floats).
+        """
         return self._continuous_factor_bins
 
     @continuous_factor_bins.setter
     def continuous_factor_bins(self, bins: Mapping[str, int | Sequence[float]]) -> None:
+        """Update binning configuration for continuous factors.
+
+        Triggers re-binning when configuration changes to ensure data
+        consistency with new bin specifications.
+
+        Parameters
+        ----------
+        bins : Mapping[str, int | Sequence[float]]
+            Dictionary mapping factor names to bin counts or explicit edges.
+        """
         if self._continuous_factor_bins != bins:
             self._continuous_factor_bins = dict(bins)
             self._reset_bins(bins)
 
     @property
     def auto_bin_method(self) -> Literal["uniform_width", "uniform_count", "clusters"]:
-        """Binning method to use when continuous_factor_bins is not defined."""
+        """Automatic binning strategy for continuous factors.
+
+        Returns
+        -------
+        {"uniform_width", "uniform_count", "clusters"}
+            Current method used for automatic discretization of continuous
+            factors that lack explicit bin specifications.
+        """
         return self._auto_bin_method
 
     @auto_bin_method.setter
     def auto_bin_method(self, method: Literal["uniform_width", "uniform_count", "clusters"]) -> None:
+        """Set automatic binning strategy for continuous factors.
+
+        Triggers re-binning with the new method when strategy changes to
+        ensure consistent discretization across all factors.
+
+        Parameters
+        ----------
+        method : {"uniform_width", "uniform_count", "clusters"}
+            Binning strategy to apply for continuous factors without
+            explicit bin configurations.
+        """
         if self._auto_bin_method != method:
             self._auto_bin_method = method
             self._reset_bins()
 
     @property
     def dataframe(self) -> pl.DataFrame:
-        """Dataframe containing target information and metadata factors."""
+        """Processed DataFrame containing targets and metadata factors.
+
+        Access the main data structure with target information (class labels,
+        scores, bounding boxes) and processed metadata factors ready for analysis.
+
+        Returns
+        -------
+        pl.DataFrame
+            DataFrame with columns for image indices, class labels, scores,
+            bounding boxes (when applicable), and all processed metadata factors.
+
+        Notes
+        -----
+        This property triggers dataset structure analysis on first access.
+        Factor binning occurs automatically when accessing factor-related data.
+        """
         self._structure()
         return self._dataframe
 
     @property
     def dropped_factors(self) -> Mapping[str, Sequence[str]]:
-        """Factors that were dropped during preprocessing and the reasons why they were dropped."""
+        """Factors removed during preprocessing with removal reasons.
+
+        Returns
+        -------
+        Mapping[str, Sequence[str]]
+            Dictionary mapping dropped factor names to lists of reasons
+            why they were excluded from the final dataset.
+
+        Notes
+        -----
+        This property triggers dataset structure analysis on first access.
+        Common removal reasons include incompatible data types, excessive
+        missing values, or insufficient variation.
+        """
         self._structure()
         return self._dropped_factors
 
     @property
     def digitized_data(self) -> NDArray[np.int64]:
-        """Factor data with digitized categorical data."""
+        """Factor data with categorical values converted to integer codes.
+
+        Access processed factor data where categorical factors are digitized
+        to integer codes but continuous factors remain in their original form.
+
+        Returns
+        -------
+        NDArray[np.int64]
+            Array with shape (n_samples, n_factors) containing integer-coded
+            categorical data. Returns empty array when no factors are available.
+
+        Notes
+        -----
+        This property triggers factor binning analysis on first access.
+        Use this for algorithms that can handle mixed categorical and
+        continuous data types.
+        """
         if not self.factor_names:
             return np.array([], dtype=np.int64)
 
@@ -173,7 +312,23 @@ class Metadata:
 
     @property
     def binned_data(self) -> NDArray[np.int64]:
-        """Factor data with binned continuous data."""
+        """Factor data with continuous values discretized into bins.
+
+        Access fully processed factor data where both categorical and
+        continuous factors are converted to integer bin indices.
+
+        Returns
+        -------
+        NDArray[np.int64]
+            Array with shape (n_samples, n_factors) containing binned integer
+            data ready for categorical analysis algorithms. Returns empty array
+            when no factors are available.
+
+        Notes
+        -----
+        This property triggers factor binning analysis on first access.
+        Use this for algorithms requiring purely discrete input data.
+        """
         if not self.factor_names:
             return np.array([], dtype=np.int64)
 
@@ -186,19 +341,59 @@ class Metadata:
 
     @property
     def factor_names(self) -> Sequence[str]:
-        """Factor names of the metadata."""
+        """Names of all processed metadata factors.
+
+        Returns
+        -------
+        Sequence[str]
+            List of factor names that passed filtering and preprocessing steps.
+            Order matches columns in factor_data, digitized_data, and binned_data.
+
+        Notes
+        -----
+        This property triggers dataset structure analysis on first access.
+        Factor names respect include/exclude filtering settings.
+        """
         self._structure()
         return list(filter(self._filter, self._factors))
 
     @property
     def factor_info(self) -> Mapping[str, FactorInfo]:
-        """Factor types of the metadata."""
+        """Type information and processing status for each factor.
+
+        Returns
+        -------
+        Mapping[str, FactorInfo]
+            Dictionary mapping factor names to FactorInfo objects containing
+            data type classification and processing flags (binned, digitized).
+
+        Notes
+        -----
+        This property triggers factor binning analysis on first access.
+        Only includes factors that survived preprocessing and filtering.
+        """
         self._bin()
         return dict(filter(self._filter, ((k, v) for k, v in self._factors.items() if v is not None)))
 
     @property
     def factor_data(self) -> NDArray[Any]:
-        """Factor data as a NumPy array."""
+        """Raw factor values before binning or digitization.
+
+        Access unprocessed factor data in its original numeric form before
+        any categorical encoding or binning transformations are applied.
+
+        Returns
+        -------
+        NDArray[Any]
+            Array with shape (n_samples, n_factors) containing original factor
+            values. Returns empty array when no factors are available.
+
+        Notes
+        -----
+        Use this for algorithms that can work with mixed data types or when
+        you need access to original continuous values. For analysis-ready
+        integer data, use binned_data or digitized_data instead.
+        """
         if not self.factor_names:
             return np.array([], dtype=np.float64)
 
@@ -207,24 +402,67 @@ class Metadata:
 
     @property
     def class_labels(self) -> NDArray[np.intp]:
-        """Class labels as a NumPy array."""
+        """Target class labels as integer indices.
+
+        Returns
+        -------
+        NDArray[np.intp]
+            Array of class indices corresponding to dataset targets. For
+            object detection datasets, contains one label per detection.
+
+        Notes
+        -----
+        This property triggers dataset structure analysis on first access.
+        Use class_names property to get human-readable label names.
+        """
         self._structure()
         return self._class_labels
 
     @property
     def class_names(self) -> Sequence[str]:
-        """Class names as a list of strings."""
+        """Human-readable names corresponding to class labels.
+
+        Returns
+        -------
+        Sequence[str]
+            List of class names where index corresponds to class label value.
+            Derived from dataset metadata or auto-generated from label indices.
+
+        Notes
+        -----
+        This property triggers dataset structure analysis on first access.
+        """
         self._structure()
         return self._class_names
 
     @property
     def image_indices(self) -> NDArray[np.intp]:
-        """Indices of images as a NumPy array."""
+        """Dataset indices linking targets back to source images.
+
+        Returns
+        -------
+        NDArray[np.intp]
+            Array mapping each target/detection back to its source image
+            index in the original dataset. Essential for object detection
+            datasets where multiple detections come from single images.
+
+        Notes
+        -----
+        This property triggers dataset structure analysis on first access.
+        """
         self._structure()
         return self._image_indices
 
     @property
     def image_count(self) -> int:
+        """Total number of images in the dataset.
+
+        Returns
+        -------
+        int
+            Count of unique images in the source dataset, regardless of
+            how many targets/detections each image contains.
+        """
         if self._count == 0:
             self._structure()
         return self._count
@@ -252,7 +490,7 @@ class Metadata:
         scores = []
         srcidx = []
         is_od = None
-        for i in range(len(self._dataset)):
+        for i in tqdm(range(len(self._dataset))):
             _, target, metadata = self._dataset[i]
 
             raw.append(metadata)
@@ -261,15 +499,15 @@ class Metadata:
                 target_labels = as_numpy(target.labels)
                 target_len = len(target_labels)
                 if target_len:
-                    labels.extend(target_labels.tolist())
-                    bboxes.extend(as_numpy(target.boxes).tolist())
-                    scores.extend(as_numpy(target.scores).tolist())
+                    labels.append(target_labels)
+                    bboxes.append(as_numpy(target.boxes))
+                    scores.append(as_numpy(target.scores))
                     srcidx.extend([i] * target_len)
             elif isinstance(target, Array):
-                if len(target):
-                    target_len = 1
-                    labels.append(int(np.argmax(as_numpy(target))))
-                    scores.append(target)
+                target_scores = as_numpy(target)
+                if len(target_scores):
+                    labels.append([np.argmax(target_scores)])
+                    scores.append([target_scores])
                     srcidx.append(i)
             else:
                 raise TypeError("Encountered unsupported target type in dataset")
@@ -278,10 +516,11 @@ class Metadata:
             if is_od != is_od_target:
                 raise ValueError("Encountered unexpected target type in dataset")
 
-        labels = as_numpy(labels).astype(np.intp)
-        scores = as_numpy(scores).astype(np.float32)
-        bboxes = as_numpy(bboxes).astype(np.float32) if is_od else None
-        srcidx = as_numpy(srcidx).astype(np.intp)
+        np_asarray: Callable[..., np.ndarray] = np.concatenate if srcidx else np.asarray
+        labels = np_asarray(labels, dtype=np.intp)
+        scores = np_asarray(scores, dtype=np.float32)
+        bboxes = np_asarray(bboxes, dtype=np.float32) if is_od else None
+        srcidx = np.asarray(srcidx, dtype=np.intp)
 
         index2label = self._dataset.metadata.get("index2label", {i: str(i) for i in np.unique(labels)})
 
@@ -370,16 +609,30 @@ class Metadata:
         self._is_binned = True
 
     def add_factors(self, factors: Mapping[str, Array | Sequence[Any]]) -> None:
-        """
-        Add additional factors to the metadata.
+        """Add additional factors to metadata collection.
 
-        The number of measures per factor must match the number of images
-        in the dataset or the number of detections in the dataset.
+        Extend the current metadata with new factors, automatically handling
+        length validation and integration with existing data structures.
 
         Parameters
         ----------
         factors : Mapping[str, Array | Sequence[Any]]
-            Dictionary of factors to add to the metadata.
+            Dictionary mapping factor names to their values. Factor length must
+            match either the number of images or number of detections in the dataset.
+
+        Raises
+        ------
+        ValueError
+            When factor lengths do not match dataset dimensions.
+
+        Examples
+        --------
+        >>> metadata = Metadata(dataset)
+        >>> new_factors = {
+        ...     "brightness": [0.2, 0.8, 0.5, 0.3, 0.4, 0.1, 0.3, 0.2],
+        ...     "contrast": [1.1, 0.9, 1.0, 0.8, 1.2, 1.0, 0.7, 1.3],
+        ... }
+        >>> metadata.add_factors(new_factors)
         """
         self._structure()
 

dataeval/data/_selection.py

@@ -2,8 +2,9 @@ from __future__ import annotations
 
 __all__ = []
 
+from collections.abc import Iterator, Sequence
 from enum import IntEnum
-from typing import Generic, Iterator, Sequence, TypeVar
+from typing import Generic, TypeVar
 
 from dataeval.typing import AnnotatedDataset, DatasetMetadata
 
@@ -31,14 +32,21 @@ class Subselection(Generic[_TDatum]):
 
 class Select(AnnotatedDataset[_TDatum]):
     """
-    Wraps a dataset and applies selection criteria to it.
+    Dataset wrapper that applies selection criteria for filtering.
+
+    Wraps an existing dataset and applies one or more selection filters to
+    create a subset view without modifying the original dataset. Supports
+    chaining multiple selection criteria for complex filtering operations.
 
     Parameters
     ----------
-    dataset : Dataset
-        The dataset to wrap.
-    selections : Selection or list[Selection], optional
-        The selection criteria to apply to the dataset.
+    dataset : AnnotatedDataset[_TDatum]
+        Source dataset to wrap and filter. Must implement AnnotatedDataset
+        interface with indexed access to data tuples.
+    selections : Selection or Sequence[Selection] or None, default None
+        Selection criteria to apply for filtering the dataset. When None,
+        returns all items from the source dataset. Default None creates
+        unfiltered view for consistent interface.
 
     Examples
     --------
@@ -49,7 +57,7 @@ class Select(AnnotatedDataset[_TDatum]):
     >>> # - f"data_{idx}", one_hot_encoded(idx % class_count), {"id": idx}
     >>> dataset = SampleDataset(size=100, class_count=10)
 
-    >>> # Apply a selection criteria to the dataset
+    >>> # Apply selection criteria to the dataset
     >>> selections = [Limit(size=5), ClassFilter(classes=[0, 2])]
     >>> selected_dataset = Select(dataset, selections=selections)
 
@@ -61,6 +69,12 @@ class Select(AnnotatedDataset[_TDatum]):
     (data_10, 0, {'id': 10})
     (data_12, 2, {'id': 12})
     (data_20, 0, {'id': 20})
+
+    Notes
+    -----
+    Selection criteria are applied in the order provided, allowing for
+    efficient sequential filtering. The wrapper maintains all metadata
+    and interface compatibility with the original dataset.
     """
 
     _dataset: AnnotatedDataset[_TDatum]
@@ -91,6 +105,7 @@ class Select(AnnotatedDataset[_TDatum]):
 
     @property
     def metadata(self) -> DatasetMetadata:
+        """Dataset metadata information including identifier and configuration."""
         return self._metadata
 
     def __str__(self) -> str:

dataeval/data/_split.py

@@ -4,7 +4,8 @@ __all__ = []
 
 import logging
 import warnings
-from typing import Any, Iterator, Protocol, Sequence
+from collections.abc import Iterator, Sequence
+from typing import Any, Protocol
 
 import numpy as np
 from numpy.typing import NDArray

dataeval/data/selections/_classfilter.py

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 __all__ = []
 
-from typing import Any, Generic, Iterable, Mapping, Sequence, Sized, TypeVar, cast
+from collections.abc import Iterable, Mapping, Sequence, Sized
+from typing import Any, Generic, TypeVar, cast
 
 import numpy as np
 from numpy.typing import NDArray
@@ -45,7 +46,7 @@ class ClassFilter(Selection[Any]):
                 if label in self.classes:
                     # Include the image index
                     selection.append(idx)
-            elif isinstance(target, (ObjectDetectionTarget, SegmentationTarget)):
+            elif isinstance(target, ObjectDetectionTarget | SegmentationTarget):
                 # Get the set of labels from the target
                 labels = set(target.labels if isinstance(target.labels, Iterable) else [target.labels])
                 # Check to see if any labels are in the classes to filter for
@@ -68,7 +69,7 @@ _TTarget = TypeVar("_TTarget", ObjectDetectionTarget, SegmentationTarget)
 
 
 def _try_mask_object(obj: _T, mask: NDArray[np.bool_]) -> _T:
-    if not isinstance(obj, (str, bytes, bytearray)) and isinstance(obj, (Sequence, Array)) and len(obj) == len(mask):
+    if not isinstance(obj, str | bytes | bytearray) and isinstance(obj, Sequence | Array) and len(obj) == len(mask):
         return obj[mask] if isinstance(obj, Array) else cast(_T, [item for i, item in enumerate(obj) if mask[i]])
     return obj
 

dataeval/data/selections/_indices.py

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 __all__ = []
 
-from typing import Any, Sequence
+from collections.abc import Sequence
+from typing import Any
 
 from dataeval.data._selection import Select, Selection, SelectionStage
 

dataeval/data/selections/_shuffle.py

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 __all__ = []
 
-from typing import Any, Sequence
+from collections.abc import Sequence
+from typing import Any
 
 import numpy as np
 from numpy.random import BitGenerator, Generator, SeedSequence
@@ -33,7 +34,7 @@ class Shuffle(Selection[Any]):
     def __init__(
         self, seed: int | Sequence[int] | Array | SeedSequence | BitGenerator | Generator | None = None
     ) -> None:
-        self.seed = as_numpy(seed) if isinstance(seed, (Sequence, Array)) else seed
+        self.seed = as_numpy(seed) if isinstance(seed, Sequence | Array) else seed
 
     def __call__(self, dataset: Select[Any]) -> None:
         rng = np.random.default_rng(self.seed)

dataeval/detectors/drift/_base.py

@@ -12,8 +12,9 @@ __all__ = []
 
 import math
 from abc import abstractmethod
+from collections.abc import Callable
 from functools import wraps
-from typing import Any, Callable, Literal, Protocol, TypeVar, runtime_checkable
+from typing import Any, Literal, Protocol, TypeVar, runtime_checkable
 
 import numpy as np
 from numpy.typing import NDArray

dataeval/detectors/drift/_mmd.py

@@ -10,7 +10,8 @@ from __future__ import annotations
 
 __all__ = []
 
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 import torch