COLA Documentation¶
Welcome to COLA¶
COLA (COunterfactual explanations with Limited Actions) is a Python framework that refines counterfactual explanations by generating action-limited plans that require significantly fewer feature changes while maintaining similar or equal outcomes.
Why COLA?¶
Traditional counterfactual explainers often produce explanations that require changing many features. COLA refines these explanations to be more actionable:
✅ 30-50% fewer actions compared to raw counterfactuals
✅ Works with different ML models (sklearn, PyTorch)
✅ Built-in Counterfactual explainers (DiCE, DisCount)
✅ Compatible with all generated counterfactuals (in DataFrame format)
✅ Theoretically grounded - based on joint-distribution-informed Shapley values (see our paper)
✅ Easy to use - simple API with sensible defaults
✅ Rich visualizations - heatmaps, charts, highlighted tables
Quick Example¶
from xai_cola import COLA
from xai_cola.ce_sparsifier.data import COLAData
from xai_cola.ce_sparsifier.models import Model
from xai_cola.ce_generator import DiCE
# 1. Prepare data
data = COLAData(factual_data=df, label_column='Risk')
# 2. Wrap model
ml_model = Model(model=your_model, backend="sklearn")
# 3. Generate counterfactuals with any explainer
explainer = DiCE(ml_model=ml_model)
_, cf = explainer.generate_counterfactuals(data=data, factual_class=1)
data.add_counterfactuals(cf, with_target_column=True)
# 4. Refine with COLA
sparsifier = COLA(data=data, ml_model=ml_model)
sparsifier.set_policy(matcher='ot', attributor='pshap')
refined = sparsifier.refine_counterfactuals(limited_actions=5)
# 5. Visualize
sparsifier.heatmap_direction(save_path='./results')
sparsifier.stacked_bar_chart(save_path='./results')
Installation¶
Install via pip:
pip install xai-cola
See Installation for detailed instructions.
Documentation Structure¶
This documentation is organized into several sections:
- Getting Started 📚
New to COLA? Start here!
Installation - Install COLA
Quick Start - 5-minute quick start
Tutorial 1: Basic COLA Workflow - Complete tutorial
- User Guide 📖
Learn how to use COLA’s features.
Data Interface - Managing data
Model Interface - Wrapping ML models
Counterfactual Explainers - Generating counterfactuals
Matching Policies - Refinement strategies
Visualization - Visualizing results
- API Reference 🔍
Detailed API documentation.
COLA API - COLA main class
Data API - Data interface
Models API - Model interface
Counterfactual Generators - CF generators
api/policies - Matching & attribution
Visualization API - Visualization tools
- Additional Resources 💡
FAQs, contributing, and more.
Frequently Asked Questions - Frequently asked questions
Contributing - Contribution guidelines
Changelog - Version history
Getting Started
- Installation
- Quick Start
- Tutorial 1: Basic COLA Workflow
- Learning Objectives
- Prerequisites
- The Problem
- Step 1: Prepare Your Data
- Step 2: Load Your ML Model
- Step 3: Generate Initial Counterfactuals
- Step 4: Initialize COLA and Set Policy
- Step 5: Refine Counterfactuals
- Step 6: Visualize Results
- Step 7: Interpret the Results
- Complete Example
- Exercises
- Solutions
- Next Steps
- Summary
API Reference
Additional Resources
Key Features¶
Flexible Data Interface¶
Works with both pandas DataFrames and NumPy arrays:
# With DataFrame
data = COLAData(factual_data=df, label_column='target')
# With NumPy
data = COLAData(
factual_data=X,
label_column='target',
column_names=['feat1', 'feat2', 'target']
)
Multi-Framework Support¶
Compatible with major ML frameworks:
# Scikit-learn
model = Model(sklearn_model, backend="sklearn")
# PyTorch
model = Model(pytorch_model, backend="pytorch")
# TensorFlow
model = Model(keras_model, backend="TF2")
Multiple Matching Strategies¶
Choose the right strategy for your needs:
# Optimal Transport - best quality
sparsifier.set_policy(matcher="ot", attributor="pshap")
# Exact Class Transition - fast
sparsifier.set_policy(matcher="ect", attributor="pshap")
# Nearest Neighbor - simplest
sparsifier.set_policy(matcher="nn", attributor="pshap")
Rich Visualizations¶
Multiple visualization options:
# Direction heatmap
sparsifier.heatmap_direction(save_path='./results')
# Stacked bar chart
sparsifier.stacked_bar_chart(save_path='./results')
# Highlighted DataFrames
_, ce_style, ace_style = sparsifier.highlight_changes_final()
display(ce_style)
Use Cases¶
Credit Approval¶
Scenario: A loan applicant is rejected. What’s the minimal change needed?
Without COLA: Change 8 features (income, duration, job, age, housing, …)
With COLA: Change 3 features (income, duration, job)
Medical Diagnosis¶
Scenario: Patient classified as high-risk. What tests should change?
Without COLA: Modify 12 biomarkers
With COLA: Focus on 4 key biomarkers
Hiring Decisions¶
Scenario: Candidate not selected. What qualifications matter most?
Without COLA: Improve 10 different areas
With COLA: Focus on 3 specific skills
Research & Citation¶
If you use COLA in your research, please cite:
@article{you2024refining,
title={Refining Counterfactual Explanations With Joint-Distribution-Informed
Shapley Towards Actionable Minimality},
author={You, Lei and Bian, Yijun and Cao, Lele},
journal={arXiv preprint arXiv:2410.05419},
year={2024}
}
Paper: arXiv:2410.05419
Community & Support¶
Contributing¶
We welcome contributions! See Contributing for guidelines.
License¶
COLA is licensed under the MIT License. See the LICENSE file for details.