glance.counterfactual_tree package

Submodules

humancompatible.explain.glance.counterfactual_tree.counterfactual_tree module

class humancompatible.explain.glance.counterfactual_tree.counterfactual_tree.T_GLANCE(model: Any, split_features: List | int | None = None, partition_counterfactuals: int | None = None, child_count: int = 2, global_method: GlobalCounterfactualMethod | str | None = None, local_method: LocalCounterfactualMethod | str | None = None, num_local_counterfactuals: int = 100)

Bases: object

A class to generate counterfactual explanations using a decision tree-like structure.

This class allows users to create a tree structure for counterfactual generation, optimizing effectiveness and cost based on specified features. It supports both local and global methods for generating counterfactuals.

Attributes:

modelAny

The predictive model used for generating counterfactuals.

split_featuresUnion[List, int]

Features to split the tree. Can be a list of feature names or an integer specifying the number of top features to use based on permutation importance.

partition_counterfactualsint

The number of partitions to create for counterfactuals.

child_countint

The number of children each node can have.

global_methodUnion[GlobalCounterfactualMethod, str]

The global counterfactual generation method to use.

local_methodUnion[LocalCounterfactualMethod, str]

The local counterfactual generation method to use.

num_local_counterfactualsint

The number of local counterfactuals to generate.

nodeNode

The root node of the counterfactual tree.

node_instancespd.DataFrame

The instances that were used to build the counterfactual tree.

dist_func_dataframeCallable

A distance function for calculating distances between instances.

Methods:

fit(X, y, train_dataset=None, feat_to_vary=”all”, random_seed=13, numeric_features_names=None, categorical_features_names=None):

Fits the counterfactual tree to the provided data.

_local_group_eff_cost(instances):

Calculates the effectiveness and cost of local counterfactuals for a group of instances.

_group_eff_cost(instances):

Calculates the effectiveness and cost of counterfactuals for a group of instances, utilizing local or global methods.

partition_group(instances):

Partitions the group of instances into a tree structure based on the specified features.

cumulative_leaf_actions():

Computes the total effectiveness and cost of actions taken from leaf nodes of the tree.

Initializes the CounterfactualTree instance.

Parameters:

modelAny

The predictive model to use for generating counterfactuals.

split_featuresUnion[List, int], optional

Features to split the tree. If None, uses permutation importance to select. If an integer, selects the top N features.

partition_counterfactualsint, optional

Number of partitions for counterfactual generation.

child_countint, optional

Number of children for each node in the tree. Default is 2.

global_methodUnion[GlobalCounterfactualMethod, str], optional

The global counterfactual generation method to use.

local_methodUnion[LocalCounterfactualMethod, str], optional

The local counterfactual generation method to use.

num_local_counterfactualsint, optional

Number of local counterfactuals to generate. Default is 100.

cumulative_leaf_actions()

Computes the total effectiveness and cost of actions taken from leaf nodes of the tree.

Returns:

Tuple[float, float, int]

A tuple containing the total effectiveness, total cost, and the number of actions taken.

fit(X: DataFrame, y: Series, train_dataset: DataFrame | None = None, feat_to_vary: List[str] | str | None = 'all', random_seed: int = 13, numeric_features_names: List[str] | None = None, categorical_features_names: List[str] | None = None)

Fits the counterfactual tree to the provided data.

Parameters:

Xpd.DataFrame

Features of the dataset.

ypd.Series

Target variable.

train_datasetOptional[pd.DataFrame], optional

The training dataset to use for local counterfactual generation methods.

feat_to_varyOptional[Union[List[str], str]], optional

Features to vary in counterfactual generation. Default is “all”.

random_seedint, optional

Random seed for reproducibility. Default is 13.

numeric_features_namesOptional[List[str]], optional

List of numeric feature names. If None, they will be inferred from X.

categorical_features_namesOptional[List[str]], optional

List of categorical feature names. If None, they will be inferred from X.

partition_group(instances: DataFrame)

Partitions the group of instances into a tree structure based on the specified features.

Parameters:

instancespd.DataFrame

The group of instances to partition.

Returns:

Node

The root node of the partitioned tree.

humancompatible.glance.counterfactual_tree.node module

class humancompatible.explain.glance.counterfactual_tree.node.Node(split_feature=None, actions=None, effectiveness=0, cost=0, size=0)

Bases: object

A class representing a node in a decision tree structure.

Each node can have child nodes, actions associated with it, and metrics such as effectiveness and cost. This class provides methods to add child nodes, retrieve actions from leaf nodes, and visualize the tree structure.

Attributes:

split_featurestr or None

The feature used to split the data at this node. Default is None.

actionslist or None

A list of actions associated with this node. Default is None.

effectivenessfloat

The effectiveness of the actions taken at this node. Default is 0.

costfloat

The total cost associated with the actions at this node. Default is 0.

sizeint

The number of instances or data points at this node. Default is 0.

childrendict

A dictionary mapping from subgroup values to child nodes.

Methods:

add_child(subgroup, child_node):

Adds a child node to this node.

return_leafs_actions():

Returns all actions from the leaf nodes in the subtree rooted at this node.

to_igraph(numeric_features=[]):

Converts the tree structure to an igraph object for visualization.

display_igraph_jupyter(numeric_features=[]):

Displays the tree structure in a Jupyter notebook using matplotlib and igraph.

Initializes a new Node instance.

Parameters:

split_featurestr or None

The feature used to split the data at this node. Default is None.

actionslist or None

A list of actions associated with this node. Default is None.

effectivenessfloat

The effectiveness of the actions taken at this node. Default is 0.

costfloat

The total cost associated with the actions at this node. Default is 0.

sizeint

The number of instances or data points at this node. Default is 0.

add_child(subgroup, child_node)

Adds a child node to this node.

Parameters:

subgroupany

The value associated with the child node.

child_nodeNode

The child node to be added.

display_igraph_jupyter(numeric_features=[])

Displays the tree structure in a Jupyter notebook using matplotlib and igraph.

Parameters:

numeric_featureslist

A list of numeric feature names used for processing node labels.

return_leafs_actions()

Returns all actions from the leaf nodes in the subtree rooted at this node.

Returns:

list

A flattened list of actions from the leaf nodes.

to_igraph(numeric_features=[])

Converts the tree structure to an igraph object for visualization.

Parameters:

numeric_featureslist

A list of numeric feature names used for processing node labels.

Returns:

ig.Graph

An igraph object representing the tree structure.

Module contents