xai-cola: A Python library for sparsifying counterfactual explanations

AI summary

Overview

• Research area: Explainable AI (XAI), specifically post-hoc counterfactual explanation (CE) for tabular machine learning models, delivered as open-source software.
• Technical level: Intermediate. Readers need basic familiarity with counterfactual explanations, scikit-learn/PyTorch workflows, and Python packaging, but the paper is primarily a library description rather than a theoretical treatment.
• Scope (one sentence): The paper introduces xai-cola, an MIT-licensed Python library installable from PyPI that provides an end-to-end pipeline for sparsifying counterfactuals produced by arbitrary CE generators, reducing superfluous feature changes while preserving validity.

What This Paper Is About

Counterfactual explanations show how small changes to input features would flip a model's prediction, but the explanations produced by most CE generators are often highly redundant, modifying many features that the user does not actually need to change. xai-cola addresses this by providing a general, model-agnostic post-processing pipeline that sits on top of existing CE generators and removes superfluous feature changes without invalidating the counterfactual. The paper describes the library's architecture, API, and an empirical evaluation of how much sparsification it achieves across four established CE generators.

Key Contributions

1. A modular open-source library for CE sparsification. xai-cola is presented as the first Python library for sparsifying counterfactual explanations, released under the MIT license and installable from PyPI, with documentation at https://cola-docs.readthedocs.io/en/latest/ and source code at https://github.com/understanding-ml/COLA.
2. A unified model and data interface. The Model class wraps compatible scikit-learn and PyTorch models behind one API exposing prediction, class-probability, and gradient-based calls; the COLAData class centralizes factual and counterfactual data along with feature names, feature types (numerical vs. categorical), and the label column, accepting either a pandas DataFrame or a NumPy array with column names.
3. A configurable sparsification layer plus built-in generators. The COLA class implements the core sparsification algorithm (COLA, from You et al., 2024) with policies set via set_policy and invoked through get_refined_counterfactuals, which takes an argument controlling the maximum number of features allowed to change. Two wrapped CE generators are bundled in the ce_generator subpackage: an instance-level DiCE wrapper and a distribution-level generator adapted from DisCount.
4. Visualization and analysis utilities. The library provides tailored plotting routines in ce_sparsifier.visualization so users can inspect sparsity patterns and compare different sparsification policies.

Main Findings

• Sparser counterfactuals across all evaluated generators: xai-cola consistently yielded sparser counterfactuals for every CE generator tested in the paper's setting.
• Reduction of up to 50%: The abstract and experiments report that the library reduces the number of modified features by up to 50% in the best cases (described as "in our setting").
• Wachter on German Credit / COMPAS (PyTorch): 10.4% and 13.8% respectively. No scikit-learn values are reported because Wachter requires gradient-based optimization, which is not applicable to scikit-learn.
• DiCE on German Credit: 24.9% with scikit-learn and 12.0% with PyTorch; DiCE on COMPAS: 11.2% with scikit-learn and 8.2% with PyTorch.
• GLOBE-CE on German Credit: 9.2% with scikit-learn and 8.4% with PyTorch; GLOBE-CE on COMPAS: 14.4% with scikit-learn and 10.0% with PyTorch.
• DisCount on German Credit / COMPAS (PyTorch): 30.3% and 45.3% respectively. As with Wachter, scikit-learn values are not applicable because DisCount requires gradient-based optimization.
• No directly comparable prior benchmarks exist: The authors state that to the best of their knowledge this is the first Python library to sparsify CEs, so the experiments focus on the degree of sparsification rather than comparison against a prior sparsification baseline.
• Attribution-level design choice: Shapley attributions are computed and reported at the original feature level rather than on one-hot-expanded dimensions, so feature importance corresponds to user-facing variables and actionable edits, avoiding attribution fragmentation caused by encoding. This differs from the original COLA algorithm's experiments.
• Base models were not tuned: The paper states that standard configurations were used without extensive hyperparameter tuning, since the goal is to demonstrate relative sparsity improvements rather than maximize base model accuracy. The "sklearn" entries correspond to logistic regression models implemented with scikit-learn, and the "pytorch" entries to feed-forward neural networks.

Methodology in Plain English

The authors build a library rather than a new algorithm. Users supply three things: raw tabular data as a pandas DataFrame, a preprocessing object (for example a scikit-learn pipeline that performs standardization and encoding), and a trained predictive model defined in the preprocessed feature space. The library wraps these into a Model instance and a COLAData instance.

Counterfactuals are then produced either by an external generator (anything that returns a DataFrame can be passed into COLAData, which the authors present as evidence of extensibility) or by one of the two built-in generators, DiCE or DisCount, which are placed in the ce_generator subpackage and share the same Model and COLAData interfaces. Generated counterfactuals are inserted back into the COLAData object.

The COLA class handles the sparsification stage. A policy is selected by name from a finite set of predefined matcher and attributor methods via set_policy; sparsification is then invoked with get_refined_counterfactuals, which takes an argument bounding the maximum number of features allowed to change in all counterfactuals. The method runs a sequence of operations — matching factual and counterfactual instances, computing feature attributions, and composing refined counterfactuals under the chosen policy — and returns a DataFrame of sparsified counterfactuals. Convenience methods connect the result to the visualization utilities.

For evaluation, the authors applied the library to counterfactuals from four generators (Wachter, DiCE, GLOBE-CE, DisCount) on two datasets (German Credit and COMPAS), using logistic regression (scikit-learn) and feed-forward neural networks (PyTorch) as the underlying predictive models. The paper does not report dataset sizes or other dataset statistics.

Why This Matters

Impact on research. Most CE research focuses on generating counterfactuals under various constraints and goals, and the paper notes that hundreds of generation algorithms have been proposed (citing Guidotti, 2024, and Verma et al., 2024). Sparsification has been treated as an algorithmic detail rather than reusable infrastructure. By packaging it as a model-agnostic library that plugs into arbitrary generators, xai-cola lets sparsity be studied and applied as a separate, composable step, and it provides a common interface for comparing sparsification policies.

Real-world applications (grounded in the tabular, socially sensitive, safety-critical settings the paper describes and the benchmarks it uses):

• Credit and lending decisions, represented in the evaluation by the German Credit dataset, where an applicant needs a concrete list of changes rather than a long, unactionable one.
• Criminal justice risk assessment, represented by the COMPAS dataset, where explanations must be concise enough to be reviewed and contested.
• Any tabular decision system where an explanation is only useful if the recommended edits are actually feasible under domain constraints, such as insurance, benefits eligibility, or clinical scoring tools.
• Regulatory and compliance workflows where concise, valid counterfactuals support trust, debugging, and the right to an explanation.

Industry relevance. Because xai-cola installs from PyPI under the MIT license, requires only a DataFrame, a preprocessing object, and a trained scikit-learn or PyTorch model, and accepts externally produced counterfactuals, it can be inserted into existing tabular ML pipelines with minimal refactoring. Its built-in DiCE and DisCount generators let teams generate and sparsify counterfactuals inside a single pipeline, and the visualization routines give a practical way to check sparsity and validity before shipping explanations to users.

Future Directions

• More CE generators. The authors state they plan to extend the library with additional CE generators, broadening coverage beyond the currently wrapped DiCE and DisCount and the externally importable generators.
• More sparsification strategies. The paper lists additional sparsification strategies as planned future work, expanding the finite set of predefined matcher and attributor methods currently selectable by name.
• Toward a one-stop toolkit. The stated goal is to make xai-cola a single toolkit for generating, sparsifying, and analyzing counterfactuals, which raises the open question of how far the pipeline can be extended before the model-agnostic interface becomes limiting.
• Benchmarking a first-of-its-kind library. Because the authors note there are no directly comparable prior benchmarks, an open question is how sparsification quality should be compared across policies and generators going forward, especially given the paper's decision to compute Shapley attributions at the original feature level rather than on one-hot-expanded dimensions.

Target Audience

This paper is most useful to practitioners and researchers who already work with counterfactual explanations and want a ready-made way to make them sparser, and to ML engineers building explanation features for tabular models in scikit-learn or PyTorch. It is also relevant to XAI researchers who need a baseline or infrastructure for studying sparsity, since the library exposes swappable policies and generators, and to contributors, whom the authors explicitly invite to help extend the pipeline. Readers looking for a new sparsification theory or a deep algorithmic derivation will not find one here; the contribution is the software and its evaluation.

Authors’ abstract

Counterfactual explanation (CE) is an important domain within post-hoc explainability. However, the explanations generated by most CE generators are often highly redundant. This work introduces an open-source Python library xai-cola, which provides an end-to-end pipeline for sparsifying CEs produced by arbitrary generators, reducing superfluous feature changes while preserving their validity. It offers a documented API that takes as input raw tabular data in pandas DataFrame form, a preprocessing object (for standardization and encoding), and a trained scikit-learn or PyTorch model. On this basis, users can either employ the built-in or externally imported CE generators. The library also implements several sparsification policies and includes visualization routines for analysing and comparing sparsified counterfactuals. xai-cola is released under the MIT license and can be installed from PyPI. Empirical experiments indicate that xai-cola produces sparser counterfactuals across several CE generators, reducing the number of modified features by up to 50% in our setting. The source code is available at https://github.com/understanding-ml/COLA.