peal.data.datasets.ImageDataset

class peal.data.datasets.ImageDataset

Bases: PealDataset

Base class of the image datasets with the explainer-facing callbacks.

Subclasses provide loading (__getitem__, __len__, output_size) and the value-range helpers project_to_pytorch_default/project_from_pytorch_default of PealDataset; this class adds collage rendering, serialization of counterfactual datasets and DINO-feature metrics. A DINOEvaluator is created lazily in dino_eval and fitted on this dataset the first time a metric is requested.

Methods

calculate_outlier_score	Mahalanobis distance of images to the dataset's DINO feature Gaussian.
distribution_distance	Mean DINO-FID of several image batches against the dataset.
flip_rate	Fraction of confidences above 0.5, averaged over samples.
generate_contrastive_collage	Render factual/counterfactual/SSIM-difference collages to PNG files.
pair_wise_distance	Mean DINO-LPIPS between corresponding batches of x1 and x2.
serialize_dataset	Save images (and optional masks) as a class-folder dataset on disk.
track_generator_performance	Compute DINO-feature FID and LPIPS for generated images.
variance	Mean per-sample pixel variance across attempts.

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=0, y_original_teacher_list=None, y_counterfactual_teacher_list=None, feedback_list=None, hint_list=None, idx_to_info=None, tracking_level=1, history_list=None, additional_info=None, **kwargs)

Render factual/counterfactual/SSIM-difference collages to PNG files.

Images are mapped to [0, 1] with project_to_pytorch_default, a high-contrast difference heatmap is computed for every pair and, if tracking_level >= 1, a three-panel figure titled with the labels, confidences, optional latent info, history and teacher feedback is saved as <base_path>/<zero-padded index>_collage.png. Titles longer than 800 characters are truncated to keep matplotlib from failing.

Parameters:

• x_list (list of torch.Tensor) – Images of shape [C, H, W] in the dataset’s value range.

• x_counterfactual_list (list of torch.Tensor) – Images of shape [C, H, W] in the dataset’s value range.

• y_target_list (list) – Target class, predicted source class and ground truth per pair.

• y_source_list (list) – Target class, predicted source class and ground truth per pair.

• y_list (list) – Target class, predicted source class and ground truth per pair.

• y_target_start_confidence_list (list) – Target-class confidence before and after the edit.

• y_target_end_confidence_list (list) – Target-class confidence before and after the edit.

• base_path (str) – Output directory, created if missing; also stored in self.base_path.

• start_idx (int, optional) – Offset added to the running index in the filenames.

• y_original_teacher_list – Teacher verdicts appended to the title when feedback_list is given.

• y_counterfactual_teacher_list – Teacher verdicts appended to the title when feedback_list is given.

• feedback_list – Teacher verdicts appended to the title when feedback_list is given.

• hint_list (list, optional) – Per-sample hints passed on to idx_to_info.

• idx_to_info (callable, optional) – f(x, x_counterfactual, hint) -> str for an extra title line.

• tracking_level (int, optional) – Below 1 no figures are written (paths become None).

• history_list (list, optional) – Per-sample optimisation histories printed into the title.

• additional_info (str, optional) – Free text drawn at the bottom of the figure.

• **kwargs – Ignored.

Returns:

(heatmap_list, collage_paths): difference heatmaps as tensors and the PNG paths (None where nothing was written).

Return type:

tuple

serialize_dataset(output_dir, x_list, y_list, hint_list=[], sample_names=None, classifier=None)

Save images (and optional masks) as a class-folder dataset on disk.

Creates <output_dir>/imgs/<class>/ (and masks/<class>/ when hints are given) for every class, writes each image twice (inside its class folder and directly under imgs/) as 8-bit PNG after project_to_pytorch_default and writes an ImgPath,Class CSV to <output_dir>/<config.label_rel_path> so the result can be loaded again as a PEAL dataset.

Parameters:

• output_dir (str) – Root of the new dataset.

• x_list (list of torch.Tensor) – Images [C, H, W] in this dataset’s value range.

• y_list (list) – Integer class labels.

• hint_list (list of torch.Tensor, optional) – Masks [C, H, W] in [0, 1]; saved when non-empty.

• sample_names (list of str) – File stem per sample (required).

• classifier – Unused.

track_generator_performance(generator, batch_size=None, num_samples=None)

Compute DINO-feature FID and LPIPS for generated images.

Draws num_samples images from the generator (or uses the given tensor), fits the DINOEvaluator on this dataset on first use (for CelebA a shared reference state under $PEAL_RUNS/sce_cfkd/results_for_paper/... is loaded if present) and compares against the first real samples of the dataset.

Parameters:

• generator (Generator or torch.Tensor) – Generator with sample_x or a batch of images [B, C, H, W].

• batch_size (int, optional) – Sampling batch size; defaults to generator.config.batch_size or 1.

• num_samples (int, optional) – Number of generated images evaluated. Defaults to batch_size.

Returns:

fid/dino_fid, lpips/dino_lpips and, if reference_fid is set on the dataset, quality_score in (0, 1].

Return type:

dict

Raises:

NotImplementedError – For unsupported generator types.

calculate_outlier_score(x)

Mahalanobis distance of images to the dataset’s DINO feature Gaussian.

Parameters:

x (torch.Tensor) – Batch [B, C, H, W]; its size is also used as the fitting batch size on first use.

Returns:

{"absolute": scores} plus "relative" (divided by reference_outlier_scores) when that attribute is set.

Return type:

dict

distribution_distance(x_list)

Mean DINO-FID of several image batches against the dataset.

Parameters:

x_list (list) – Batches, each a tensor [B, C, H, W] or a list of images.

Returns:

Average FID over the batches.

Return type:

float

pair_wise_distance(x1, x2)

Mean DINO-LPIPS between corresponding batches of x1 and x2.

Parameters:

• x1 (list) – Equal-length lists of batches (tensor or list of images).

• x2 (list) – Equal-length lists of batches (tensor or list of images).

Returns:

Average pairwise distance over the batches.

Return type:

float

variance(x_list)

Mean per-sample pixel variance across attempts.

Parameters:

x_list (list of list of torch.Tensor) – x_list[j][i] is attempt j for sample i.

Returns:

Variance over attempts, averaged over pixels and samples.

Return type:

float

flip_rate(y_confidence_list)

Fraction of confidences above 0.5, averaged over samples.

Parameters:

y_confidence_list (list of list of torch.Tensor) – Target-class confidences per sample and attempt.

Returns:

Mean flip rate.

Return type:

float