maite-datasets 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

maite_datasets/__init__.py

@@ -1,5 +1,14 @@
 """Module for MAITE compliant Computer Vision datasets."""
 
 from maite_datasets._builder import to_image_classification_dataset, to_object_detection_dataset
+from maite_datasets._collate import collate_as_torch, collate_as_numpy, collate_as_list
+from maite_datasets._validate import validate_dataset
 
-__all__ = ["to_image_classification_dataset", "to_object_detection_dataset"]
+__all__ = [
+    "collate_as_list",
+    "collate_as_numpy",
+    "collate_as_torch",
+    "to_image_classification_dataset",
+    "to_object_detection_dataset",
+    "validate_dataset",
+]

maite_datasets/_collate.py

@@ -0,0 +1,112 @@
+"""
+Collate functions used with a PyTorch DataLoader to load data from MAITE compliant datasets.
+"""
+
+from __future__ import annotations
+
+__all__ = []
+
+from collections.abc import Iterable, Sequence
+from typing import Any, TypeVar, TYPE_CHECKING
+
+import numpy as np
+from numpy.typing import NDArray
+
+if TYPE_CHECKING:
+    import torch
+
+from maite_datasets._protocols import ArrayLike
+
+T_in = TypeVar("T_in")
+T_tgt = TypeVar("T_tgt")
+T_md = TypeVar("T_md")
+
+
+def collate_as_list(
+    batch_data_as_singles: Iterable[tuple[T_in, T_tgt, T_md]],
+) -> tuple[Sequence[T_in], Sequence[T_tgt], Sequence[T_md]]:
+    """
+    A collate function that takes a batch of individual data points in the format
+    (input, target, metadata) and returns three lists: the input batch, the target batch,
+    and the metadata batch. This is useful for loading data with torch.utils.data.DataLoader
+    when the target and metadata are not tensors.
+
+    Parameters
+    ----------
+    batch_data_as_singles : An iterable of (input, target, metadata) tuples.
+
+    Returns
+    -------
+    tuple[Sequence[T_in], Sequence[T_tgt], Sequence[T_md]]
+        A tuple of three lists: the input batch, the target batch, and the metadata batch.
+    """
+    input_batch: list[T_in] = []
+    target_batch: list[T_tgt] = []
+    metadata_batch: list[T_md] = []
+    for input_datum, target_datum, metadata_datum in batch_data_as_singles:
+        input_batch.append(input_datum)
+        target_batch.append(target_datum)
+        metadata_batch.append(metadata_datum)
+
+    return input_batch, target_batch, metadata_batch
+
+
+def collate_as_numpy(
+    batch_data_as_singles: Iterable[tuple[ArrayLike, T_tgt, T_md]],
+) -> tuple[NDArray[Any], Sequence[T_tgt], Sequence[T_md]]:
+    """
+    A collate function that takes a batch of individual data points in the format
+    (input, target, metadata) and returns the batched input as a single NumPy array with two
+    lists: the target batch, and the metadata batch. The inputs must be homogeneous arrays.
+
+    Parameters
+    ----------
+    batch_data_as_singles : An iterable of (ArrayLike, target, metadata) tuples.
+
+    Returns
+    -------
+    tuple[NDArray[Any], Sequence[T_tgt], Sequence[T_md]]
+        A tuple of a NumPy array and two lists: the input batch, the target batch, and the metadata batch.
+    """
+    input_batch: list[NDArray[Any]] = []
+    target_batch: list[T_tgt] = []
+    metadata_batch: list[T_md] = []
+    for input_datum, target_datum, metadata_datum in batch_data_as_singles:
+        input_batch.append(np.asarray(input_datum))
+        target_batch.append(target_datum)
+        metadata_batch.append(metadata_datum)
+
+    return np.stack(input_batch) if input_batch else np.array([]), target_batch, metadata_batch
+
+
+def collate_as_torch(
+    batch_data_as_singles: Iterable[tuple[ArrayLike, T_tgt, T_md]],
+) -> tuple[torch.Tensor, Sequence[T_tgt], Sequence[T_md]]:
+    """
+    A collate function that takes a batch of individual data points in the format
+    (input, target, metadata) and returns the batched input as a single torch Tensor with two
+    lists: the target batch, and the metadata batch. The inputs must be homogeneous arrays.
+
+    Parameters
+    ----------
+    batch_data_as_singles : An iterable of (ArrayLike, target, metadata) tuples.
+
+    Returns
+    -------
+    tuple[torch.Tensor, Sequence[T_tgt], Sequence[T_md]]
+        A tuple of a torch Tensor and two lists: the input batch, the target batch, and the metadata batch.
+    """
+    try:
+        import torch
+    except ImportError:
+        raise ImportError("PyTorch is not installed. Please install it to use this function.")
+
+    input_batch: list[torch.Tensor] = []
+    target_batch: list[T_tgt] = []
+    metadata_batch: list[T_md] = []
+    for input_datum, target_datum, metadata_datum in batch_data_as_singles:
+        input_batch.append(torch.as_tensor(input_datum))
+        target_batch.append(target_datum)
+        metadata_batch.append(metadata_datum)
+
+    return torch.stack(input_batch) if input_batch else torch.tensor([]), target_batch, metadata_batch

maite_datasets/_validate.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+__all__ = []
+
+import numpy as np
+from collections.abc import Sequence, Sized
+from typing import Any, Literal
+
+from maite_datasets._protocols import Array, ObjectDetectionTarget
+
+
+class ValidationMessages:
+    DATASET_SIZED = "Dataset must be sized."
+    DATASET_INDEXABLE = "Dataset must be indexable."
+    DATASET_NONEMPTY = "Dataset must be non-empty."
+    DATASET_METADATA = "Dataset must have a 'metadata' attribute."
+    DATASET_METADATA_TYPE = "Dataset metadata must be a dictionary."
+    DATASET_METADATA_FORMAT = "Dataset metadata must contain an 'id' key."
+    DATUM_TYPE = "Dataset datum must be a tuple."
+    DATUM_FORMAT = "Dataset datum must contain 3 elements: image, target, metadata."
+    DATUM_IMAGE_TYPE = "Images must be 3-dimensional arrays."
+    DATUM_IMAGE_FORMAT = "Images must be in CHW format."
+    DATUM_TARGET_IC_TYPE = "ImageClassificationDataset targets must be one-dimensional arrays."
+    DATUM_TARGET_IC_FORMAT = "ImageClassificationDataset targets must be one-hot encoded or pseudo-probabilities."
+    DATUM_TARGET_OD_TYPE = "ObjectDetectionDataset targets must be have 'boxes', 'labels' and 'scores'."
+    DATUM_TARGET_OD_LABELS_TYPE = "ObjectDetectionTarget labels must be one-dimensional (N,) arrays."
+    DATUM_TARGET_OD_BOXES_TYPE = "ObjectDetectionTarget boxes must be two-dimensional (N, 4) arrays in xxyy format."
+    DATUM_TARGET_OD_SCORES_TYPE = "ObjectDetectionTarget scores must be one (N,) or two-dimensional (N, M) arrays."
+    DATUM_TARGET_TYPE = "Target is not a valid ImageClassification or ObjectDetection target type."
+    DATUM_METADATA_TYPE = "Datum metadata must be a dictionary."
+    DATUM_METADATA_FORMAT = "Datum metadata must contain an 'id' key."
+
+
+def _validate_dataset_type(dataset: Any) -> list[str]:
+    issues = []
+    is_sized = isinstance(dataset, Sized)
+    is_indexable = hasattr(dataset, "__getitem__")
+    if not is_sized:
+        issues.append(ValidationMessages.DATASET_SIZED)
+    if not is_indexable:
+        issues.append(ValidationMessages.DATASET_INDEXABLE)
+    if is_sized and len(dataset) == 0:
+        issues.append(ValidationMessages.DATASET_NONEMPTY)
+    return issues
+
+
+def _validate_dataset_metadata(dataset: Any) -> list[str]:
+    issues = []
+    if not hasattr(dataset, "metadata"):
+        issues.append(ValidationMessages.DATASET_METADATA)
+    metadata = getattr(dataset, "metadata", None)
+    if not isinstance(metadata, dict):
+        issues.append(ValidationMessages.DATASET_METADATA_TYPE)
+    if not isinstance(metadata, dict) or "id" not in metadata:
+        issues.append(ValidationMessages.DATASET_METADATA_FORMAT)
+    return issues
+
+
+def _validate_datum_type(datum: Any) -> list[str]:
+    issues = []
+    if not isinstance(datum, tuple):
+        issues.append(ValidationMessages.DATUM_TYPE)
+    if datum is None or isinstance(datum, Sized) and len(datum) != 3:
+        issues.append(ValidationMessages.DATUM_FORMAT)
+    return issues
+
+
+def _validate_datum_image(image: Any) -> list[str]:
+    issues = []
+    if not isinstance(image, Array) or len(image.shape) != 3:
+        issues.append(ValidationMessages.DATUM_IMAGE_TYPE)
+    if (
+        not isinstance(image, Array)
+        or len(image.shape) == 3
+        and (image.shape[0] > image.shape[1] or image.shape[0] > image.shape[2])
+    ):
+        issues.append(ValidationMessages.DATUM_IMAGE_FORMAT)
+    return issues
+
+
+def _validate_datum_target_ic(target: Any) -> list[str]:
+    issues = []
+    if not isinstance(target, Array) or len(target.shape) != 1:
+        issues.append(ValidationMessages.DATUM_TARGET_IC_TYPE)
+    if target is None or sum(target) > 1 + 1e-6 or sum(target) < 1 - 1e-6:
+        issues.append(ValidationMessages.DATUM_TARGET_IC_FORMAT)
+    return issues
+
+
+def _validate_datum_target_od(target: Any) -> list[str]:
+    issues = []
+    if not isinstance(target, ObjectDetectionTarget):
+        issues.append(ValidationMessages.DATUM_TARGET_OD_TYPE)
+    od_target: ObjectDetectionTarget | None = target if isinstance(target, ObjectDetectionTarget) else None
+    if od_target is None or len(np.asarray(od_target.labels).shape) != 1:
+        issues.append(ValidationMessages.DATUM_TARGET_OD_LABELS_TYPE)
+    if (
+        od_target is None
+        or len(np.asarray(od_target.boxes).shape) != 2
+        or (len(np.asarray(od_target.boxes).shape) == 2 and np.asarray(od_target.boxes).shape[1] != 4)
+    ):
+        issues.append(ValidationMessages.DATUM_TARGET_OD_BOXES_TYPE)
+    if od_target is None or len(np.asarray(od_target.scores).shape) not in (1, 2):
+        issues.append(ValidationMessages.DATUM_TARGET_OD_SCORES_TYPE)
+    return issues
+
+
+def _detect_target_type(target: Any) -> Literal["ic", "od", "auto"]:
+    if isinstance(target, Array):
+        return "ic"
+    if isinstance(target, ObjectDetectionTarget):
+        return "od"
+    return "auto"
+
+
+def _validate_datum_target(target: Any, target_type: Literal["ic", "od", "auto"]) -> list[str]:
+    issues = []
+    target_type = _detect_target_type(target) if target_type == "auto" else target_type
+    if target_type == "ic":
+        issues.extend(_validate_datum_target_ic(target))
+    elif target_type == "od":
+        issues.extend(_validate_datum_target_od(target))
+    else:
+        issues.append(ValidationMessages.DATUM_TARGET_TYPE)
+    return issues
+
+
+def _validate_datum_metadata(metadata: Any) -> list[str]:
+    issues = []
+    if metadata is None or not isinstance(metadata, dict):
+        issues.append(ValidationMessages.DATUM_METADATA_TYPE)
+    if metadata is None or isinstance(metadata, dict) and "id" not in metadata:
+        issues.append(ValidationMessages.DATUM_METADATA_FORMAT)
+    return issues
+
+
+def validate_dataset(dataset: Any, dataset_type: Literal["ic", "od", "auto"] = "auto") -> None:
+    """
+    Validate a dataset for compliance with MAITE protocol.
+
+    Parameters
+    ----------
+    dataset: Any
+        Dataset to validate.
+    dataset_type: "ic", "od", or "auto", default "auto"
+        Dataset type, if known.
+
+    Raises
+    ------
+    ValueError
+        Raises exception if dataset is invalid with a list of validation issues.
+    """
+    issues = []
+    issues.extend(_validate_dataset_type(dataset))
+    datum = None if issues else dataset[0]  # type: ignore
+    issues.extend(_validate_dataset_metadata(dataset))
+    issues.extend(_validate_datum_type(datum))
+
+    is_seq = isinstance(datum, Sequence)
+    datum_len = len(datum) if is_seq else 0
+    image = datum[0] if is_seq and datum_len > 0 else None
+    target = datum[1] if is_seq and datum_len > 1 else None
+    metadata = datum[2] if is_seq and datum_len > 2 else None
+    issues.extend(_validate_datum_image(image))
+    issues.extend(_validate_datum_target(target, dataset_type))
+    issues.extend(_validate_datum_metadata(metadata))
+
+    if issues:
+        raise ValueError("Dataset validation issues found:\n - " + "\n - ".join(issues))

{maite_datasets-0.0.2.dist-info → maite_datasets-0.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maite-datasets
-Version: 0.0.2
+Version: 0.0.3
 Summary: A collection of Image Classification and Object Detection task datasets conforming to the MAITE protocol.
 Author-email: Andrew Weng <andrew.weng@ariacoustics.com>, Ryan Wood <ryan.wood@ariacoustics.com>, Shaun Jullens <shaun.jullens@ariacoustics.com>
 License-Expression: MIT

{maite_datasets-0.0.2.dist-info → maite_datasets-0.0.3.dist-info}/RECORD

@@ -1,9 +1,11 @@
-maite_datasets/__init__.py,sha256=aM16hWPYR5WF0nx2AqTYHbGmibNTBCrYilcDKUs_yPo,235
+maite_datasets/__init__.py,sha256=81LNxx03O7FzWNZQbIrSovDrdpO_x74WkLPKBJy91gU,483
 maite_datasets/_base.py,sha256=BiWB_xvL4AtV0jxVjzpcZHuRTb52dTD0CQtu08DzoXA,8195
 maite_datasets/_builder.py,sha256=URhRCedvuqsy88N4lzQrwI-uL1kS1_kavP9fS402sPw,10036
+maite_datasets/_collate.py,sha256=-XuKeeMmOnSB0RgQbz8BjsoqQar9Tsf_qALZxijQ498,4063
 maite_datasets/_fileio.py,sha256=7S-hF3xU60AdcsPsfYR7rjbeGZUlv3JjGEZhGJOxGYU,5622
 maite_datasets/_protocols.py,sha256=uwnI2P-zJnpEHJ0eOJ7dO_7KehwHEtEqR4pYcJiEXNk,5312
 maite_datasets/_types.py,sha256=S5DMyiUrkUjV9uM0ysKqxVoi7z5P7B3EPiLI4Fyq9Jc,1147
+maite_datasets/_validate.py,sha256=sP-5lYXkmkiTadJcy_LtEMiZ0m82xR0yELoxWORrZDQ,6904
 maite_datasets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 maite_datasets/_mixin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 maite_datasets/_mixin/_numpy.py,sha256=GEuRyeprH-STh-_zktAp0Tg6NNyMdh1ThyhjW558NOo,860
@@ -18,7 +20,7 @@ maite_datasets/object_detection/_milco.py,sha256=KEU4JFvCxfyMAb4RFMnxTMk_MggdEAV
 maite_datasets/object_detection/_seadrone.py,sha256=w_pSojLzgwdKrUSxaz8r7dPJVKGND6JSYl0S_BKOLH0,271282
 maite_datasets/object_detection/_voc.py,sha256=VuokKaOzI1wSfgG5DC7ufMbRDlG-b6Se3hg4eQzNQbE,19731
 maite_datasets/object_detection/_voc_torch.py,sha256=bjeawnNit7Llcf_cZY_9lcJYoUoAU-Wen6MMT-7QX3k,2917
-maite_datasets-0.0.2.dist-info/METADATA,sha256=O3RGToBWSFhEyi_iAdnc8pqYSVzNRXo_XjIQBOEIEWA,3747
-maite_datasets-0.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-maite_datasets-0.0.2.dist-info/licenses/LICENSE,sha256=6h3J3R-ajGHh_isDSftzS5_jJjB9HH4TaI0vU-VscaY,1082
-maite_datasets-0.0.2.dist-info/RECORD,,
+maite_datasets-0.0.3.dist-info/METADATA,sha256=hoOvbKjGriS10siM8HsRvepA3nfi-QgUcrpjGsHr1lM,3747
+maite_datasets-0.0.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+maite_datasets-0.0.3.dist-info/licenses/LICENSE,sha256=6h3J3R-ajGHh_isDSftzS5_jJjB9HH4TaI0vU-VscaY,1082
+maite_datasets-0.0.3.dist-info/RECORD,,