xai-cola: A Python library for sparsifying counterfactual explanations

1. Problem Statement

Counterfactual Explanations (CEs) are a prominent post-hoc explainability method that demonstrates how minimal changes to input features can alter a model's prediction. However, a significant limitation of existing CE generators is redundancy.

• The Issue: Many generated CEs modify a large number of features simultaneously.
• The Consequence: These dense explanations are often difficult for humans to act upon, may violate domain constraints (making them infeasible), and reduce the interpretability of the explanation.
• The Gap: While many algorithms exist to generate CEs, there is a lack of standardized, open-source tools to post-process these explanations to reduce feature changes (sparsify them) while maintaining validity.

2. Methodology: The xai-cola Library

The authors introduce xai-cola, an open-source Python library designed to provide an end-to-end pipeline for sparsifying CEs produced by arbitrary generators. The library is built on the COLA algorithm (You et al., 2024) but extends it into a modular, user-friendly framework.

Core Architecture

The library is model-agnostic and integrates seamlessly with existing pipelines (e.g., scikit-learn, PyTorch). Its architecture consists of four main components:

1. Data Container (COLAData):

   • A structured container for factual and counterfactual instances.
   • Accepts pandas DataFrames or NumPy arrays.
   • Centralizes metadata handling, including feature names, types (numerical vs. categorical), and label columns.

2. Model Interface (Model):

   • Wraps diverse prediction backends (scikit-learn and PyTorch) under a unified API.
   • Automatically detects model types and exposes common operations: prediction, class-probability queries, and gradient-based calls (where applicable).
   • Ensures compatibility between the sparsification logic and various underlying models.

3. CE Generators (ce_generator):

   • Extensibility: Supports external generators as long as they output a DataFrame compatible with COLAData.
   • Built-in Generators: Includes wrappers for:
     • DiCE: An instance-level generator (Mothilal et al., 2020).
     • DisCount: A distribution-level generator adapted from You et al. (2025).
   • This allows users to generate CEs and immediately sparsify them within a single workflow.

4. Sparsification and Visualization (ce_sparsifier):

   • The COLA Class: Orchestrates the sparsification process.
   • Workflow:
     1. Input: Takes a Model instance and a COLAData instance containing candidate CEs.
     2. Policy Configuration: Users select a sparsification policy via set_policy, choosing from predefined matchers (to align factual and counterfactual instances) and attributors (to compute feature importance).
     3. Execution: The get_refined_counterfactuals method performs matching, computes feature attributions (specifically Shapley values at the original feature level to avoid fragmentation from one-hot encoding), and reconstructs the CEs based on the chosen policy.
     4. Constraint: Users can specify the maximum number of features allowed to change.
   • Visualization: Includes utilities to inspect sparsity patterns and compare different policies.

3. Key Contributions

• First Dedicated Library: xai-cola is the first open-source Python library specifically designed to sparsify counterfactual explanations.
• Unified Pipeline: It bridges the gap between CE generation and sparsification, supporting both instance-level and distribution-level explanations.
• Modular Design: The library decouples the sparsification logic from the generation logic, allowing it to be applied to any CE generator (built-in or external).
• Actionable Explanations: By focusing on reducing superfluous feature changes, the library directly addresses the "actionability" problem in XAI.
• Open Source: Released under the MIT license and available on PyPI, with source code hosted on GitHub.

4. Experimental Results

The authors evaluated xai-cola on the German Credit and COMPAS datasets using four distinct CE generators: Wachter, DiCE, GLOBE-CE, and DisCount.

• Performance Metrics: The primary metric was the reduction in the number of modified features (sparsity).
• Key Findings:
  • xai-cola consistently produced sparser counterfactuals across all evaluated generators.
  • Reduction Magnitude: The library reduced the number of modified features by up to 50% in the best-case scenarios.
  • Specific Results (PyTorch Models):
    • DiCE: Reduced feature changes by 12.0% (German Credit) and 8.2% (COMPAS).
    • DisCount: Achieved the highest reduction, lowering feature changes by 30.3% (German Credit) and 45.3% (COMPAS).
    • Wachter: Showed reductions of 10.4% and 13.8% respectively.
• Note on Methodology: The experiments computed Shapley attributions at the original feature level (rather than on one-hot expanded dimensions) to ensure feature importance corresponds to actionable user variables.

5. Significance

• Enhanced Usability: By minimizing the number of changes required to flip a prediction, xai-cola makes counterfactual explanations more practical for end-users (e.g., loan applicants or medical patients) to understand and act upon.
• Standardization: It provides a standardized interface for sparsification, a task previously handled by ad-hoc scripts or not addressed at all.
• Future-Proofing: The library's modular design allows for the easy integration of new CE generators and sparsification strategies, positioning it as a potential "one-stop toolkit" for the XAI community.
• Regulatory Compliance: In safety-critical and sensitive domains, providing concise, non-redundant explanations is often a regulatory requirement; xai-cola facilitates compliance with these standards.