Skip to main content

ACFX — Actionable Counterfactual eXplainer

PyPI version Python versions License Documentation Status GitHub Stars

ACFX (Actionable Counterfactual eXplainer) is a model-agnostic Explainable AI (XAI) framework for generating actionable counterfactual explanations for machine learning models.

It answers the question:

What minimal and feasible changes to the input would lead to a desired prediction outcome?

Key Features

  • Model-agnostic counterfactual explanations
  • Actionability and feasibility constraints
  • Support for causal structures and expert knowledge
  • Built-in benchmarking framework
  • Python API and graphical user interface (GUI)

Installation

From PyPI

conda create --name acfx_env python=3.11
conda activate acfx_env
conda install pip
pip install acfx

From source

git clone https://github.com/sbobek/acfx
cd acfx/src
pip install .

Note: The requirements.txt file includes additional packages that are not required for standard use. It is provided for development purposes and to support reproducibility of the complete development environment. Direct runtime dependencies are specified in pyproject.toml.

Quick Start

from acfx import AcfxEBM
from interpret.glassbox import ExplainableBoostingClassifier
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
import numpy as np

# Initialize model and explainer
model = ExplainableBoostingClassifier()
explainer = AcfxEBM(model)

# Load sample data
data = load_iris(as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(data.data, data.target, test_size=0.2, random_state=42)

# Define feature bounds
pbounds = {col: (X_train[col].min(), X_train[col].max()) for col in X_train.columns}

# Example adjacency matrix and causal order
adjacency_matrix = np.array([
    [0.0, 0.0, 0.0, 0.0],
    [0.8, 0.0, 0.0, 0.0],
    [0.0, 0.6, 0.0, 0.0],
    [0.5, 0.0, 0.7, 0.0]
])
causal_order = [0, 1, 2, 3]

# Fit explainer
explainer.fit(
    X=X_train,
    adjacency_matrix=adjacency_matrix,
    causal_order=causal_order,
    pbounds=pbounds,
    y=y_train,
    features_order=X_train.columns.tolist()
)

# Generate counterfactual
query_instance = X_test.iloc[0].values
original_class = model.predict([query_instance])[0]
cf = explainer.counterfactual(desired_class=original_class, query_instance=query_instance)
print(cf)

⚠️ The adjacency matrix above is a simple example. In practice, it can be provided by expert knowledge or learned using tools like DirectLiNGAM.

Usage Tutorials

Learn more and explore advanced examples:

Testing

The library and the Streamlit GUI are covered by an automated pytest suite with code coverage measurement:

git clone https://github.com/sbobek/acfx
cd acfx/src
pip install -e ".[test,streamlit-app]"
pytest --cov

See TESTING.md for details (fast mode, HTML coverage report, what is excluded from coverage and why).

Benchmarking

Install dependencies

pip install acfx[benchmark]

Run benchmark

git clone https://github.com/sbobek/acfx
cd acfx/src
python -m acfx.benchmark.main

⚠️ Always run as a module from acfx/src using python -m. Running directly or from another folder may cause import or path errors.

Citation

TBD

Metadata

Release files for acfx 0.3.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for acfx 0.3.8
File Size Uploaded Provenance Actions
acfx-0.3.8.tar.gz 23.7 kB Without provenance Details for acfx-0.3.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for acfx 0.3.8
File Interpreter ABI Platform Actions
acfx-0.3.8-py3-none-any.whl Python 3 none any Details for acfx-0.3.8-py3-none-any.whl

Total release size: 50.8 kB

Release files / acfx-0.3.8.tar.gz

Download URL acfx-0.3.8.tar.gz
Size 23.7 kB
Tags Source
SHA-256 checksum
How to use checksums
428457db22644e368423a1ac8e4e583ea8262c21613995bd62a49bb5f60b2e16
BLAKE2b-256 checksum
How to use checksums
20bc833ebaa10a63c6f41727bf40612cdfb1d0bd89fe89174d90f22752820e24
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / acfx-0.3.8-py3-none-any.whl

Download URL acfx-0.3.8-py3-none-any.whl
Size 27.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e5b568714e33f261d131cde75c959e9af3d3b19f47dc37f6fd9b6fec2490a789
BLAKE2b-256 checksum
How to use checksums
023d355a647166ad4f98a020dbd6031f8bc983be688f0e29353c01cc17d35f2f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for acfx 0.3.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page