Explainer Guide

This page focuses on the common public API shared by the three explainers and highlights the few places where backend behavior differs.

Constructor pattern

All public explainers follow the same constructor shape.

explainer = SomeExplainer(model, mapper=mapper)

The two required inputs are:

• a fitted supported tree ensemble,

• the mapper returned by ocean.feature.parse_features().

Two optional constructor arguments are especially useful when you compare backends:

• isolation=some_isolation_forest is supported by the MIP and CP explainers and adds an isolation-forest plausibility constraint.

• isolation_threshold=... can be passed together with isolation=... on MIP and CP. 0.5 reproduces the historical cutoff, values closer to 1 are weaker, and smaller values are stricter.

• hard_voting=True is supported by the MaxSAT explainer for RandomForestClassifier and switches the score comparison from soft class proportions to per-tree votes.

Calling explain

Every explainer exposes an explain method with the same core arguments.

x

Query instance as a one-dimensional numpy array in the processed feature space.

y

Target class to enforce in the counterfactual.

norm

Distance norm. The MIP backend supports 1 and 2. The CP backend supports integer norms with 1 as the default. The MaxSAT backend supports 1.

max_time

Solver time limit in seconds.

num_workers

Parallel worker count when the backend exposes it.

random_seed

Solver seed for more repeatable runs. The MaxSAT backend currently accepts this argument for API compatibility but does not use it.

verbose

Whether to print solver logs.

Backend-specific behavior

Runtime differences

Topic	MIP	CP	MaxSAT
Norm support	L1 and L2	Integer Lp norms, default L1	L1 only
Anytime callback	Yes	Yes	No public callback list
Automatic cleanup after solve	Yes by default	Yes	Yes
Isolation forest support	Yes	Yes	No
Hard-voting random forest mode	No	No	Yes

Repeated solves

All three explainers default to clean_up=True inside explain. That means query-specific objectives and target-class constraints are removed automatically after each solve unless you opt out.

Call cleanup() manually only when you deliberately run explain(..., clean_up=False) and want to clear the previous query state yourself before reusing the same explainer instance.

One backend detail matters when you keep old explanations around. The CP and MaxSAT explanation objects read values back from the current shared backend solver state, so they behave like live views rather than frozen snapshots. If you want to preserve one result before another CP or MaxSAT solve, materialize it immediately with explanation.to_numpy().copy() or explanation.to_series().copy().

Inspecting the result

Once a counterfactual is found, these access patterns are typically the most useful.

• explanation.x gives the processed numerical vector.

• explanation.to_series() keeps the processed column names.

• explanation.value decodes one-hot groups into original category labels.

• explainer.get_objective_value() returns the backend objective value for the last solve.

• explainer.get_distance() returns the post-processed distance between the query and the decoded counterfactual using the norm from the last explain(...) call.

• repr(explanation) is usually the best display form for notebooks and logs.

Handling infeasibility and time limits

All explainers return None when no counterfactual is found under the given constraints. Depending on the backend, the solver may also warn when:

• the target class is infeasible,

• a feasible solution was found but optimality could not be certified in time,

• the solver terminated for a backend-specific reason.

When that happens, increase max_time, simplify the ensemble, or choose a query whose target class is realistically reachable under the learned model. For MIP and CP with isolation=..., also check whether isolation_threshold is too strict for the target region.