CounterfactualStoryboard

A Python library for generating and visualizing narrative sequences of counterfactual explanations.

CounterfactualStoryboard calculates the Shortest Path, Cheapest Path, and Most Actionable Path to reach a desired outcome, generating plain-language explanations and a beautiful decision storyboard.

Features

• Abstract Engine: Built on dice-ml, but extensible to other counterfactual generation algorithms.
• Narrative Generation: Uses Jinja2 templates to turn numeric feature changes into human-readable sentences.
• Dual Visualization: Outputs interactive HTML/Plotly dashboards or static Matplotlib figures.
• Model Agnostic: Works with scikit-learn, TensorFlow, PyTorch, or any custom model via a simple predict_fn.

Installation

pip install counterfactual_storyboard

Quickstart

import pandas as pd
from sklearn.ensemble import RandomForestClassifier
from counterfactual_storyboard import StoryboardExplainer, FeatureMetadata

# 1. Train your model
df = pd.read_csv("data.csv")
X = df.drop(columns=["target"])
y = df["target"]
model = RandomForestClassifier().fit(X, y)

# 2. Define Feature Metadata (Costs and Mutability)
metadata = FeatureMetadata(
    continuous_features=["age", "balance", "credit_score"],
    actionable_features=["balance"], 
    feature_costs={"age": 100, "balance": 1, "credit_score": 10}
)

# 3. Initialize Explainer
explainer = StoryboardExplainer(
    predict_fn=model.predict_proba,
    training_data=df,
    target_column="target",
    feature_metadata=metadata
)

# 4. Generate Storyboard for an instance
instance = X.iloc[0:1]
storyboard = explainer.generate_storyboard(instance, target_class=1)

# 5. Visualize
storyboard.show()