Using RecourseBench#

This is the canonical, user-facing API. Import the package as rb and use the named namespaces to construct components, or run() to execute a whole experiment from a config.

import recourse_bench as rb

metrics = rb.run(config)              # run an experiment from a config dict

model  = rb.models.linear(seed=7)     # construct components by name
method = rb.methods.wachter(target_model=model, seed=7, desired_class=1)
data   = rb.datasets.credit()

Named namespaces#

Each registered component is available as an attribute of a namespace, under its registry name. The attribute is the component class — call it to construct an instance. The namespaces are populated dynamically from the registry, so they always reflect the currently registered components.

Namespace

Base class

Contains

rb.datasets

DatasetObject

Tabular datasets, e.g. rb.datasets.credit

rb.preprocessors

PreProcessObject

Pipeline steps, e.g. rb.preprocessors.scale

rb.models

ModelObject

Target classifiers, e.g. rb.models.linear

rb.methods

MethodObject

Recourse methods, e.g. rb.methods.wachter

rb.evaluations

EvaluationObject

Evaluation metrics, e.g. rb.evaluations.validity

Constructor arguments match the corresponding base class (see Extending the framework for the full argument and method signatures). The lists below are a snapshot; call rb.list_datasets(), rb.list_methods(), etc. for the authoritative, up-to-date set. To iterate over components by name (e.g. for a sweep), use getattr:

for name in ["wachter", "dice", "gs"]:
    method = getattr(rb.methods, name)(target_model=model, seed=7)

Datasets — rb.datasets#

Available: adult, adult_cfrl, adult_cfvae, adult_cogs, boston_housing, breast_cancer, compas, compas_carla, compas_clue, credit, credit_cchvae, diabetes, german, german_roar, german_sns, hepatitis, news_popularity, synthetic_face, toydata (variants suffixed with a method name carry the features/metadata that method expects).

  • Construct: data = rb.datasets.credit() — no required arguments; the raw dataframe and feature metadata are loaded from the bundled offline data.

  • Output: a DatasetObject in its mutable state. Preprocessing steps mutate it; once frozen the read interface is data.get(target=False) (feature columns as a DataFrame), data.get(target=True) (the label column), len(data), data[idx], and data.attr(name) for feature metadata (type, mutability, actionability).

Preprocessors — rb.preprocessors#

Available: balance, encode, finalize, reorder, scale, split (a typical pipeline runs balance → encode → scale → split → finalize).

  • Construct: step = rb.preprocessors.scale(scaling="normalize") — seed plus step-specific options.

  • Input → output: step.transform(dataset) takes a mutable DatasetObject and returns the transformed dataset, or a tuple of datasets for steps that split (split → trainset, testset).

Models — rb.models#

Available: linear, mlp, mlp_bayesian, randomforest, sklearn_logistic_regression.

  • Construct: model = rb.models.linear(seed=7, device="cpu").

  • Inputs → outputs: model.fit(trainset) trains on a frozen DatasetObject; model.predict(testset) / model.predict_proba(testset) return a (n_rows, n_classes) torch.Tensor of logits / probabilities; model.get_prediction(X, proba=...) predicts on a feature DataFrame. Differentiable models also support model(X) / model.forward(X) on a feature tensor.

Methods — rb.methods#

Available: apas, arg_ensembling, cchvae, cemsp, cfrl, cfvae, claproar, clue, cogs, cols, cruds, cvas_proj, dice, diverse_dist, face, feature_tweak, gravitational, gs, larr, mace, probe, proplace, rbr, revise, roar, sns, toy, trex, wachter.

  • Construct: method = rb.methods.wachter(target_model=model, seed=7, desired_class=1) — wraps a (to-be-)trained model; desired_class steers which class counterfactuals move toward (None flips a binary label). Extra keyword arguments are method-specific hyperparameters.

  • Inputs → outputs: method.fit(trainset) builds any auxiliary search structures; method.get_counterfactuals(factuals) takes a feature DataFrame and returns one with the same rows and columns, with NaN rows where no valid counterfactual was found. The inherited method.predict(testset) runs that in batches and returns a frozen counterfactual DatasetObject carrying runtime, prediction, and target-label metadata (failed rows have NaN features and target -1).

Evaluations — rb.evaluations#

Available: constraints, distance, examples, knn, runtime, validity, ynn.

  • Construct: metric = rb.evaluations.validity() — metric-specific options (e.g. a reference set or distance norm).

  • Input → output: metric.evaluate(factuals, counterfactuals) takes the finalized factual dataset and the counterfactual dataset from method.predict and returns a single-row DataFrame of named metrics. Experiment concatenates these column-wise into the final metrics table.

Run an experiment#

For full control — including access to the trained model, the generated counterfactuals, and run provenance — use the Experiment class directly.

Discover components#