peal.explainers.counterfactual_explainer.flatten_explanations

peal.explainers.counterfactual_explainer.flatten_explanations(explanations, reference_key='x_counterfactual_list', batch_size=None)

Give every entry of an explanations dict one row per counterfactual.

With num_attempts > 1 the counterfactual-derived entries hold one row per (factual, attempt) while the per-factual entries hold one row per factual. Every consumer indexes by counterfactual – cluster_explanations(), Model2ModelTeacher.get_feedback and the desiderata in calculate_explainer_stats – so a ragged dict makes them read the wrong factual or run off the end of the list.

The expansion is per batch, not global. Counterfactuals are laid out as one attempt-major block per batch: for a batch of batch_size factuals and r attempts the order is all factuals of the batch for attempt 0, then the same factuals for attempt 1, and only then the next batch. So a per-factual entry is expanded by repeating each batch_size-sized chunk r times, which leaves the two copies of a factual batch_size rows apart.

That layout was read off a published run rather than assumed: in a finished cache of 408 counterfactuals over 204 factuals, each factual appears exactly twice and the two copies are 6 indices apart, 6 being the configured batch size. Global tiling would have put them 204 apart and pairs every counterfactual with the wrong factual outside the first batch.

batch_size may be omitted when the dict covers a single batch, which is the case inside explain_batch(); the whole entry is then one chunk and the result is the same.