heart_library package¶

Subpackages¶

Submodules¶

heart_library.config module¶

This module loads and provides configuration parameters for HEART

heart_library.config.set_data_path(path: str) → None[source]¶

Set the path for HEART’s data directory (HEART_DATA_PATH).

Parameters:: path (str) – data path.
Raises:: OSError – if path cannot be read from.

heart_library.utils module¶

Utility methods for converting data types to ART compatible versions.

class heart_library.utils.ImageDataset(images: list[ndarray[Any, dtype[float32]]], targets: ndarray[Any, dtype[float32]], metadata: list[dict[str, Any]], metadata_id: str | None = None)[source]¶

Bases: object

MAITE aligned dataset

Examples

We can define a white-box attack and generate adversarial images:

>>> import numpy as np
>>> import torch
>>> import torchvision
>>> from heart_library.estimators.classification.pytorch import JaticPyTorchClassifier
>>> from heart_library.utils import ImageDataset
>>> from datasets import load_dataset
>>> from heart_library.metrics import AccuracyPerturbationMetric
>>> from heart_library.attacks.attack import JaticAttack
>>> from art.attacks.evasion import ProjectedGradientDescentPyTorch
>>> from copy import deepcopy
>>> from torchvision import transforms

Load an applicable dataset:

>>> data = load_dataset("CDAO/xview-subset-classification", split="test[0:14]")

Define the model:

>>> model = torchvision.models.resnet18(False)
>>> _ = model.eval()

Wrap the model:

>>> jptc = JaticPyTorchClassifier(
...     model=model,
...     loss=torch.nn.CrossEntropyLoss(),
...     input_shape=(3, 224, 224),
...     nb_classes=6,
...     clip_values=(0, 1),
... )

Transform dataset:

>>> IMAGE_H, IMAGE_W = 224, 224

>>> preprocess = transforms.Compose([transforms.Resize((IMAGE_H, IMAGE_W)), transforms.ToTensor()])

>>> data = data.map(lambda x: {"image": preprocess(x["image"]), "label": x["label"]})
>>> to_image = lambda x: transforms.ToPILImage()(torch.Tensor(x))

Define and wrap the attacks:

>>> evasion_attack_undefended = ProjectedGradientDescentPyTorch(estimator=jptc, max_iter=10, eps=0.03)
>>> attack_undefended = JaticAttack(evasion_attack_undefended, norm=2)

Generate adversarial images:

>>> x_adv, y, metadata = attack_undefended(data=data)

>>> data_with_detections = ImageDataset(data, deepcopy(jptc(data)), metadata)

metadata: dict[str, Any]¶

heart_library.utils.adjust_bboxes_resize(bboxes: list[list[float]], original_width: int, original_height: int, target_width: int = 640, target_height: int = 640) → list[list[float]][source]¶

Adjust bounding boxes for images resized to a fixed width and height (640x640).

Parameters:

bboxes (list of lists) – Bounding boxes in [x, y, width, height] format.
original_width (int) – Original width of the image.
original_height (int) – Original height of the image.
target_width (int) – Target width of the resized image.
target_height (int) – Target height of the resized image.

Returns:

Adjusted bounding boxes in [x_min, y_min, x_max, y_max] format.

Return type:

list of lists

heart_library.utils.hf_dataset_to_maite(dataset: Any, image_label: str = '', target_label: str = '', meta_label: str = '', indices: Sequence[int] | None = None) → ImageDataset[source]¶

Convert HF dataset to MAITE aligned dataset

Parameters:

dataset (Any) – Image data.
image_label (str, optional) – Image label. Defaults to EMPTY_STRING.
target_label (str, optional) – Target label. Defaults to EMPTY_STRING.
meta_label (str, optional) – Metadata label. Defaults to EMPTY_STRING.
indices (Optional[Sequence[int]], optional) – Indices. Defaults to None.

Raises:

ValueError – if image feature not found in dataset.
ValueError – if image feature not found in dataset.

Returns:

MAITE aligned dataset.

Return type:

ImageDataset

heart_library.utils.process_inputs_for_art(data: Any) → tuple[ndarray[Any, dtype[float32]], ndarray[Any, dtype[float32]] | list[dict[str, Any]] | None, list[dict[str, Any]]][source]¶

Convert JATIC supported data to ART supported data.

Parameters:

data (Any) – JATIC supported data.

Raises:

ValueError – if Dataset does not implement __getitem__ or __iter__.
ValueError – if Images and targets are not the same length.
ValueError – if Images are empty.

Returns:

ART supported data.

Return type:

Tuple[NDArray[np.float32], Optional[Union[NDArray[np.float32], List[dict[str, Any]]]], List[dict[str, Any]]]

heart_library.utils.torch_subset_to_maite(dataset: Any) → ImageDataset[source]¶

Convert Torch subset dataset to MAITE aligned dataset.

Parameters:: dataset (Any) – Torch dataset.
Returns:: MAITE aligned dataset.
Return type:: ImageDataset

Module contents¶

The HEART extension.