Low-level Internals

This page documents the low-level helper classes that connect processed tabular columns to backend variables and tree encodings.

The notation is the same as in Mathematical Model:

• \(x\) is the counterfactual explanation,

• \(\hat{x}\) is the query instance,

• \(f\) is the ensemble decision function,

• \(p_{t,\ell}\) denotes the active leaf or path variable,

• \(\varepsilon_c\) is the tie-breaking margin.

Mapper utilities

class Indexer(*getters)

Bases: Generic

Memoized dispatcher used to resolve column positions efficiently.

Store the lookup functions used for each supported key arity.

__init__(*getters)

Store the lookup functions used for each supported key arity.

get(*keys)

Return the cached lookup result for keys.

Returns:

Memoized lookup result.

Return type:

V

class Mapper(mapping=None, *, columns=None, validate=True)

Bases: Mapping[Key, V], Generic

Map original feature names to transformed columns.

Both the counterfactual point \(x\) and the query \(\hat{x}\) are represented in this transformed coordinate system. The mapper is the low-level bridge between original feature semantics and processed columns.

Initialize a mapper from feature metadata and transformed columns.

Parameters:

• mapping – Mapping from original feature names to metadata objects.

• columns – Processed pandas index describing the transformed coordinates.

• validate – Whether to verify that mapping and columns are consistent.

__init__(mapping=None, *, columns=None, validate=True)

Initialize a mapper from feature metadata and transformed columns.

Parameters:

• mapping – Mapping from original feature names to metadata objects.

• columns – Processed pandas index describing the transformed coordinates.

• validate – Whether to verify that mapping and columns are consistent.

reduce(reducer)

Apply reducer to each mapped value and keep the original keys.

Returns:

Reduced mapping with the same keys.

Return type:

Mapping[Key, S]

apply(func)

Transform the mapped values while preserving the column structure.

Returns:

New mapper with transformed values and the same columns.

Return type:

Mapper[U]

__len__()

Return the number of original features tracked by the mapper.

Returns:

Number of original features.

Return type:

NonNegativeInt

__iter__()

Iterate over original feature names.

Returns:

Iterator over mapper keys.

Return type:

Iterator[Key]

__getitem__(key)

Return the mapped value associated with feature name key.

Returns:

Value associated with key.

Return type:

V

static _get_args(mapping, columns)

Normalize constructor arguments into a mapping and a column index.

Returns:

Pair (mapping, columns) ready for validation.

Return type:

Args[V]

_validate_args(mapping, columns, *, validate=True)

Check that the mapping metadata matches the transformed columns.

Raises:

ValueError – If feature names or one-hot codes do not match the column index.

_add_indexer()

Build the memoized index dispatcher used by idx.

Returns:

Index dispatcher for transformed columns.

Return type:

Indexer[Key, NonNegativeInt]

_add_getter(n)

Return the lookup function matching a given number of keys.

Returns:

Getter matching the requested key arity.

Return type:

Getter[Key, NonNegativeInt]

Raises:

ValueError – If the requested key arity is unsupported.

_get_with_name(name)

Resolve the transformed column index for a non-encoded feature name.

Returns:

Column position associated with name.

Return type:

NonNegativeInt

Raises:

KeyError – If name is not present in the mapper.

_get_with_code(name, code)

Resolve the transformed column index for a one-hot encoded feature code.

Returns:

Column position associated with (name, code).

Return type:

NonNegativeInt

Raises:

KeyError – If name or code is not present in the mapper.

static _repr(mapping)

Return a column-aligned string representation of a small mapping.

Returns:

Multi-line aligned representation of mapping.

Return type:

str

MIP managers

class FeatureManager(mapper)

Bases: object

Manage MIP feature variables for the counterfactual point \(x\).

This manager owns the backend-specific feature variables that represent the processed coordinates of the counterfactual explanation. The query \(\hat{x}\) only appears later when the model objective is built.

Wrap the parsed feature mapper in MIP-specific feature variables.

build_features(model)

Create backend variables for the coordinates of \(x\).

vget(i)

Return the solver variable for processed coordinate i of x.

Returns:

Solver variable representing the requested coordinate.

Return type:

gp.Var

_set_mapper(mapper)

Convert parsed feature metadata into backend-specific feature variables.

Raises:

ValueError – If mapper is empty.

class TreeManager(trees, *, weights=None, n_isolators=0, max_samples=0, flow_type=FlowType.CONTINUOUS)

Bases: object

Manage MIP tree variables and the ensemble decision function \(f\).

Each TreeVar encodes the active leaf or path decisions \(p_{t,\ell}\) for one tree. Aggregating those variables yields the backend expression for \(f(x)\).

Initialize the tree manager and record ensemble metadata.

build_trees(model)

Create the backend tree variables and cache the derived expressions.

After this call, the manager stores the aggregate path-length expression and the MIP representation of \(f(x)\).

weighted_function(weights)

Return the weighted ensemble decision function \(f(x)\).

Returns:

MIP expression representing \(f(x)\).

Return type:

gp.MLinExpr

xgb_margin_function(weights)

Return the XGBoost margin form of \(f(x)\).

This includes the base logit term in addition to the weighted tree contributions.

Returns:

Margin expression representing \(f(x)\).

Return type:

gp.MLinExpr

_set_trees(trees, *, flow_type)

Wrap parsed trees in backend-specific TreeVar objects.

Raises:

ValueError – If no tree is provided.

_set_weights(weights=None)

Validate and store the ensemble weights.

Raises:

ValueError – If the number of weights does not match the number of estimators.

_get_length()

Return the total isolation-path length expression.

Returns:

Sum of the isolation-tree path lengths.

Return type:

gp.LinExpr

_get_function()

Return the backend expression representing \(f(x)\).

Returns:

Cached MIP expression for \(f(x)\).

Return type:

gp.MLinExpr

class GarbageManager

Bases: object

Track temporary MIP variables and constraints tied to one query.

Initialize the container used for query-specific garbage objects.

add_garbage(*args)

Register temporary objects created for the current query.

remove_garbage(model)

Delete all registered temporary objects from the backend model.

CP managers

class FeatureManager(mapper)

Bases: object

Manage CP feature variables for the counterfactual point \(x\).

This manager owns the finite-domain variables representing the processed coordinates of the counterfactual explanation. The query \(\hat{x}\) only appears later in the objective terms.

Wrap the parsed feature mapper in CP-specific feature variables.

build_features(model)

Create CP variables for the coordinates of \(x\).

vget(i)

Return the CP variable for processed coordinate i of x.

Returns:

CP variable representing the requested coordinate.

Return type:

cp.IntVar

_set_mapper(mapper)

Convert parsed feature metadata into CP-specific feature variables.

Raises:

ValueError – If mapper is empty.

class TreeManager(trees, *, weights=None, scale=10000000000)

Bases: object

Manage CP tree variables and the scaled decision function \(f\).

Each TreeVar encodes the active leaf decisions \(p_{t,\ell}\) of one tree. Aggregating those variables yields the integer-scaled CP representation of \(f(x)\).

Initialize the tree manager and the score-scaling factor.

build_trees(model)

Create the CP tree variables and cache \(f(x)\).

weighted_function(weights)

Return the integer-scaled CP representation of \(f(x)\).

The returned dictionary maps each output-class pair (op, c) to the corresponding linear expression for \(f_c(x)\).

Returns:

Dictionary of scaled class-score expressions.

Return type:

dict[tuple[NonNegativeInt, NonNegativeInt], cp.LinearExpr]

_set_trees(trees)

Wrap parsed trees in CP-specific TreeVar objects.

Raises:

ValueError – If no tree is provided.

_set_weights(weights=None)

Validate and store the ensemble weights.

Raises:

ValueError – If the number of weights does not match the number of estimators.

_get_function()

Return the cached CP representation of \(f(x)\).

Returns:

Cached class-score expressions.

Return type:

dict[tuple[NonNegativeInt, NonNegativeInt], cp.LinearExpr]

class GarbageManager

Bases: object

Track temporary CP variables and constraints tied to one query.

Initialize the container used for query-specific garbage objects.

add_garbage(*args)

Register temporary objects created for the current query.

remove_garbage()

Clear all registered temporary CP objects from the model state.

MaxSAT managers

class FeatureManager(mapper)

Bases: object

Manage MaxSAT feature variables for the counterfactual point \(x\).

This manager owns the Boolean or interval-selector variables representing the processed coordinates of the counterfactual explanation. The query \(\hat{x}\) only appears later in the soft objective clauses.

Wrap parsed features in MaxSAT-specific backend variables.

build_features(model)

Create MaxSAT variables for the coordinates of \(x\).

vget(i)

Return the literal representing processed coordinate i of x.

Returns:

Literal representing the requested coordinate.

Return type:

int

_set_mapper(mapper)

Convert parsed feature metadata into MaxSAT-specific feature variables.

Raises:

ValueError – If mapper is empty.

class TreeManager(trees, *, weights=None)

Bases: object

Manage MaxSAT tree variables and the support encoding of \(f\).

Each TreeVar encodes the active leaf decisions \(p_{t,\ell}\) of one tree. The stored function representation is a Boolean support view of \(f(x)\) used by the MaxSAT encoding.

Initialize the tree manager and validate the estimator weights.

build_trees(model)

Create the MaxSAT tree variables and cache \(f(x)\) support.

weighted_function()

Return the Boolean support representation used for \(f(x)\).

Each entry (op, c) stores the leaf literals whose active leaf supports class \(c\) for output op.

Returns:

Boolean support literals grouped by output and class.

Return type:

dict[tuple[NonNegativeInt, NonNegativeInt], list[int]]

_set_trees(trees)

Wrap parsed trees in MaxSAT-specific TreeVar objects.

Raises:

ValueError – If no tree is provided.

_set_weights(weights=None)

Validate and store the ensemble weights.

Raises:

ValueError – If the number of weights does not match the number of estimators.

_get_function()

Return the cached MaxSAT support representation.

Returns:

Cached Boolean support representation.

Return type:

dict[tuple[NonNegativeInt, NonNegativeInt], list[int]]

class GarbageManager

Bases: object

Track temporary MaxSAT clause identifiers tied to one query.

Initialize the container used for query-specific clause ids.

add_garbage(*args)

Register temporary clause identifiers created for one query.

remove_garbage()

Forget all registered temporary clause identifiers.

garbage_list()

Return the registered clause identifiers in insertion order.

Returns:

Registered clause identifiers.

Return type:

list[GarbageObject]