dataeval 0.69.4__py3-none-any.whl → 0.70.1__py3-none-any.whl

dataeval/_internal/metrics/parity.py

@@ -17,6 +17,8 @@ TData = TypeVar("TData", np.float64, NDArray[np.float64])
 @dataclass(frozen=True)
 class ParityOutput(Generic[TData], OutputMetadata):
     """
+    Output class for :func:`parity` and :func:`label_parity` bias metrics
+
     Attributes
     ----------
     score : np.float64 | NDArray[np.float64]
@@ -62,8 +64,8 @@ def digitize_factor_bins(continuous_values: NDArray, bins: int, factor_name: str
 
 
 def format_discretize_factors(
-    data_factors: dict[str, NDArray], continuous_factor_bincounts: dict[str, int]
-) -> tuple[dict[str, NDArray], NDArray]:
+    data_factors: Mapping[str, NDArray], continuous_factor_bincounts: Mapping[str, int]
+) -> dict[str, NDArray]:
     """
     Sets up the internal list of metadata factors.
 
@@ -80,10 +82,9 @@ def format_discretize_factors(
 
     Returns
     -------
-    Tuple[Dict[str, NDArray], NDArray]
+    Dict[str, NDArray]
         - Intrinsic per-image metadata information with the formatting that input data_factors uses.
           Each key is a metadata factor, whose value is the discrete per-image factor values.
-        - Per-image labels, whose ith element is the label for the ith element of the dataset.
     """
 
     invalid_keys = set(continuous_factor_bincounts.keys()) - set(data_factors.keys())
@@ -103,8 +104,6 @@ def format_discretize_factors(
     if lengths[1:] != lengths[:-1]:
         raise ValueError("The lengths of each entry in the dictionary are not equal." f" Found lengths {lengths}")
 
-    labels = data_factors["class"]
-
     metadata_factors = {
         name: val
         if name not in continuous_factor_bincounts
@@ -113,7 +112,7 @@ def format_discretize_factors(
         if name != "class"
     }
 
-    return metadata_factors, labels
+    return metadata_factors
 
 
 def normalize_expected_dist(expected_dist: NDArray, observed_dist: NDArray) -> NDArray:
@@ -140,8 +139,8 @@ def normalize_expected_dist(expected_dist: NDArray, observed_dist: NDArray) -> N
     ValueError
         If the expected distribution is all zeros.
 
-    Notes
-    -----
+    Note
+    ----
     The function ensures that the total number of labels in the expected distribution matches the total
     number of labels in the observed distribution by scaling the expected distribution.
     """
@@ -187,7 +186,8 @@ def validate_dist(label_dist: NDArray, label_name: str):
         warnings.warn(
             f"Labels {np.where(label_dist<5)[0]} in {label_name}"
             " dataset have frequencies less than 5. This may lead"
-            " to invalid chi-squared evaluation."
+            " to invalid chi-squared evaluation.",
+            UserWarning,
         )
 
 
@@ -226,8 +226,8 @@ def label_parity(
         of unique classes between the observed and expected distributions.
 
 
-    Notes
-    -----
+    Note
+    ----
     - Providing ``num_classes`` can be helpful if there are classes with zero instances in one of the distributions.
     - The function first validates the observed distribution and normalizes the expected distribution so that it
       has the same total number of labels as the observed distribution.
@@ -280,8 +280,9 @@ def label_parity(
 
 @set_metadata("dataeval.metrics")
 def parity(
+    class_labels: ArrayLike,
     data_factors: Mapping[str, ArrayLike],
-    continuous_factor_bincounts: dict[str, int] | None = None,
+    continuous_factor_bincounts: Mapping[str, int] | None = None,
 ) -> ParityOutput[NDArray[np.float64]]:
     """
     Calculate chi-square statistics to assess the relationship between multiple factors and class labels.
@@ -292,10 +293,12 @@ def parity(
 
     Parameters
     ----------
+    class_labels: ArrayLike
+        List of class labels for each image
     data_factors: Mapping[str, ArrayLike]
-        The dataset factors, which are per-image attributes including class label and metadata.
+        The dataset factors, which are per-image metadata attributes.
         Each key of dataset_factors is a factor, whose value is the per-image factor values.
-    continuous_factor_bincounts : Dict[str, int] | None, default None
+    continuous_factor_bincounts : Mapping[str, int] | None, default None
         A dictionary specifying the number of bins for discretizing the continuous factors.
         The keys should correspond to the names of continuous factors in `data_factors`,
         and the values should be the number of bins to use for discretization.
@@ -316,8 +319,8 @@ def parity(
         factor values either 0 times or at least 5 times. Alternatively, continuous-valued factors can be digitized
         into fewer bins.
 
-    Notes
-    -----
+    Note
+    ----
     - Each key of the ``continuous_factor_bincounts`` dictionary must occur as a key in data_factors.
     - A high score with a low p-value suggests that a metadata factor is strongly correlated with a class label.
     - The function creates a contingency matrix for each factor, where each entry represents the frequency of a
@@ -329,21 +332,27 @@ def parity(
     --------
     Randomly creating some "continuous" and categorical variables using ``np.random.default_rng``
 
+    >>> labels = np_random_gen.choice([0, 1, 2], (100))
     >>> data_factors = {
     ...     "age": np_random_gen.choice([25, 30, 35, 45], (100)),
     ...     "income": np_random_gen.choice([50000, 65000, 80000], (100)),
     ...     "gender": np_random_gen.choice(["M", "F"], (100)),
-    ...     "class": np_random_gen.choice([0, 1, 2], (100)),
     ... }
     >>> continuous_factor_bincounts = {"age": 4, "income": 3}
-    >>> parity(data_factors, continuous_factor_bincounts)
-    ParityOutput(score=array([2.82329785, 1.60625584, 1.38377236]), p_value=array([0.83067563, 0.80766733, 0.5006309 ]))
+    >>> parity(labels, data_factors, continuous_factor_bincounts)
+    ParityOutput(score=array([7.35731943, 5.46711299, 0.51506212]), p_value=array([0.28906231, 0.24263543, 0.77295762]))
     """
+    if len(np.shape(class_labels)) > 1:
+        raise ValueError(
+            f"Got class labels with {len(np.shape(class_labels))}-dimensional",
+            f" shape {np.shape(class_labels)}, but expected a 1-dimensional array.",
+        )
 
     data_factors_np = {k: to_numpy(v) for k, v in data_factors.items()}
     continuous_factor_bincounts = continuous_factor_bincounts if continuous_factor_bincounts else {}
 
-    factors, labels = format_discretize_factors(data_factors_np, continuous_factor_bincounts)
+    labels = to_numpy(class_labels)
+    factors = format_discretize_factors(data_factors_np, continuous_factor_bincounts)
 
     chi_scores = np.zeros(len(factors))
     p_values = np.zeros(len(factors))
@@ -396,7 +405,8 @@ def parity(
         message = "\n".join(factor_msg)
 
         warnings.warn(
-            f"The following factors did not meet the recommended 5 occurrences for each value-label combination. \nRecommend rerunning parity after adjusting the following factor-value-label combinations: \n{message}",  # noqa: E501
+            f"The following factors did not meet the recommended 5 occurrences for each value-label combination. \n\
+            Recommend rerunning parity after adjusting the following factor-value-label combinations: \n{message}",
             UserWarning,
         )
 

dataeval/_internal/metrics/stats/base.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import re
+import warnings
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, NamedTuple, Optional, Union
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from dataeval._internal.interop import to_numpy_iter
+from dataeval._internal.metrics.utils import normalize_box_shape, normalize_image_shape, rescale
+from dataeval._internal.output import OutputMetadata
+
+DTYPE_REGEX = re.compile(r"NDArray\[np\.(.*?)\]")
+SOURCE_INDEX = "source_index"
+BOX_COUNT = "box_count"
+
+OptionalRange = Optional[Union[int, Iterable[int]]]
+
+
+def matches(index: int | None, opt_range: OptionalRange) -> bool:
+    if index is None or opt_range is None:
+        return True
+    return index in opt_range if isinstance(opt_range, Iterable) else index == opt_range
+
+
+class SourceIndex(NamedTuple):
+    """
+    Attributes
+    ----------
+    image: int
+        Index of the source image
+    box : int | None
+        Index of the box of the source image
+    channel : int | None
+        Index of the channel of the source image
+    """
+
+    image: int
+    box: int | None
+    channel: int | None
+
+
+@dataclass(frozen=True)
+class BaseStatsOutput(OutputMetadata):
+    """
+    Attributes
+    ----------
+    source_index : List[SourceIndex]
+        Mapping from statistic to source image, box and channel index
+    box_count : NDArray[np.uint16]
+    """
+
+    source_index: list[SourceIndex]
+    box_count: NDArray[np.uint16]
+
+    def get_channel_mask(
+        self,
+        channel_index: OptionalRange,
+        channel_count: OptionalRange = None,
+    ) -> list[bool]:
+        """
+        Boolean mask for results filtered to specified channel index and optionally the count
+        of the channels per image.
+
+        Parameters
+        ----------
+        channel_index : int | Iterable[int] | None
+            Index or indices of channel(s) to filter for
+        channel_count : int | Iterable[int] | None
+            Optional count(s) of channels to filter for
+        """
+        mask: list[bool] = []
+        cur_mask: list[bool] = []
+        cur_image = 0
+        cur_max_channel = 0
+        for source_index in list(self.source_index) + [None]:
+            if source_index is None or source_index.image > cur_image:
+                mask.extend(cur_mask if matches(cur_max_channel + 1, channel_count) else [False for _ in cur_mask])
+                if source_index is None:
+                    break
+                cur_image = source_index.image
+                cur_max_channel = 0
+                cur_mask.clear()
+            cur_mask.append(matches(source_index.channel, channel_index))
+            cur_max_channel = max(cur_max_channel, source_index.channel or 0)
+        return mask
+
+    def __len__(self) -> int:
+        return len(self.source_index)
+
+
+class StatsProcessor:
+    cache_keys: list[str] = []
+    image_function_map: dict[str, Callable[[StatsProcessor], Any]] = {}
+    channel_function_map: dict[str, Callable[[StatsProcessor], Any]] = {}
+
+    def __init__(self, image: NDArray, box: NDArray | None, per_channel: bool):
+        self.raw = image
+        self.width = image.shape[-1]
+        self.height = image.shape[-2]
+        self.box = np.array([0, 0, self.width, self.height]) if box is None else box
+        self.per_channel = per_channel
+        self._image = None
+        self._shape = None
+        self._scaled = None
+        self.cache = {}
+        self.fn_map = self.channel_function_map if per_channel else self.image_function_map
+        self.is_valid_slice = box is None or bool(
+            box[0] >= 0 and box[1] >= 0 and box[2] <= image.shape[-1] and box[3] <= image.shape[-2]
+        )
+
+    def get(self, fn_key: str) -> NDArray:
+        if fn_key in self.cache_keys:
+            if fn_key not in self.cache:
+                self.cache[fn_key] = self.fn_map[fn_key](self)
+            return self.cache[fn_key]
+        else:
+            return self.fn_map[fn_key](self)
+
+    @property
+    def image(self) -> NDArray:
+        if self._image is None:
+            if self.is_valid_slice:
+                norm = normalize_image_shape(self.raw)
+                self._image = norm[:, self.box[1] : self.box[3], self.box[0] : self.box[2]]
+            else:
+                self._image = np.zeros((self.raw.shape[0], self.box[3] - self.box[1], self.box[2] - self.box[0]))
+        return self._image
+
+    @property
+    def shape(self) -> tuple:
+        if self._shape is None:
+            self._shape = self.image.shape
+        return self._shape
+
+    @property
+    def scaled(self) -> NDArray:
+        if self._scaled is None:
+            self._scaled = rescale(self.image)
+            if self.per_channel:
+                self._scaled = self._scaled.reshape(self.image.shape[0], -1)
+        return self._scaled
+
+
+def run_stats(
+    images: Iterable[ArrayLike],
+    bboxes: Iterable[ArrayLike] | None,
+    per_channel: bool,
+    stats_processor_cls: type,
+    output_cls: type,
+) -> dict:
+    """
+    Compute specified statistics on a set of images.
+
+    This function applies a set of statistical operations to each image in the input iterable,
+    based on the specified output class. The function determines which statistics to apply
+    using a function map. It also supports optional image flattening for pixel-wise calculations.
+
+    Parameters
+    ----------
+    images : Iterable[ArrayLike]
+        An iterable of images (e.g., list of arrays), where each image is represented as an
+        array-like structure (e.g., NumPy arrays).
+    bboxes : Iterable[ArrayLike]
+        An iterable of bounding boxes (e.g. list of arrays) where each bounding box is represented
+        as an array-like structure in the format of (X0, Y0, X1, Y1). The length of the bounding boxes
+        iterable should match the length of the input images.
+    per_channel : bool
+        A flag which determines if the states should be evaluated on a per-channel basis or not.
+    output_cls : type
+        The output class for which stats values will be calculated.
+
+    Returns
+    -------
+    dict[str, NDArray]]
+        A dictionary containing the computed statistics for each image.
+        The dictionary keys correspond to the names of the statistics, and the values are NumPy arrays
+        with the results of the computations.
+
+    Note
+    ----
+    - The function performs image normalization (rescaling the image values)
+      before applying some of the statistics.
+    - Pixel-level statistics (e.g., brightness, entropy) are computed after
+      rescaling and, optionally, flattening the images.
+    - For statistics like histograms and entropy, intermediate results may
+      be reused to avoid redundant computation.
+    """
+    results_list: list[dict[str, NDArray]] = []
+    output_list = list(output_cls.__annotations__)
+    source_index = []
+    box_count = []
+    bbox_iter = (None for _ in images) if bboxes is None else to_numpy_iter(bboxes)
+
+    for i, (boxes, image) in enumerate(zip(bbox_iter, to_numpy_iter(images))):
+        nboxes = [None] if boxes is None else normalize_box_shape(boxes)
+        for i_b, box in enumerate(nboxes):
+            i_b = None if box is None else i_b
+            processor: StatsProcessor = stats_processor_cls(image, box, per_channel)
+            if not processor.is_valid_slice:
+                warnings.warn(f"Bounding box {i_b}: {box} is out of bounds of image {i}: {image.shape}.")
+            results_list.append({stat: processor.get(stat) for stat in output_list})
+            if per_channel:
+                source_index.extend([SourceIndex(i, i_b, c) for c in range(image.shape[-3])])
+            else:
+                source_index.append(SourceIndex(i, i_b, None))
+        box_count.append(0 if boxes is None else len(boxes))
+
+    output = {}
+    if per_channel:
+        for i, results in enumerate(results_list):
+            for stat, result in results.items():
+                output.setdefault(stat, []).extend(result.tolist())
+    else:
+        for results in results_list:
+            for stat, result in results.items():
+                output.setdefault(stat, []).append(result.tolist() if isinstance(result, np.ndarray) else result)
+
+    for stat in output:
+        stat_type: str = output_cls.__annotations__[stat]
+
+        dtype_match = re.match(DTYPE_REGEX, stat_type)
+        if dtype_match is not None:
+            output[stat] = np.asarray(output[stat], dtype=np.dtype(dtype_match.group(1)))
+
+    output[SOURCE_INDEX] = source_index
+    output[BOX_COUNT] = np.asarray(box_count, dtype=np.uint16)
+
+    return output

dataeval/_internal/metrics/stats/boxratiostats.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import copy
+from typing import Callable, Generic, TypeVar, cast
+
+import numpy as np
+from numpy.typing import NDArray
+
+from dataeval._internal.metrics.stats.base import BOX_COUNT, SOURCE_INDEX, BaseStatsOutput
+from dataeval._internal.metrics.stats.dimensionstats import DimensionStatsOutput
+from dataeval._internal.output import set_metadata
+
+TStatOutput = TypeVar("TStatOutput", bound=BaseStatsOutput, contravariant=True)
+ArraySlice = tuple[int, int]
+
+
+class BoxImageStatsOutputSlice(Generic[TStatOutput]):
+    class StatSlicer:
+        def __init__(self, stats: TStatOutput, slice: ArraySlice, channels: int = 0) -> None:  # noqa: A002
+            self._stats = stats
+            self._slice = slice
+            self._channels = channels
+
+        def __getitem__(self, key: str) -> NDArray[np.float64]:
+            _stat = cast(np.ndarray, getattr(self._stats, key)).astype(np.float64)
+            _shape = _stat[0].shape
+            _slice = _stat[self._slice[0] : self._slice[1]]
+            return _slice.reshape(-1, self._channels, *_shape) if self._channels else _slice.reshape(-1, *_shape)
+
+    box: StatSlicer
+    img: StatSlicer
+    channels: int
+
+    def __init__(
+        self, box_stats: TStatOutput, box_slice: ArraySlice, img_stats: TStatOutput, img_slice: ArraySlice
+    ) -> None:
+        self.channels = img_slice[1] - img_slice[0]
+        self.box = self.StatSlicer(box_stats, box_slice, self.channels)
+        self.img = self.StatSlicer(img_stats, img_slice)
+
+
+RATIOSTATS_OVERRIDE_MAP: dict[type, dict[str, Callable[[BoxImageStatsOutputSlice], NDArray]]] = {
+    DimensionStatsOutput: {
+        "left": lambda x: x.box["left"] / x.img["width"],
+        "top": lambda x: x.box["top"] / x.img["height"],
+        "channels": lambda x: x.box["channels"],
+        "depth": lambda x: x.box["depth"],
+        "distance": lambda x: x.box["distance"],
+    }
+}
+
+
+def get_index_map(stats: BaseStatsOutput) -> list[int]:
+    index_map: list[int] = []
+    cur_index = -1
+    for i, s in enumerate(stats.source_index):
+        if s.image > cur_index:
+            index_map.append(i)
+            cur_index = s.image
+    return index_map
+
+
+def calculate_ratios(key: str, box_stats: BaseStatsOutput, img_stats: BaseStatsOutput) -> NDArray:
+    if not hasattr(box_stats, key) or not hasattr(img_stats, key):
+        raise KeyError("Invalid key for provided stats output object.")
+
+    stats = getattr(box_stats, key)
+
+    # Copy over stats index maps and box counts
+    if key in (SOURCE_INDEX):
+        return copy.deepcopy(stats)
+    elif key == BOX_COUNT:
+        return np.copy(stats)
+
+    # Calculate ratios for each stat
+    out_stats: np.ndarray = np.copy(stats).astype(np.float64)
+
+    box_map = get_index_map(box_stats)
+    img_map = get_index_map(img_stats)
+    for i, (box_i, img_i) in enumerate(zip(box_map, img_map)):
+        box_j = len(box_stats) if i == len(box_map) - 1 else box_map[i + 1]
+        img_j = len(img_stats) if i == len(img_map) - 1 else img_map[i + 1]
+        stats = BoxImageStatsOutputSlice(box_stats, (box_i, box_j), img_stats, (img_i, img_j))
+        out_type = type(box_stats)
+        use_override = out_type in RATIOSTATS_OVERRIDE_MAP and key in RATIOSTATS_OVERRIDE_MAP[out_type]
+        ratio = (
+            RATIOSTATS_OVERRIDE_MAP[out_type][key](stats)
+            if use_override
+            else np.nan_to_num(stats.box[key] / stats.img[key])
+        )
+        out_stats[box_i:box_j] = ratio.reshape(-1, *out_stats[box_i].shape)
+    return out_stats
+
+
+@set_metadata("dataeval.metrics")
+def boxratiostats(
+    boxstats: TStatOutput,
+    imgstats: TStatOutput,
+) -> TStatOutput:
+    """
+    Calculates ratio statistics of box outputs over image outputs
+
+    Parameters
+    ----------
+    boxstats : DimensionStatsOutput | PixelStatsOutput | VisualStatsOutput
+        Box statistics outputs to perform calculations on
+    imgstats : DimensionStatsOutput | PixelStatsOutput | VisualStatsOutput
+        Image statistics outputs to perform calculations on
+
+    Returns
+    -------
+    DimensionStatsOutput | PixelStatsOutput | VisualStatsOutput
+        A dictionary-like object containing the computed ratio of the box statistics divided by the
+        image statistics.
+
+    See Also
+    --------
+    dimensionstats, pixelstats, visualstats
+
+    Note
+    ----
+    DimensionStatsOutput values for channels, depth and distances are the original values
+    provided by the box outputs
+
+    Examples
+    --------
+    Calculating the box ratio statistics using the dimension stats of the boxes and images
+
+    >>> imagestats = dimensionstats(images)
+    >>> boxstats = dimensionstats(images, bboxes)
+    >>> ratiostats = boxratiostats(boxstats, imagestats)
+    >>> print(ratiostats.aspect_ratio)
+    [ 1.15169271  0.78450521 21.33333333  1.5234375   2.25651042  0.77799479
+      0.88867188  3.40625     1.73307292  1.11132812  0.75018315  0.45018315
+      0.69596354 20.          5.11197917  2.33333333  0.75        0.70019531]
+    >>> print(ratiostats.size)
+    [0.03401693 0.01383464 0.00130208 0.01822917 0.02327474 0.00683594
+     0.01220703 0.0168457  0.01057943 0.00976562 0.00130208 0.01098633
+     0.02246094 0.0012207  0.01123047 0.00911458 0.02636719 0.06835938]
+    """
+    output_cls = type(boxstats)
+    if type(boxstats) is not type(imgstats):
+        raise TypeError("Must provide stats outputs of the same type.")
+    if boxstats.source_index[-1].image != imgstats.source_index[-1].image:
+        raise ValueError("Stats index_map length mismatch. Check if the correct box and image stats were provided.")
+    if all(count == 0 for count in boxstats.box_count):
+        raise TypeError("Input for boxstats must contain box information.")
+    if any(count != 0 for count in imgstats.box_count):
+        raise TypeError("Input for imgstats must not contain box information.")
+    boxstats_has_channels = any(si.channel is None for si in boxstats.source_index)
+    imgstats_has_channels = any(si.channel is None for si in imgstats.source_index)
+    if boxstats_has_channels != imgstats_has_channels:
+        raise TypeError("Input for boxstats and imgstats must have matching channel information.")
+
+    output_dict = {}
+    for key in boxstats.dict():
+        output_dict[key] = calculate_ratios(key, boxstats, imgstats)
+
+    return output_cls(**output_dict)

dataeval/_internal/metrics/stats/datasetstats.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from numpy.typing import ArrayLike
+
+from dataeval._internal.metrics.stats.base import BaseStatsOutput
+from dataeval._internal.metrics.stats.dimensionstats import DimensionStatsOutput, dimensionstats
+from dataeval._internal.metrics.stats.labelstats import LabelStatsOutput, labelstats
+from dataeval._internal.metrics.stats.pixelstats import PixelStatsOutput, pixelstats
+from dataeval._internal.metrics.stats.visualstats import VisualStatsOutput, visualstats
+from dataeval._internal.output import OutputMetadata, set_metadata
+
+
+@dataclass(frozen=True)
+class DatasetStatsOutput(OutputMetadata):
+    """
+    Output class for :func:`datasetstats` stats metric
+
+    This class represents the outputs of various stats functions against a single
+    dataset, such that each index across all stat outputs are representative of
+    the same source image.  Modifying or mixing outputs will result in inaccurate
+    outlier calculations if not created correctly.
+
+    Attributes
+    ----------
+    dimensionstats : DimensionStatsOutput or None
+    pixelstats: PixelStatsOutput or None
+    visualstats: VisualStatsOutput or None
+    labelstats: LabelStatsOutput or None, default None
+    """
+
+    dimensionstats: DimensionStatsOutput | None
+    pixelstats: PixelStatsOutput | None
+    visualstats: VisualStatsOutput | None
+    labelstats: LabelStatsOutput | None = None
+
+    def outputs(self) -> list[BaseStatsOutput]:
+        return [s for s in (self.dimensionstats, self.pixelstats, self.visualstats) if s is not None]
+
+    def __post_init__(self):
+        lengths = [len(s) for s in self.outputs()]
+        if not all(length == lengths[0] for length in lengths):
+            raise ValueError("All StatsOutput classes must contain the same number of image sources.")
+
+
+@set_metadata("dataeval.metrics")
+def datasetstats(
+    images: Iterable[ArrayLike],
+    bboxes: Iterable[ArrayLike] | None = None,
+    labels: Iterable[ArrayLike] | None = None,
+    use_dimension: bool = True,
+    use_pixel: bool = True,
+    use_visual: bool = True,
+) -> DatasetStatsOutput:
+    """
+    Calculates various statistics for each image
+
+    This function computes dimension, pixel and visual metrics
+    on the images or individual bounding boxes for each image as
+    well as label statistics if provided.
+
+    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
+    labels : Iterable[ArrayLike] or None
+        Labels of images or boxes to perform calculations on
+
+    Returns
+    -------
+    DatasetStatsOutput
+        Output class containing the outputs of various stats functions
+
+    See Also
+    --------
+    dimensionstats, labelstats, pixelstats, visualstats, Outliers
+
+    Examples
+    --------
+    Calculating the dimension, pixel and visual stats for a dataset with bounding boxes
+
+    >>> stats = datasetstats(images, bboxes)
+    >>> print(stats.dimensionstats.aspect_ratio)
+    [ 0.864   0.5884 16.      1.143   1.692   0.5835  0.6665  2.555   1.3
+      0.8335  1.      0.6     0.522  15.      3.834   1.75    0.75    0.7   ]
+    >>> print(stats.visualstats.contrast)
+    [1.744   1.946   0.1164  0.0635  0.0633  0.06274 0.0429  0.0317  0.0317
+     0.02576 0.02081 0.02171 0.01915 0.01767 0.01799 0.01595 0.01433 0.01478]
+    """
+    return DatasetStatsOutput(
+        dimensionstats(images, bboxes) if use_dimension else None,
+        pixelstats(images, bboxes) if use_pixel else None,
+        visualstats(images, bboxes) if use_visual else None,
+        labelstats(labels) if labels else None,
+    )