Target models#

class model.model_object.ModelObject(seed=None, device='cpu', **kwargs)[source]#

Bases: ABC

Base class for a target classifier that recourse methods explain.

Subclasses implement fit(), get_prediction(), and forward(). The predict()/predict_proba() methods are inherited batching wrappers over get_prediction(). Differentiable (torch) models implement forward() for gradient-based recourse; tree/sklearn models may raise from forward(). device must match the recourse method’s device.

Parameters:

seed (int | None)
device (str)

_need_grad#

Whether the model supports differentiable (gradient) access.

Type:: bool

_is_trained#

Set to True by fit(); guards inference.

Type:: bool

abstractmethod fit(trainset)[source]#

Train the model on a frozen training dataset.

Parameters:: trainset (DatasetObject or None) – Finalized training data. Implementations should set self._is_trained = True on success.

abstractmethod get_prediction(X, proba=True)[source]#

Predict on a feature dataframe.

Parameters:

X (pandas.DataFrame) – Feature rows (no target column).
proba (bool, default True) – If True return class probabilities; otherwise return logits.

Returns:

A (n_rows, n_classes) tensor. Typically decorated with process_nan().

Return type:

torch.Tensor

predict(testset, batch_size=20)[source]#

Batched logits over a frozen dataset.

Parameters:

testset (DatasetObject) – Frozen dataset to predict on.
batch_size (int, default 20) – Rows per inference batch.

Returns:

Concatenated (n_rows, n_classes) logits on CPU.

Return type:

torch.Tensor

Raises:

RuntimeError – If the model is not trained.

predict_proba(testset, batch_size=20)[source]#

Batched class probabilities over a frozen dataset.

Parameters:

testset (DatasetObject) – Frozen dataset to predict on.
batch_size (int, default 20) – Rows per inference batch.

Returns:

Concatenated (n_rows, n_classes) probabilities on CPU.

Return type:

torch.Tensor

abstractmethod forward(X)[source]#

Differentiable forward pass on a feature tensor.

Parameters:: X (torch.Tensor) – Batch of feature rows.
Returns:: Logits. Non-differentiable models should raise RuntimeError.
Return type:: torch.Tensor

__call__(X)[source]#

Alias for forward().

Parameters:: X (torch.Tensor)
Return type:: torch.Tensor

extract_training_data(trainset)[source]#

Split a trainset into features, integer labels, and output dimension.

Builds and stores the class-to-index mapping used to translate model outputs back to dataset labels.

Parameters:: trainset (DatasetObject) – Frozen training dataset.
Returns:: Features X, integer labels, and the number of output classes.
Return type:: tuple[pandas.DataFrame, torch.Tensor, int]

get_class_to_index()[source]#

Return the mapping from dataset label to model output index.

Returns:: Copy of the label-to-index mapping established during fit().
Return type:: dict
Raises:: RuntimeError – If the mapping is unavailable (model not yet trained).

model.model_object.process_nan()[source]#

Decorator factory for ModelObject.get_prediction().

Wraps a prediction method so that any input row containing NaN (the convention for a failed counterfactual) is temporarily zero-filled before inference and its output is forced to -1 afterwards, keeping invalid rows from contaminating predictions.

Returns:: A decorator to apply to a get_prediction(self, X, ...) method.
Return type:: callable