peal.teachers.preclustered_teacher.PreclusteredTeacher

class peal.teachers.preclustered_teacher.PreclusteredTeacher[source]

Bases: TeacherInterface

Feedback source that labels a counterfactual by its cluster membership.

A counterfactual is "true" when its cluster id is in correct_clusters and "false" otherwise; the usual sanity gates (student already wrong, not flipped, out of distribution) are applied first.

Parameters:

  • dataset (PealDataset) – Dataset used for the outlier score (calculate_outlier_score) and, at high tracking levels, for rendering contrastive collages.

  • correct_clusters (collection of int) – Cluster ids whose counterfactuals count as valid explanations.

  • tracking_level (int, optional) – Verbosity; at 5 or above a collage of every feedback batch is written.

  • counterfactual_type (str, optional) – "1sided" (default) rejects counterfactuals of samples the student misclassified in the first place; any other value skips that gate.

Methods

get_feedback

Return one feedback string per counterfactual.
__init__(dataset, correct_clusters, tracking_level=0, counterfactual_type='1sided')[source]

Store the dataset, the correct cluster ids and the tracking options.

get_feedback(x_counterfactual_list, y_source_list, x_list, y_list, y_target_end_confidence_list, cluster_list, base_dir=None, y_target_list=None, mode='train', **kwargs)[source]

Return one feedback string per counterfactual.

Parameters:

  • x_counterfactual_list (sequence of torch.Tensor) – Counterfactual inputs, each without batch dimension.

  • y_source_list (sequence of int) – Class the predictor assigned to the original sample.

  • x_list (sequence of torch.Tensor) – Original samples; only forwarded to the collage writer.

  • y_list (sequence of int) – Ground-truth labels of the original samples.

  • y_target_end_confidence_list (sequence of float) – Predictor confidence in the target class after the edit.

  • cluster_list (sequence of int) – Cluster id of every counterfactual, as stamped by CounterfactualExplainer.cluster_explanations.

  • base_dir (str, optional) – Directory the collages are written to when tracking_level >= 5.

  • y_target_list (sequence of int, optional) – Target classes, forwarded to the collage writer.

  • mode (str, optional) – "train" or "validation"; collages are written for both.

  • **kwargs – Passed through to dataset.generate_contrastive_collage.

Returns:

Per counterfactual, in order of precedence: "student originally wrong!" (1sided and y != y_source), "student not swapped!" (target confidence below 0.5), "ood_<score>" (relative outlier score above 4.0), else "true" or "false" by cluster membership.

Return type:

list of str

Notes

The teacher labels handed to the collage writer are -1 placeholders; this teacher never relabels the images themselves.