DiCEx: Directional Counterfactual Explanations

DiCEx tells you in which direction to change the features of a record to improve the prediction of a machine learning model, choosing the direction that remains reliable when the change is carried out imprecisely.

Classical counterfactual explanations prescribe a precise endpoint ("raise your income to exactly 52,300"). In practice, people execute recommendations with an uncertain magnitude, and an endpoint that sits next to a decision boundary can easily backfire. DiCEx instead prescribes a direction of change and evaluates it by the improvement it delivers when the length of the move is random, using a risk-averse criterion (the lower-tail CVaR) that rewards reliable gains rather than best-case ones. When no direction is reliably better than doing nothing, DiCEx recommends not acting.

DiCEx works with any fitted model that exposes predict (regression) or predict_proba (classification): scikit-learn estimators, gradient-boosted trees, neural networks, or your own black box. The formulation and the optimization algorithm (vMF-VNS, a derivative-free search on the sphere of directions with a Rust core) are described in the preprint.

Contents

• Installation
• Quick start
• Inputs and outputs
• Reproducing the paper
• Development
• Citation
• License

Installation

DiCEx requires Python 3.12 or later. Prebuilt wheels are provided for Linux (x86_64, aarch64), macOS (Apple silicon, Intel), and Windows (x86_64):

pip install dicex

or, with uv:

uv add dicex

To install from source (this compiles the Rust extension and needs a Rust toolchain):

pip install git+https://github.com/javiermartinch/dicex.git

The only runtime dependencies are NumPy and SciPy.

Quick start

A company's loan application has been rejected. In which direction should it improve its figures so that approval becomes likely, even if the improvements turn out larger or smaller than planned?

import numpy as np
from sklearn.neural_network import MLPClassifier
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler

from dicex import Dicex, GaussianPerturbation

# Synthetic loan applications from companies. The three features are levers the company
# can act on, and they are all continuous, signed, and measured in percentage points.
features = ["operating margin (%)", "sales growth (%)", "working capital (% of sales)"]
rng = np.random.default_rng(0)
n = 3000
x_train = np.column_stack([rng.normal(5.0, 8.0, n), rng.normal(3.0, 10.0, n), rng.normal(10.0, 8.0, n)])
score = x_train @ np.array([0.10, 0.05, 0.07]) + rng.normal(0, 0.5, n)
y_train = (score > 1.2).astype(int)  # 1 = loan approved
model = make_pipeline(StandardScaler(), MLPClassifier(hidden_layer_sizes=(32, 32), max_iter=2000, random_state=0))
model.fit(x_train, y_train)

company = np.array([2.0, 0.0, 8.0])
print(f"P(approved) today: {model.predict_proba(company[None])[0, 1]:.2f}")

explainer = Dicex(
    model,
    task="classification",
    target_class=1,  # raise the probability of approval
    # The company will move along the recommended direction, but by an uncertain
    # amount: about 0.5 +/- 0.15 standard deviations of each feature.
    perturbation=GaussianPerturbation(mu=0.5, sigma=0.15),
    alpha=0.1,  # optimize the worst 10% of outcomes
    seed=42,
    verbose="none",
).fit(x_train)

result = explainer.explain(company)
# Recommended direction of change, in the units of each feature.
for name, c in zip(features, result.direction, strict=True):
    print(f"{name:>28}: {c:+.2f}")
print(f"Gain in P(approved) in the worst 10% of executions: {result.robust_value:+.2f}")

P(approved) today: 0.15
        operating margin (%): +0.60
            sales growth (%): +0.57
working capital (% of sales): +0.56
Gain in P(approved) in the worst 10% of executions: +0.30

The direction gives the proportions of the change in the units of each feature, here percentage points: DiCEx recommends improving the three together, in similar measure, rather than betting on a single one. Moving along that direction with a random step raises the probability of approval by at least 0.30 in 90% of the executions.

Inputs and outputs

What you provide:

What you get: an ExplanationResult with

The components of direction are proportions in the units of each feature, so when the features have different units, those measured on larger scales get larger components; metadata["direction_scaled"] gives the same direction in standard deviations of each feature, the space in which the optimizer works.

The preprint describes the formulation and the algorithm, and the API reference documents every option.

Reproducing the paper

The folder experiments/ contains the scripts, configurations, raw results, and output logs behind every figure and table of the paper and its electronic companion. It has its own locked environment; the dicex package installed from PyPI is only the library in src/.

cd experiments
uv sync              # see experiments/README.md for options without Rust or uv
./run_all.sh example figures

This regenerates the figures and tables from the included results in a few minutes; the collected figures are written to experiments/paper_figures/ under the file names of the manuscript. experiments/README.md describes the full pipeline (runtimes, memory, random seeds) and maps each figure and table of the paper to the script that produces it.

Development

The project uses uv and a pinned Rust toolchain (rust-toolchain.toml):

git clone https://github.com/javiermartinch/dicex.git
cd dicex
uv sync --dev          # builds the Rust extension
uv run pytest          # tests
uv run pre-commit run --all-files   # ruff, pyright (strict), cargo fmt and clippy

See CONTRIBUTING.md for the contribution workflow.

Citation

If you use DiCEx in your work, please cite:

E. Carrizosa, J. Martín-Chávez, and C. Molero-Río. Directional Counterfactual Explanations. Preprint, 2026. https://www.researchgate.net/publication/415152503_Directional_Counterfactual_Explanations

@misc{carrizosa2026directional,
  title        = {Directional Counterfactual Explanations},
  author       = {Carrizosa, Emilio and Mart{\'\i}n-Ch{\'a}vez, Javier and Molero-R{\'\i}o, Cristina},
  howpublished = {Preprint},
  year         = {2026},
  url          = {https://www.researchgate.net/publication/415152503_Directional_Counterfactual_Explanations}
}

GitHub also shows this citation from CITATION.cff.

License

DiCEx is released under the MIT License.