oceanpy 2.0.7

A simple Python package Optimal Counterfactual Explanations in Tree Ensembles

Optimal Counterfactual Explanations in Tree Ensembles

ocean is a full package dedicated to counterfactual explanations for tree ensembles.
It builds on the paper Optimal Counterfactual Explanations in Tree Ensemble by Axel Parmentier and Thibaut Vidal in the Proceedings of the thirty-eighth International Conference on Machine Learning, 2021, in press. The article is available here.
Beyond the original MIP approach, ocean also includes constraint programming (CP) and weighted MaxSAT backends for exact counterfactual search on the same parsed tree ensembles.

Installation

You can install the package with the following command:

pip install oceanpy

Note : The MIP method requires the gurobi solver access. You can request for a free academic license here. Once you have installed gurobi, you can install the package with the command above. However, you can also use the CP method without gurobi.

Usage

The package provides multiple classes and functions to wrap the tree ensemble models from the scikit-learn library. A minimal example is provided below:

from sklearn.ensemble import RandomForestClassifier

from ocean import (
    ConstraintProgrammingExplainer,
    MaxSATExplainer,
    MixedIntegerProgramExplainer,
)
from ocean.datasets import load_adult

# Load the adult dataset
(data, target), mapper = load_adult()

# Select an instance to explain from the dataset
x = data.iloc[0].to_frame().T

# Train a random forest classifier
rf = RandomForestClassifier(n_estimators=10, max_depth=3, random_state=42)
rf.fit(data, target)

# Predict the class of the random instance
y = int(rf.predict(x).item())
x = x.to_numpy().flatten()

# Explain the prediction using the MIP backend
mip_model = MixedIntegerProgramExplainer(rf, mapper=mapper)
mip_explanation = mip_model.explain(x, y=1 - y, norm=1)

# Explain the prediction using the CP backend
cp_model = ConstraintProgrammingExplainer(rf, mapper=mapper)
cp_explanation = cp_model.explain(x, y=1 - y, norm=1)

# Explain the prediction using the MaxSAT backend
maxsat_model = MaxSATExplainer(rf, mapper=mapper)
maxsat_explanation = maxsat_model.explain(x, y=1 - y, norm=1)

# Show the explanations and their objective values
print("MIP objective value:", mip_model.get_objective_value())
print("MIP", mip_explanation, "\n")

print("CP objective value:", cp_model.get_objective_value())
print("CP", cp_explanation, "\n")

print("MaxSAT objective value:", maxsat_model.get_objective_value())
print("MaxSAT", maxsat_explanation, "\n")

Expected output:

MIP objective value: 3.0
MIP Explanation:
Age              : 39.0
CapitalGain      : 2174.0
CapitalLoss      : 0
EducationNumber  : 13.0
HoursPerWeek     : 40.0
MaritalStatus    : 3
NativeCountry    : 0
Occupation       : 10
Relationship     : 0
Sex              : 0
WorkClass        : 6 

CP objective value: 3.0
CP Explanation:
Age              : 39.0
CapitalGain      : 2174.0
CapitalLoss      : 0.0
EducationNumber  : 13.0
HoursPerWeek     : 40.0
MaritalStatus    : 3
NativeCountry    : 0
Occupation       : 1
Relationship     : 0
Sex              : 0
WorkClass        : 4

MaxSAT objective value: 3.0
MaxSAT Explanation:
Age              : 39.0
CapitalGain      : 2174.0
CapitalLoss      : 0.0
EducationNumber  : 13.0
HoursPerWeek     : 40.0
MaritalStatus    : 3
NativeCountry    : 0
Occupation       : 1
Relationship     : 0
Sex              : 0
WorkClass        : 4

See the examples folder or the documentation for more usage examples.

Feature Preview & Roadmap

Area	Status	Notes / References
MIP formulation	✅ Done	Based on Parmentier & Vidal (2020/2021).
Constraint Programming (CP)	✅ Done	Based on an upcoming paper.
MaxSAT formulation	✅ Done	Based on Raevskaya & Lehtonen (2025).
Heuristics	⏳ Upcoming	Fast approximate methods.
Other methods	⏳ Upcoming	Additional formulations under exploration.
AdaBoost support	✅ Ready	Fully supported in ocean.
Random Forest support	✅ Ready	Fully supported in ocean.
XGBoost support	✅ Ready	Fully supported in ocean.

Legend: ✅ available · ⏳ upcoming

Stargazers over time

References

• Axel Parmentier and Thibaut Vidal. 2021. Optimal Counterfactual Explanations in Tree Ensembles. In Proceedings of the thirty-eighth International Conference on Machine Learning. PMLR, 8276–8286. Available here.
• Raevskaya, Alesya & Lehtonen, Tuomo. (2025). Optimal Counterfactual Explanations for Random Forests with MaxSAT. 10.3233/FAIA250895. Available here.