peal.data.datasets.Image2MixedDataset

class peal.data.datasets.Image2MixedDataset

Bases: ImageDataset

Image dataset with multi-attribute CSV labels (CelebA-style).

Images live under <root_dir>/<config.x_selection>/ and are looked up by the keys of the label CSV <root_dir>/<config.label_rel_path> (see image_name/open_image for the tolerated filename variants); optional masks live under <root_dir>/masks/. Attribute names of the form A_vs_B yield the positive/negative phrases used for text descriptions. Targets are the task_config.y_selection attributes (or the first config.output_size[0] columns); with a "ce" criterion the single target is returned as an int64 class index. config.class_ratios subsamples the split to fixed class proportions. If the subclass defines sample_to_2d_latent, decision boundary and global counterfactual plots become available.

Parameters:

• config (DataConfig) – Uses dataset_path, label_rel_path, x_selection, delimiter, set_negative_to_zero, input_size, output_size, class_ratios, has_hints, in_memory and confounding_factors.

• mode (str) – Split: "train", "val", "test" or "all".

• root_dir (str, optional) – Dataset root; overrides and rewrites config.dataset_path.

• data_dir (str, optional) – Path of the label CSV. Defaults to <root_dir>/<label_rel_path>.

• transform (callable, optional) – Applied to the PIL image (and, with the same RNG state, to the mask). Defaults to ToTensor().

• task_config (TaskConfig, optional) – Target selection, output_channels and criterions.

• return_dict (bool, optional) – Return a dict from __getitem__ instead of (x, y...).

Variables:

• attributes (list of str) – CSV column names; attributes_positive/attributes_negative hold the description phrases.

• keys (list of str) – Image keys of the (possibly class-balanced or restricted) split.

• data (dict) – Key to label tensor.

Methods

disable_class_restriction	Restore backup_keys (note: class_restrictions_enabled stays True).
disable_groups	Stop returning has_confounder.
disable_hints	Stop returning masks.
disable_idx	Stop returning the sample index.
disable_string_description	Stop returning the text description.
disable_tokens	Drop the tokenizer and restore the previous description setting.
disable_url	Stop returning the image key.
enable_class_restriction	Keep only samples whose first selected target equals class_idx.
enable_groups	Also return has_confounder from the confounding_factors columns.
enable_hints	Also return the mask from <root_dir>/masks as hint.
enable_idx	Also return the sample index.
enable_string_description	Also return a text description built from the target attributes.
enable_tokens	Also return tokens: the description tokenized with tokenizer.
enable_url	Also return the image key as url.
generate_contrastive_collage	Collage rendering that adds the 2D latent coordinates to the title.
global_counterfactual_visualization	Generalized global counterfactual visualization using sample_to_2d_latent.
image_name	The image filename a dataset key refers to (keys may omit the suffix).
load_in_memory	Cache every image (and mask, if config.has_hints) as a numpy array.
open_image	Open an image by filename, tolerating .jpg/.png and zero-padded variants.
set_task_specific_keys	Subsample keys so the classes follow config.class_ratios.
visualize_decision_boundary	Generalized decision boundary visualization using sample_to_2d_latent.

Attributes

output_size

task_config.output_channels when targets are selected, else columns.

visualize_decision_boundary(predictor, batch_size, device, path, temperature=1.0, train_dataloader=None, val_dataloaders=[], val_weights=[], test_dataloader=None)

Generalized decision boundary visualization using sample_to_2d_latent.

Uses the balanced test dataset to fit a linear model in the 2D latent space, then visualizes the decision boundary with train/val/test sample overlays.

Requires self.sample_to_2d_latent (returns silently otherwise). A logistic regression on the test latents (fitted on the predictor’s predictions) yields a probability grid that is saved as <path minus .png>.npy and ..._bounds.npy for global_counterfactual_visualization; the test plot goes to decision_boundary_test.png next to path and the train/val plot to path. Marker fill shows the prediction, edge the label.

Parameters:

• predictor (torch.nn.Module) – Classifier evaluated on device.

• batch_size (int) – Unused; kept for interface compatibility.

• device (torch.device or str) – Device for predictor and latent extraction.

• path (str) – Output PNG of the train/val plot.

• temperature (float, optional) – Unused.

• train_dataloader (DataLoader or DataloaderMixer, optional) – Up to 8 batches are plotted.

• val_dataloaders (list or WeightedDataloaderList, optional) – Validation loaders; val_weights scales the batch budget.

• val_weights (list of float, optional)

• test_dataloader (DataLoader, optional) – Up to 16 batches define the latent range and fit the model.

global_counterfactual_visualization(filename, x_list, counterfactuals, y_target_start_confidence, y_target_end_confidence, y_list, hint_list, attempts=1)

Generalized global counterfactual visualization using sample_to_2d_latent.

Picks up to 10 samples of each of the first two classes seen in y_list (plus their extra attempts), maps factuals and counterfactuals to 2D latents and draws arrows between them on top of the decision boundary grid saved by visualize_decision_boundary (decision_boundary.npy or decision_boundary_precise.npy in the directory of filename). Returns silently without sample_to_2d_latent.

Parameters:

• filename (str) – Output image path; "_precise" in the name selects the precise grid.

• x_list (list of torch.Tensor) – Factual and counterfactual images, attempts stacked block-wise.

• counterfactuals (list of torch.Tensor) – Factual and counterfactual images, attempts stacked block-wise.

• y_target_start_confidence (list) – Target confidences used to color the arrow ends.

• y_target_end_confidence (list) – Target confidences used to color the arrow ends.

• y_list (list) – Ground-truth labels.

• hint_list (list, optional) – Hints forwarded to sample_to_2d_latent.

• attempts (int, optional) – Number of attempts per factual contained in the lists.

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, idx_to_info=None, **kwargs)

Collage rendering that adds the 2D latent coordinates to the title.

If idx_to_info is not given and the dataset has sample_to_2d_latent, a default is built that prints <factor>: <before> -> <after> per latent dimension (named after config.confounding_factors). Everything else is delegated to ImageDataset.generate_contrastive_collage.

Returns:

(heatmap_list, collage_paths) from the base implementation.

Return type:

tuple

Parameters:

• x_list (list)

• x_counterfactual_list (list)

• y_target_list (list)

• y_source_list (list)

• y_list (list)

• y_target_start_confidence_list (list)

• y_target_end_confidence_list (list)

• base_path (str)

• kwargs (dict)

__init__(config, mode, root_dir=None, data_dir=None, transform=torchvision.transforms.ToTensor, task_config=None, return_dict=False)

Parse the label CSV and optionally load all images into memory.

load_in_memory()

Cache every image (and mask, if config.has_hints) as a numpy array.

Images are stored in in_memory_images under the resolved filename and converted to "L" or "RGB" according to config.input_size[0]; masks go to in_memory_masks.

property output_size

task_config.output_channels when targets are selected, else columns.

enable_hints()

Also return the mask from <root_dir>/masks as hint.

disable_hints()

Stop returning masks.

enable_groups()

Also return has_confounder from the confounding_factors columns.

disable_groups()

Stop returning has_confounder.

enable_idx()

Also return the sample index.

disable_idx()

Stop returning the sample index.

enable_url()

Also return the image key as url.

disable_url()

Stop returning the image key.

enable_string_description()

Also return a text description built from the target attributes.

disable_string_description()

Stop returning the text description.

enable_tokens(tokenizer)

Also return tokens: the description tokenized with tokenizer.

Parameters:

tokenizer (callable) – HuggingFace-style tokenizer with model_max_length; the description is padded/truncated to that length.

disable_tokens()

Drop the tokenizer and restore the previous description setting.

enable_class_restriction(class_idx)

Keep only samples whose first selected target equals class_idx.

The full key list is saved in backup_keys; requires task_config with y_selection.

Parameters:

class_idx (int) – Class value to keep.

disable_class_restriction()

Restore backup_keys (note: class_restrictions_enabled stays True).

set_task_specific_keys()

Subsample keys so the classes follow config.class_ratios.

Counts samples per class of task_config.y_selection[0], finds the largest multiple of class_ratios that fits and keeps the first matching keys in order; the original list is saved in keys_backup.

image_name(name)

The image filename a dataset key refers to (keys may omit the suffix).

open_image(name_img)

Open an image by filename, tolerating .jpg/.png and zero-padded variants.

Serialized counterfactual datasets and the raw datasets on disk disagree about both the extension and the zero padding, so try the plausible spellings before giving up.