peal.explainers.no_generator_counterfactual_explainers.DiCEExplainer

class peal.explainers.no_generator_counterfactual_explainers.DiCEExplainer

Bases: ExplainerInterface

Explainer wrapper for DiCE (Diverse Counterfactual Explanations) https://arxiv.org/pdf/1905.07697

The predictor is a PyTorch tabular classifier; the dataset must expose a pandas df and an attributes list (and optionally task_config with x_selection/y_selection and continuous_features) so that dice_ml.Data can be built from it.

Parameters:

• config (DiCEExplainerConfig) – The explainer config; explainer_config wins if both are given.

• explainer_config (DiCEExplainerConfig) – The explainer config; explainer_config wins if both are given.

• predictor (torch.nn.Module) – Classifier mapping [B, num_features] to logits.

• predictor_datasources (sequence) – Dataloaders or datasets of the predictor; the first entry (or its .dataset) is used to initialize DiCE. datasource wins if both are given. Without one, dataset is None and explain_batch raises.

• datasource (sequence) – Dataloaders or datasets of the predictor; the first entry (or its .dataset) is used to initialize DiCE. datasource wins if both are given. Without one, dataset is None and explain_batch raises.

• **kwargs – Ignored; accepted for factory compatibility.

Variables:

• dice_model (dice, dice_data,) – The dice_ml objects built by setup_dice.

• feat_names (list of str) – Column order of the model input features.

Methods

cluster_explanations	No-op clustering hook; returns the first positional argument.
explain_batch	Generate DiCE counterfactuals for every factual in batch.
setup_dice	Build the dice_ml Data, Model and Dice objects.

Attributes

explainer_config

__init__(config=None, explainer_config=None, predictor=None, predictor_datasources=None, datasource=None, **kwargs)

Store config, predictor and dataset; build DiCE if a dataset is given.

setup_dice()

Build the dice_ml Data, Model and Dice objects.

The outcome column is task_config.y_selection[0] or, failing that, the last dataset attribute; the feature columns are task_config.x_selection or all remaining attributes. Continuous features come from dataset.continuous_features or a heuristic (numeric dtype with more than 10 unique values). The predictor is wrapped in a small sklearn-like object with predict and predict_proba. Prints a warning and does nothing if the dataset has no df/attributes.

explain_batch(batch, **kwargs)

Generate DiCE counterfactuals for every factual in batch.

Each factual is converted to a one-row dataframe (categorical columns snapped to the exact values DiCE saw during setup), explained with num_attempts counterfactuals and the resulting rows are scored with the predictor. Failed or empty searches fall back to the factual itself with confidence 0.0; with merge_clusters != "concatenate" only the highest-confidence counterfactual per factual is kept. The batch dict is updated in place and expanded so that every counterfactual gets its own entry in all *_list keys.

Parameters:

• batch (dict) – Must contain "x_list" (tensor or list of [num_features] tensors) and "y_target_list"; "y_list" is carried along if present.

• **kwargs – base_path and start_idx for dataset.generate_contrastive_collage when tracking_level >= 4.

Returns:

The same dict with x_counterfactual_list, y_target_end_confidence_list, y_source_list, y_target_start_confidence_list, x_attribution_list (|cf - x| unless collages are rendered), collage_path_list and empty z_difference_list/history_list/cluster_list placeholders.

Return type:

dict

Raises:

ValueError – If no dataset was provided at construction.

cluster_explanations(*args, **kwargs)

No-op clustering hook; returns the first positional argument.

Tabular DiCE explanations are not clustered, but CFKD calls this method on every explainer, so it simply passes the input through.