dataeval 0.74.2__py3-none-any.whl → 0.76.0__py3-none-any.whl

dataeval/metrics/stats/visualstats.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__all__ = ["VisualStatsOutput", "visualstats"]
+__all__ = []
 
 from dataclasses import dataclass
 from typing import Any, Callable, Iterable
@@ -8,7 +8,7 @@ from typing import Any, Callable, Iterable
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
 
-from dataeval.metrics.stats.base import BaseStatsOutput, StatsProcessor, run_stats
+from dataeval.metrics.stats.base import BaseStatsOutput, HistogramPlotMixin, StatsProcessor, run_stats
 from dataeval.output import set_metadata
 from dataeval.utils.image import edge_filter
 
@@ -16,9 +16,9 @@ QUARTILES = (0, 25, 50, 75, 100)
 
 
 @dataclass(frozen=True)
-class VisualStatsOutput(BaseStatsOutput):
+class VisualStatsOutput(BaseStatsOutput, HistogramPlotMixin):
     """
-    Output class for :func:`visualstats` stats metric
+    Output class for :func:`visualstats` stats metric.
 
     Attributes
     ----------
@@ -46,6 +46,8 @@ class VisualStatsOutput(BaseStatsOutput):
     zeros: NDArray[np.float16]
     percentiles: NDArray[np.float16]
 
+    _excluded_keys = ["percentiles"]
+
 
 class VisualStatsProcessor(StatsProcessor[VisualStatsOutput]):
     output_class: type = VisualStatsOutput
@@ -81,7 +83,7 @@ def visualstats(
     per_channel: bool = False,
 ) -> VisualStatsOutput:
     """
-    Calculates visual statistics for each image
+    Calculates visual :term:`statistics` for each image.
 
     This function computes various visual metrics (e.g., :term:`brightness<Brightness>`, darkness, contrast, blurriness)
     on the images as a whole.
@@ -112,15 +114,10 @@ def visualstats(
     --------
     Calculating the :term:`statistics<Statistics>` on the images, whose shape is (C, H, W)
 
-    >>> results = visualstats(images)
+    >>> results = visualstats(stats_images)
     >>> print(results.brightness)
-    [0.02246 0.5557  0.06805 0.1014  0.1348  0.1681  0.2014  0.2347  0.268
-     0.3015  0.3347  0.3682  0.4014  0.4348  0.468   0.5015  0.5347  0.568
-     0.6016  0.635   0.668   0.701   0.735   0.768   0.8013  0.835   0.868
-     0.9014  0.9346  0.9683 ]
+    [0.1353 0.2085 0.4143 0.6084 0.8135]
     >>> 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]
+    [2.04  1.331 1.261 1.279 1.253]
     """
     return run_stats(images, bboxes, per_channel, [VisualStatsProcessor])[0]

dataeval/output.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 __all__ = []
 
 import inspect
+import logging
 import sys
 from collections.abc import Mapping
 from datetime import datetime, timezone
@@ -81,29 +82,37 @@ def set_metadata(fn: Callable[P, R] | None = None, *, state: list[str] | None =
                 return f"{v.__class__.__name__}: len={len(v)}"
             return f"{v.__class__.__name__}"
 
-        time = datetime.now(timezone.utc)
-        result = fn(*args, **kwargs)
-        duration = (datetime.now(timezone.utc) - time).total_seconds()
-        fn_params = inspect.signature(fn).parameters
-
+        # Collect function metadata
         # set all params with defaults then update params with mapped arguments and explicit keyword args
+        fn_params = inspect.signature(fn).parameters
         arguments = {k: None if v.default is inspect.Parameter.empty else v.default for k, v in fn_params.items()}
         arguments.update(zip(fn_params, args))
         arguments.update(kwargs)
         arguments = {k: fmt(v) for k, v in arguments.items()}
-        state_attrs = (
-            {k: fmt(getattr(args[0], k)) for k in state if "self" in arguments} if "self" in arguments and state else {}
-        )
-        name = (
-            f"{args[0].__class__.__module__}.{args[0].__class__.__name__}.{fn.__name__}"
-            if "self" in arguments
-            else f"{fn.__module__}.{fn.__qualname__}"
-        )
+        is_method = "self" in arguments
+        state_attrs = {k: fmt(getattr(args[0], k)) for k in state or []} if is_method else {}
+        module = args[0].__class__.__module__ if is_method else fn.__module__.removeprefix("src.")
+        class_prefix = f".{args[0].__class__.__name__}." if is_method else "."
+        name = f"{module}{class_prefix}{fn.__name__}"
+        arguments = {k: v for k, v in arguments.items() if k != "self"}
+
+        _logger = logging.getLogger(module)
+        time = datetime.now(timezone.utc)
+        _logger.log(logging.INFO, f">>> Executing '{name}': args={arguments} state={state} <<<")
+
+        ##### EXECUTE FUNCTION #####
+        result = fn(*args, **kwargs)
+        ############################
+
+        duration = (datetime.now(timezone.utc) - time).total_seconds()
+        _logger.log(logging.INFO, f">>> Completed '{name}': args={arguments} state={state} duration={duration} <<<")
+
+        # Update output with recorded metadata
         metadata = {
             "_name": name,
             "_execution_time": time,
             "_execution_duration": duration,
-            "_arguments": {k: v for k, v in arguments.items() if k != "self"},
+            "_arguments": arguments,
             "_state": state_attrs,
             "_version": __version__,
         }

dataeval/utils/__init__.py

@@ -1,18 +1,9 @@
 """
-The utility classes and functions are provided by DataEval to assist users
-in setting up architectures that are guaranteed to work with applicable DataEval
-metrics. Currently DataEval supports both :term:`TensorFlow` and PyTorch backends.
+The utility classes and functions are provided by DataEval to assist users \
+in setting up data and architectures that are guaranteed to work with applicable \
+DataEval metrics.
 """
 
-from dataeval import _IS_TORCH_AVAILABLE
-from dataeval.utils.metadata import merge_metadata
-from dataeval.utils.split_dataset import split_dataset
+__all__ = ["dataset", "metadata", "torch"]
 
-__all__ = ["split_dataset", "merge_metadata"]
-
-if _IS_TORCH_AVAILABLE:
-    from dataeval.utils import torch
-
-    __all__ += ["torch"]
-
-del _IS_TORCH_AVAILABLE
+from dataeval.utils import dataset, metadata, torch

dataeval/utils/dataset/__init__.py

@@ -0,0 +1,7 @@
+"""Provides utility functions for interacting with Computer Vision datasets."""
+
+__all__ = ["datasets", "read_dataset", "SplitDatasetOutput", "split_dataset"]
+
+from dataeval.utils.dataset import datasets
+from dataeval.utils.dataset.read import read_dataset
+from dataeval.utils.dataset.split import SplitDatasetOutput, split_dataset

dataeval/utils/{torch → dataset}/datasets.py

@@ -1,3 +1,5 @@
+"""Provides access to common Computer Vision datasets."""
+
 from __future__ import annotations
 
 __all__ = ["MNIST", "CIFAR10", "VOCDetection"]

dataeval/utils/dataset/read.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+__all__ = []
+
+from collections import defaultdict
+from typing import Any
+
+from torch.utils.data import Dataset
+
+
+def read_dataset(dataset: Dataset[Any]) -> list[list[Any]]:
+    """
+    Extract information from a dataset at each index into individual lists of each information position.
+
+    Parameters
+    ----------
+    dataset : torch.utils.data.Dataset
+        Input dataset
+
+    Returns
+    -------
+    List[List[Any]]
+        All objects in individual lists based on return position from dataset
+
+    Warning
+    -------
+    No type checking is done between lists or data inside lists
+
+    See Also
+    --------
+    torch.utils.data.Dataset
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> data = np.ones((10, 1, 3, 3))
+    >>> labels = np.ones((10,))
+    >>> class ICDataset:
+    ...     def __init__(self, data, labels):
+    ...         self.data = data
+    ...         self.labels = labels
+    ...
+    ...     def __getitem__(self, idx):
+    ...         return self.data[idx], self.labels[idx]
+
+    >>> ds = ICDataset(data, labels)
+
+    >>> result = read_dataset(ds)
+    >>> len(result)  # images and labels
+    2
+    >>> np.asarray(result[0]).shape  # images
+    (10, 1, 3, 3)
+    >>> np.asarray(result[1]).shape  # labels
+    (10,)
+    """
+
+    ddict: dict[int, list[Any]] = defaultdict(list[Any])
+
+    for data in dataset:
+        for i, d in enumerate(data if isinstance(data, tuple) else (data,)):
+            ddict[i].append(d)
+
+    return list(ddict.values())

dataeval/utils/{split_dataset.py → dataset/split.py}

@@ -1,12 +1,9 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
-
-from dataeval.output import Output, set_metadata
-
-__all__ = ["split_dataset", "SplitDatasetOutput"]
+__all__ = []
 
 import warnings
+from dataclasses import dataclass
 from typing import Any, Iterator, NamedTuple, Protocol
 
 import numpy as np
@@ -16,19 +13,30 @@ from sklearn.metrics import silhouette_score
 from sklearn.model_selection import GroupKFold, KFold, StratifiedGroupKFold, StratifiedKFold
 from sklearn.utils.multiclass import type_of_target
 
+from dataeval.output import Output, set_metadata
+
 
 class TrainValSplit(NamedTuple):
     """Tuple containing train and validation indices"""
 
-    train: NDArray[np.int_]
-    val: NDArray[np.int_]
+    train: NDArray[np.intp]
+    val: NDArray[np.intp]
 
 
 @dataclass(frozen=True)
 class SplitDatasetOutput(Output):
-    """Output class containing test indices and a list of TrainValSplits"""
+    """
+    Output class containing test indices and a list of TrainValSplits.
+
+    Attributes
+    ----------
+    test: NDArray[np.intp]
+        Indices for the test set
+    folds: list[TrainValSplit]
+        List where each index contains the indices for the train and validation splits
+    """
 
-    test: NDArray[np.int_]
+    test: NDArray[np.intp]
     folds: list[TrainValSplit]
 
 
@@ -100,7 +108,7 @@ def calculate_validation_fraction(num_folds: int, test_frac: float, val_frac: fl
     return val_base * (1.0 / num_folds) * (1.0 - test_frac)
 
 
-def _validate_labels(labels: NDArray[np.int_], total_partitions: int) -> None:
+def _validate_labels(labels: NDArray[np.intp], total_partitions: int) -> None:
     """
     Check to make sure there is more input data than the total number of partitions requested
 
@@ -131,7 +139,7 @@ def _validate_labels(labels: NDArray[np.int_], total_partitions: int) -> None:
         raise ValueError("Detected continuous labels. Labels must be discrete for proper stratification")
 
 
-def is_stratifiable(labels: NDArray[np.int_], num_partitions: int) -> bool:
+def is_stratifiable(labels: NDArray[np.intp], num_partitions: int) -> bool:
     """
     Check if the dataset can be stratified by class label over the given number of partitions
 
@@ -166,7 +174,7 @@ def is_stratifiable(labels: NDArray[np.int_], num_partitions: int) -> bool:
     return True
 
 
-def is_groupable(group_ids: NDArray[np.int_], num_partitions: int) -> bool:
+def is_groupable(group_ids: NDArray[np.intp], num_partitions: int) -> bool:
     """
     Warns user if the number of unique group_ids is incompatible with a grouped partition containing
     num_folds folds. If this is the case, returns groups=None, which tells the partitioner not to
@@ -205,7 +213,7 @@ def is_groupable(group_ids: NDArray[np.int_], num_partitions: int) -> bool:
     return True
 
 
-def bin_kmeans(array: NDArray[Any]) -> NDArray[np.int_]:
+def bin_kmeans(array: NDArray[Any]) -> NDArray[np.intp]:
     """
     Find bins of continuous data by iteratively applying k-means clustering, and keeping the
     clustering with the highest silhouette score.
@@ -226,18 +234,18 @@ def bin_kmeans(array: NDArray[Any]) -> NDArray[np.int_]:
         best_score = 0.60
     else:
         best_score = 0.50
-    bin_index = np.zeros(len(array), dtype=np.int_)
+    bin_index = np.zeros(len(array), dtype=np.intp)
     for k in range(2, 20):
         clusterer = KMeans(n_clusters=k)
         cluster_labels = clusterer.fit_predict(array)
         score = silhouette_score(array, cluster_labels, sample_size=25_000)
         if score > best_score:
             best_score = score
-            bin_index = cluster_labels.astype(np.int_)
+            bin_index = cluster_labels.astype(np.intp)
     return bin_index
 
 
-def get_group_ids(metadata: dict[str, Any], group_names: list[str], num_samples: int) -> NDArray[np.int_]:
+def get_group_ids(metadata: dict[str, Any], group_names: list[str], num_samples: int) -> NDArray[np.intp]:
     """
     Returns individual group numbers based on a subset of metadata defined by groupnames
 
@@ -262,7 +270,7 @@ def get_group_ids(metadata: dict[str, Any], group_names: list[str], num_samples:
     """
     features2group = {k: np.array(v) for k, v in metadata.items() if k in group_names}
     if not features2group:
-        return np.zeros(num_samples, dtype=np.int_)
+        return np.zeros(num_samples, dtype=np.intp)
     for name, feature in features2group.items():
         if len(feature) != num_samples:
             raise ValueError(
@@ -278,10 +286,10 @@ def get_group_ids(metadata: dict[str, Any], group_names: list[str], num_samples:
 
 
 def make_splits(
-    index: NDArray[np.int_],
-    labels: NDArray[np.int_],
+    index: NDArray[np.intp],
+    labels: NDArray[np.intp],
     n_folds: int,
-    groups: NDArray[np.int_] | None,
+    groups: NDArray[np.intp] | None,
     stratified: bool,
 ) -> list[TrainValSplit]:
     """
@@ -318,8 +326,8 @@ def make_splits(
         split_defs.clear()
         for train_idx, eval_idx in splits:
             # test_ratio = len(eval_idx) / len(index)
-            t = np.atleast_1d(train_idx).astype(np.int_)
-            v = np.atleast_1d(eval_idx).astype(np.int_)
+            t = np.atleast_1d(train_idx).astype(np.intp)
+            v = np.atleast_1d(eval_idx).astype(np.intp)
             good = good or (len(np.unique(labels[t])) == n_labels and len(np.unique(labels[v])) == n_labels)
             split_defs.append(TrainValSplit(t, v))
     if not good and attempts == 3:
@@ -328,7 +336,7 @@ def make_splits(
 
 
 def find_best_split(
-    labels: NDArray[np.int_], split_defs: list[TrainValSplit], stratified: bool, split_frac: float
+    labels: NDArray[np.intp], split_defs: list[TrainValSplit], stratified: bool, split_frac: float
 ) -> TrainValSplit:
     """
     Finds the split that most closely satisfies a criterion determined by the arguments passed.
@@ -385,10 +393,10 @@ def find_best_split(
 
 
 def single_split(
-    index: NDArray[np.int_],
-    labels: NDArray[np.int_],
+    index: NDArray[np.intp],
+    labels: NDArray[np.intp],
     split_frac: float,
-    groups: NDArray[np.int_] | None = None,
+    groups: NDArray[np.intp] | None = None,
     stratified: bool = False,
 ) -> TrainValSplit:
     """
@@ -427,7 +435,7 @@ def single_split(
 
 @set_metadata
 def split_dataset(
-    labels: list[int] | NDArray[np.int_],
+    labels: list[int] | NDArray[np.intp],
     num_folds: int = 1,
     stratify: bool = False,
     split_on: list[str] | None = None,
@@ -481,7 +489,7 @@ def split_dataset(
     total_partitions = num_folds + 1 if test_frac else num_folds
 
     if isinstance(labels, list):
-        labels = np.array(labels, dtype=np.int_)
+        labels = np.array(labels, dtype=np.intp)
 
     label_length: int = len(labels)
 
@@ -497,13 +505,13 @@ def split_dataset(
         if is_groupable(possible_groups, group_partitions):
             groups = possible_groups
 
-    test_indices: NDArray[np.int_]
+    test_indices: NDArray[np.intp]
     index = np.arange(label_length)
 
     tv_indices, test_indices = (
         single_split(index=index, labels=labels, split_frac=test_frac, groups=groups, stratified=stratify)
         if test_frac
-        else (index, np.array([], dtype=np.int_))
+        else (index, np.array([], dtype=np.intp))
     )
 
     tv_labels = labels[tv_indices]

dataeval/utils/image.py

@@ -63,8 +63,8 @@ def edge_filter(image: ArrayLike, offset: float = 0.5) -> NDArray[np.uint8]:
     """
     Returns the image filtered using a 3x3 edge detection kernel:
     [[ -1, -1, -1 ],
-     [ -1,  8, -1 ],
-     [ -1, -1, -1 ]]
+    [ -1,  8, -1 ],
+    [ -1, -1, -1 ]]
     """
     edges = convolve2d(image, EDGE_KERNEL, mode="same", boundary="symm") + offset
     np.clip(edges, 0, 255, edges)