pacex 0.1.2

PACE: Proposal Assembly for Counterfactual Explanations

PACE

Proposal Assembly for Counterfactual Explanations — a counterfactual explainer for tabular classifiers.

PACE generates counterfactual explanations — the smallest change to a data point that flips the model's prediction. It works with any binary classifier that exposes a predict_proba method, handles mixed numeric/categorical features natively, and supports actionability constraints.

Install

pip install pacex

Quick start

from sklearn.datasets import fetch_openml
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split
from pace import PACE, FeatureInfo
from pace.preprocessing import make_preprocessor, feature_info_from_preprocessor

# 1. Load the German credit dataset (1 000 rows, mixed features)
data = fetch_openml("credit-g", version=1, as_frame=True)
df = data.frame
y = (df["class"] == "good").astype(int)

num_cols = ["age", "duration", "credit_amount"]
cat_cols = ["checking_status", "credit_history", "purpose", "personal_status"]

X_train_df, X_test_df, y_train, y_test = train_test_split(
    df[num_cols + cat_cols], y, test_size=0.2, random_state=42
)

# 2. Preprocess
pre = make_preprocessor(num_cols, cat_cols)
X_tr_sc = pre.fit_transform(X_train_df)   # numpy array, model space
X_te_sc = pre.transform(X_test_df)
feature_info = feature_info_from_preprocessor(pre, num_cols, cat_cols)

# 3. Train your model (any sklearn-compatible classifier)
model = RandomForestClassifier(random_state=42).fit(X_tr_sc, y_train)

# 4. Fit PACE once per (dataset, model) pair
explainer = PACE(
    X_train=X_tr_sc,
    predict_proba=model.predict_proba,
    feature_info=feature_info,
    pre=pre,
    num_cols=num_cols,
    cat_cols=cat_cols,
)

# 5. Explain a single instance — with constraints and immutability
x_f = X_te_sc[0]
x_cf, report = explainer.explain(
    x_f,
    y_desired=1,                           # flip to "good credit"
    n_candidates=1200,                     # more candidates → better quality
    max_changed_features=2,               # change at most 2 features
    immutable=["age", "personal_status"], # these must not change
    constraints={
        "duration":      (None, 36),       # loan term ≤ 36 months
        "credit_amount": (0,    None),     # amount must stay non-negative
    },
)

print(report)
# {'status': 'ok', 'l0': 2, 'l2': 0.74, 'p_cf': 0.68, ...}

# 6. Decode back to human-readable values
print(explainer.decode(x_cf))
# {'age': 34.0, 'duration': 24.0, 'credit_amount': 2500.0, ...}

Constraints are specified in the original feature space (before scaling).

Purely numeric data

If your data has no categorical columns, skip feature_info:

explainer = PACE(X_train=X_tr_sc, predict_proba=model.predict_proba)
x_cf, report = explainer.explain(x_f, y_desired=1)

License

Apache 2.0