peal.data.interfaces.PealDataset

class peal.data.interfaces.PealDataset

Bases: Dataset

Base class of every dataset in PEAL.

Subclasses (see peal.data.datasets and custom_datasets) hold a config (DataConfig) and usually a normalization transform. The methods defined here are defaults/hooks: most return placeholders and are meant to be overridden when a dataset supports the corresponding feature. project_to_pytorch_default/project_from_pytorch_default are the bridge between the classifier’s input format and the generator’s image format and are used by every counterfactual explainer.

Methods

distribution_distance	Hook: distance of x_list to the data distribution (returns None).
flip_rate	Hook: fraction of counterfactuals whose label differs (returns None).
generate_contrastive_collage	Render original/counterfactual pairs for teachers and tracking (hook).
pair_wise_distance	Hook: distance between two samples in dataset units (returns None).
project_from_pytorch_default	This function maps pytorch default image to the processed format
project_to_pytorch_default	This function maps processed data sample back to pytorch default format
serialize_dataset	This function serializes the dataset to a given directory
track_generator_performance	This function tracks the performance of the generator
variance	Hook: diversity/variance of a list of samples (returns None).

generate_contrastive_collage(x_list, x_counterfactual_list, y_target_list, y_source_list, y_list, y_target_start_confidence_list, y_target_end_confidence_list, base_path, start_idx, y_counterfactual_teacher_list=None, y_original_teacher_list=None, feedback_list=None, **kwargs)

Render original/counterfactual pairs for teachers and tracking (hook).

Subclasses write one collage image per pair under base_path and return the paths plus per-sample attribution maps; teachers such as BaselineTeacher or Model2ModelTeacher call this to show or log the counterfactuals they judge.

Parameters:

• x_list (list of torch.Tensor) – Originals and their counterfactuals, in dataset format.

• x_counterfactual_list (list of torch.Tensor) – Originals and their counterfactuals, in dataset format.

• y_target_list (list) – Target class of the edit, class predicted for the original, and ground-truth label.

• y_source_list (list) – Target class of the edit, class predicted for the original, and ground-truth label.

• y_list (list) – Target class of the edit, class predicted for the original, and ground-truth label.

• y_target_start_confidence_list (list) – Student confidence in the target class before and after the edit.

• y_target_end_confidence_list (list) – Student confidence in the target class before and after the edit.

• base_path (str) – Directory to write the collages to.

• start_idx (int) – Offset used to number the written files.

• y_counterfactual_teacher_list (list, optional) – Teacher-model predictions, if available.

• y_original_teacher_list (list, optional) – Teacher-model predictions, if available.

• feedback_list (list, optional) – Feedback strings to print onto the collage.

• kwargs (dict)

Returns:

This base implementation only returns a (3, 64, 64) zero tensor. Overrides return (collage_paths, attribution_list).

Return type:

torch.Tensor

serialize_dataset(output_dir, x_list, y_list, sample_names=None)

This function serializes the dataset to a given directory

Parameters:

• output_dir (Path) – The output directory

• x_list (list) – The list of inputs

• y_list (list) – The list of labels

• sample_names (list, optional) – The list of sample names. Defaults to None.

project_to_pytorch_default(x)

This function maps processed data sample back to pytorch default format

Parameters:

x (torch.tensor) – The data sample in the processed format

Returns:

The data sample in the pytorch default format

Return type:

torch.tensor

project_from_pytorch_default(x)

This function maps pytorch default image to the processed format

Parameters:

x (torch.tensor) – The data sample in the pytorch default format

Returns:

The data sample in the processed format

Return type:

torch.tensor

track_generator_performance(generator, batch_size=1)

This function tracks the performance of the generator

Parameters:

generator (Generator) – The generator

distribution_distance(x_list)

Hook: distance of x_list to the data distribution (returns None).

pair_wise_distance(x1, x2)

Hook: distance between two samples in dataset units (returns None).

variance(x_list)

Hook: diversity/variance of a list of samples (returns None).

flip_rate(y_list, y_counterfactual_list)

Hook: fraction of counterfactuals whose label differs (returns None).