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

dataeval/_internal/interop.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from importlib import import_module
-from typing import Iterable
+from typing import Any, Iterable, Iterator
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
@@ -22,24 +22,28 @@ def try_import(module_name):
     return module
 
 
-def to_numpy(array: ArrayLike | None) -> NDArray:
+def as_numpy(array: ArrayLike | None) -> NDArray[Any]:
+    return to_numpy(array, copy=False)
+
+
+def to_numpy(array: ArrayLike | None, copy: bool = True) -> NDArray[Any]:
     if array is None:
         return np.ndarray([])
 
     if isinstance(array, np.ndarray):
-        return array
+        return array.copy() if copy else array
 
     tf = try_import("tensorflow")
     if tf and tf.is_tensor(array):
-        return array.numpy()  # type: ignore
+        return array.numpy().copy() if copy else array.numpy()  # type: ignore
 
     torch = try_import("torch")
     if torch and isinstance(array, torch.Tensor):
-        return array.detach().cpu().numpy()  # type: ignore
+        return array.detach().cpu().numpy().copy() if copy else array.detach().cpu().numpy()  # type: ignore
 
-    return np.asarray(array)
+    return np.array(array, copy=copy)
 
 
-def to_numpy_iter(iterable: Iterable[ArrayLike]):
+def to_numpy_iter(iterable: Iterable[ArrayLike]) -> Iterator[NDArray[Any]]:
     for array in iterable:
         yield to_numpy(array)

dataeval/_internal/metrics/balance.py

@@ -2,10 +2,10 @@ from __future__ import annotations
 
 import warnings
 from dataclasses import dataclass
-from typing import Sequence
+from typing import Mapping
 
 import numpy as np
-from numpy.typing import NDArray
+from numpy.typing import ArrayLike, NDArray
 from sklearn.feature_selection import mutual_info_classif, mutual_info_regression
 
 from dataeval._internal.metrics.utils import entropy, preprocess_metadata
@@ -51,16 +51,16 @@ def validate_num_neighbors(num_neighbors: int) -> int:
 
 
 @set_metadata("dataeval.metrics")
-def balance(class_labels: Sequence[int], metadata: list[dict], num_neighbors: int = 5) -> BalanceOutput:
+def balance(class_labels: ArrayLike, metadata: Mapping[str, ArrayLike], num_neighbors: int = 5) -> BalanceOutput:
     """
     Mutual information (MI) between factors (class label, metadata, label/image properties)
 
     Parameters
     ----------
-    class_labels: Sequence[int]
+    class_labels: ArrayLike
         List of class labels for each image
-    metadata: List[Dict]
-        List of metadata factors for each image
+    metadata: Mapping[str, ArrayLike]
+        Dict of lists of metadata factors for each image
     num_neighbors: int, default 5
         Number of nearest neighbors to use for computing MI between discrete
         and continuous variables.
@@ -90,9 +90,9 @@ def balance(class_labels: Sequence[int], metadata: list[dict], num_neighbors: in
     Return intra/interfactor balance (mutual information)
 
     >>> bal.factors
-    array([[0.99999843, 0.03510422, 0.09725766],
-           [0.03510422, 0.08433558, 0.15621459],
-           [0.09725766, 0.15621459, 0.99999856]])
+    array([[0.99999843, 0.04133555, 0.09725766],
+           [0.04133555, 0.08433558, 0.1301489 ],
+           [0.09725766, 0.1301489 , 0.99999856]])
 
     Return classwise balance (mutual information) of factors with individual class_labels
 

dataeval/_internal/metrics/ber.py

@@ -17,7 +17,7 @@ from numpy.typing import ArrayLike, NDArray
 from scipy.sparse import coo_matrix
 from scipy.stats import mode
 
-from dataeval._internal.interop import to_numpy
+from dataeval._internal.interop import as_numpy
 from dataeval._internal.metrics.utils import compute_neighbors, get_classes_counts, get_method, minimum_spanning_tree
 from dataeval._internal.output import OutputMetadata, set_metadata
 
@@ -145,7 +145,7 @@ def ber(images: ArrayLike, labels: ArrayLike, k: int = 1, method: Literal["KNN",
     BEROutput(ber=0.04, ber_lower=0.020416847668728033)
     """
     ber_fn = get_method(BER_FN_MAP, method)
-    X = to_numpy(images)
-    y = to_numpy(labels)
+    X = as_numpy(images)
+    y = as_numpy(labels)
     upper, lower = ber_fn(X, y, k) if method == "KNN" else ber_fn(X, y)
     return BEROutput(upper, lower)

dataeval/_internal/metrics/divergence.py

@@ -9,7 +9,7 @@ from typing import Literal
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
 
-from dataeval._internal.interop import to_numpy
+from dataeval._internal.interop import as_numpy
 from dataeval._internal.metrics.utils import compute_neighbors, get_method, minimum_spanning_tree
 from dataeval._internal.output import OutputMetadata, set_metadata
 
@@ -123,8 +123,8 @@ def divergence(data_a: ArrayLike, data_b: ArrayLike, method: Literal["FNN", "MST
     DivergenceOutput(divergence=0.28, errors=36.0)
     """
     div_fn = get_method(DIVERGENCE_FN_MAP, method)
-    a = to_numpy(data_a)
-    b = to_numpy(data_b)
+    a = as_numpy(data_a)
+    b = as_numpy(data_b)
     N = a.shape[0]
     M = b.shape[0]
 

dataeval/_internal/metrics/diversity.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Literal, Sequence
+from typing import Literal, Mapping
 
 import numpy as np
-from numpy.typing import NDArray
+from numpy.typing import ArrayLike, NDArray
 
 from dataeval._internal.metrics.utils import entropy, get_counts, get_method, get_num_bins, preprocess_metadata
 from dataeval._internal.output import OutputMetadata, set_metadata
@@ -142,7 +142,7 @@ DIVERSITY_FN_MAP = {"simpson": diversity_simpson, "shannon": diversity_shannon}
 
 @set_metadata("dataeval.metrics")
 def diversity(
-    class_labels: Sequence[int], metadata: list[dict], method: Literal["shannon", "simpson"] = "simpson"
+    class_labels: ArrayLike, metadata: Mapping[str, ArrayLike], method: Literal["shannon", "simpson"] = "simpson"
 ) -> DiversityOutput:
     """
     Compute diversity and classwise diversity for discrete/categorical variables and, through standard
@@ -155,10 +155,10 @@ def diversity(
 
     Parameters
     ----------
-    class_labels: Sequence[int]
+    class_labels: ArrayLike
         List of class labels for each image
-    metadata: List[Dict]
-        List of metadata factors for each image
+    metadata: Mapping[str, ArrayLike]
+        Dict of list of metadata factors for each image
     method: Literal["shannon", "simpson"], default "simpson"
         Indicates which diversity index should be computed
 

dataeval/_internal/metrics/parity.py

@@ -62,8 +62,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 +80,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 +102,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 +110,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:
@@ -187,7 +184,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,
         )
 
 
@@ -280,8 +278,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 +291,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.
@@ -329,21 +330,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 +403,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.
+
+    Notes
+    -----
+    - 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)