rocelib.recourse_methods package

Submodules

rocelib.recourse_methods.BinaryLinearSearch module

class rocelib.recourse_methods.BinaryLinearSearch.BinaryLinearSearch(ct, custom_distance_func=None)[source]

Bases: RecourseGenerator

A recourse generator that uses binary linear search to find counterfactual explanations.

Inherits from the RecourseGenerator class and implements the _generation_method to perform binary linear search for generating counterfactuals.

_task

The task to solve, inherited from RecourseGenerator.

Type:

Task

__customFunc

A custom distance function, inherited from RecourseGenerator.

Type:

callable, optional

rocelib.recourse_methods.GuidedBinaryLinearSearch module

class rocelib.recourse_methods.GuidedBinaryLinearSearch.GuidedBinaryLinearSearch(ct, custom_distance_func=None)[source]

Bases: RecourseGenerator

rocelib.recourse_methods.KDTreeNNCE module

class rocelib.recourse_methods.KDTreeNNCE.KDTreeNNCE(ct, custom_distance_func=None)[source]

Bases: RecourseGenerator

A recourse generator that uses KD-Tree for nearest neighbor counterfactual explanations.

Inherits from the RecourseGenerator class and implements the _generation_method to find counterfactual explanations using KD-Tree for nearest neighbors.

_task

The task to solve, inherited from RecourseGenerator.

Type:

Task

__customFunc

A custom distance function, inherited from RecourseGenerator.

Type:

callable, optional

rocelib.recourse_methods.MCE module

class rocelib.recourse_methods.MCE.MCE(ct)[source]

Bases: RecourseGenerator

A recourse generator that uses Mixed-Integer Linear Programming (MILP) to find counterfactual explanations.

Inherits from the RecourseGenerator class and implements the _generation_method to find counterfactual explanations using MILP with the Gurobi optimizer.

_task

The task to solve, inherited from RecourseGenerator.

Type:

Task

__customFunc

A custom distance function, inherited from RecourseGenerator.

Type:

callable, optional

opt

An optimizer instance for setting up and solving the MILP problem.

Type:

OptSolver

rocelib.recourse_methods.MCER module

class rocelib.recourse_methods.MCER.MCER(ct, evaluator=<class 'rocelib.robustness_evaluations.DeltaRobustnessEvaluator.DeltaRobustnessEvaluator'>)[source]

Bases: RecourseGenerator

A recourse generator that uses the Mixed-Integer Linear Programming (MILP) method and a robustness evaluator to find counterfactual explanations that are robust against perturbations.

Inherits from RecourseGenerator and combines MCE with a robustness evaluation mechanism.

_task

The task to solve, inherited from RecourseGenerator.

Type:

Task

__customFunc

A custom distance function, inherited from RecourseGenerator.

Type:

callable, optional

mce

An instance of the MCE class for generating counterfactuals using MILP.

Type:

MCE

evaluator

An instance of the DeltaRobustnessEvaluator for evaluating robustness.

Type:

DeltaRobustnessEvaluator

rocelib.recourse_methods.ModelMultiplicityMILP module

class rocelib.recourse_methods.ModelMultiplicityMILP.ModelMultiplicityMILP(dl, models)[source]

Bases: RecourseGenerator

rocelib.recourse_methods.ModelMultiplicityMILP.create_weights_and_bias_dictionary(model)[source]

layer 0 is input layer

rocelib.recourse_methods.NNCE module

class rocelib.recourse_methods.NNCE.NNCE(ct, custom_distance_func=None)[source]

Bases: RecourseGenerator

A recourse generator that uses a nearest-neighbor counterfactual explanation (NNCE) approach.

Inherits from RecourseGenerator and calculates counterfactual explanations based on the nearest neighbor in the training data with the desired prediction.

_task

The task to solve, inherited from RecourseGenerator.

Type:

Task

__customFunc

A custom distance function, inherited from RecourseGenerator.

Type:

callable, optional

rocelib.recourse_methods.RNCE module

class rocelib.recourse_methods.RNCE.RNCE(task)[source]

Bases: RecourseGenerator

A recourse generator that finds robust nearest counterfactual examples using KDTree.

Inherits from the RecourseGenerator class and implements the _generation_method to find counterfactual examples that are robust to perturbations. It leverages KDTree for nearest neighbor search and uses a robustness evaluator to identify robust instances in the training data.

intabs

An evaluator for checking the robustness of instances to perturbations.

Type:

DeltaRobustnessEvaluator

getCandidates(robustInit, delta, bias_delta, column_name='target', neg_value=0)[source]

Retrieves candidate instances from the dataset that are robust to perturbations.

@param robustInit: If True, only robust instances are considered. @param delta: The tolerance for robustness in the feature space. @param bias_delta: The bias tolerance for robustness in the feature space. @param column_name: The name of the target column. @param neg_value: The value considered negative in the target variable. @return: A DataFrame containing robust instances from the dataset.

rocelib.recourse_methods.RecourseGenerator module

class rocelib.recourse_methods.RecourseGenerator.RecourseGenerator(ct, custom_distance_func=None)[source]

Bases: ABC

Abstract class for generating counterfactual explanations for a given task.

This class provides a framework for generating counterfactuals based on a distance function and a given task. It supports default distance functions such as Euclidean and Manhattan, and allows for custom distance functions.

_task

The task to solve.

Type:

Task

__customFunc

A custom distance function.

Type:

callable, optional

property custom_distance_func

Returns custom distance function passed at instantiation @return: distance Function, (DataFrame, DataFrame) -> Int

generate(instances, neg_value=0, column_name='target', **kwargs)[source]

Generates counterfactuals for a given DataFrame of instances.

@param instances: A DataFrame of instances for which you want to generate recourses. @param distance_func: The method to calculate the distance between two points. Options are ‘l1’ / ‘manhattan’, ‘l2’ / ‘euclidean’, and ‘custom’. @param column_name: The name of the target column. @param neg_value: The value considered negative in the target variable. @return: A DataFrame of the recourses for the provided instances.

Return type:

DataFrame

generate_for_all(neg_value=0, column_name='target', **kwargs)[source]

Generates counterfactuals for all instances with a given negative value in their target column.

@param neg_value: The value in the target column which counts as a negative instance. @param column_name: The name of the target variable. @param distance_func: The method to calculate the distance between two points. Options are ‘l1’ / ‘manhattan’, ‘l2’ / ‘euclidean’, and ‘custom’. @return: A DataFrame of the recourses for all negative values.

Return type:

DataFrame

generate_for_instance(instance, neg_value=0, column_name='target', **kwargs)[source]

Generates a counterfactual for a provided instance.

@param instance: The instance for which you would like to generate a counterfactual. @param distance_func: The method to calculate the distance between two points. Options are ‘l1’ / ‘manhattan’, ‘l2’ / ‘euclidean’, and ‘custom’. @param column_name: The name of the target column. @param neg_value: The value considered negative in the target variable. @return: A DataFrame containing the recourse for the instance.

Return type:

DataFrame

property task

rocelib.recourse_methods.STCE module

class rocelib.recourse_methods.STCE.TrexNN(ct, custom_distance_func=None)[source]

Bases: RecourseGenerator

A recourse generator that uses the T-Rex method for finding robust counterfactual explanations.

Inherits from the RecourseGenerator class and implements the _generation_method to find counterfactual examples with robustness checks using a specified base method and evaluator. The method iterates over positive instances and evaluates their robustness, returning those with stable counterfactuals.

None specific to this class, but utilizes the task and model from the RecourseGenerator base class.
counterfactual_stability(xp)[source]

Evaluates the stability of a given counterfactual instance.

@param xp: The instance for which to evaluate counterfactual stability. @return: A tensor representing the stability score of the counterfactual.

rocelib.recourse_methods.Wachter module

class rocelib.recourse_methods.Wachter.CostLoss[source]

Bases: Module

Custom loss function to calculate the absolute difference between two tensors.

Inherits from nn.Module.

forward(x1, x2)[source]

Computes the forward pass of the loss function.

@param x1: The first tensor (e.g., the original instance). @param x2: The second tensor (e.g., the counterfactual instance). @return: The absolute difference between x1 and x2.

class rocelib.recourse_methods.Wachter.Wachter(ct, custom_distance_func=None)[source]

Bases: RecourseGenerator

A recourse generator that uses Wachter’s method for finding counterfactual explanations.

Inherits from RecourseGenerator and implements the _generation_method to find counterfactuals using gradient descent.

Module contents