ACFX — Actionable Counterfactual eXplainer
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:
- Documentation: ACFX Docs
- Python API (Colab Notebooks): Interactive Examples
- Graphical User Interface (GUI): ACFX GUI
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/srcusingpython -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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.