psyke 0.8.14.dev6__tar.gz → 0.9.0__tar.gz

{psyke-0.8.14.dev6/psyke.egg-info → psyke-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: psyke
-Version: 0.8.14.dev6
+Version: 0.9.0
 Summary: Python-based implementation of PSyKE, i.e. a Platform for Symbolic Knowledge Extraction
 Home-page: https://github.com/psykei/psyke-python
 Author: Matteo Magnini

psyke-0.9.0/VERSION

@@ -0,0 +1 @@
+0.9.0

{psyke-0.8.14.dev6 → psyke-0.9.0}/psyke/__init__.py

@@ -5,16 +5,20 @@ from enum import Enum
 
 import numpy as np
 import pandas as pd
+from matplotlib import pyplot as plt
 from sklearn.linear_model import LinearRegression
 from sklearn.metrics import mean_absolute_error, mean_squared_error, r2_score, f1_score, accuracy_score, \
     adjusted_rand_score, adjusted_mutual_info_score, v_measure_score, fowlkes_mallows_score
+from tuprolog.solve.prolog import prolog_solver
 
 from psyke.schema import DiscreteFeature
 from psyke.utils import get_default_random_seed, Target, get_int_precision
-from tuprolog.theory import Theory
+from tuprolog.theory import Theory, mutable_theory
 from typing import Iterable
 import logging
 
+from psyke.utils.logic import get_in_rule, data_to_struct, get_not_in_rule
+
 logging.basicConfig(level=logging.WARN)
 logger = logging.getLogger('psyke')
 
@@ -52,7 +56,7 @@ class EvaluableModel(object):
         """
         Predicts the output values of every sample in dataset.
 
-        :param dataframe: is the set of instances to predict.
+        :param dataframe: the set of instances to predict.
         :return: a list of predictions.
         """
         return self.__convert(self._predict(dataframe))
@@ -85,7 +89,7 @@ class EvaluableModel(object):
     def score(self, dataframe: pd.DataFrame, predictor=None, fidelity: bool = False, completeness: bool = True,
               brute: bool = False, criterion: str = 'corners', n: int = 2,
               task: EvaluableModel.Task = Task.CLASSIFICATION,
-              scoring_function: Iterable[EvaluableModel.Score] = [ClassificationScore.ACCURACY]):
+              scoring_function: Iterable[EvaluableModel.Score] = (ClassificationScore.ACCURACY, )):
         extracted = np.array(
             self.predict(dataframe.iloc[:, :-1]) if not brute else
             self.brute_predict(dataframe.iloc[:, :-1], criterion, n)
@@ -151,42 +155,113 @@ class Extractor(EvaluableModel, ABC):
     def __init__(self, predictor, discretization: Iterable[DiscreteFeature] = None, normalization=None):
         super().__init__(discretization, normalization)
         self.predictor = predictor
+        self.theory = None
 
     def extract(self, dataframe: pd.DataFrame) -> Theory:
         """
         Extracts rules from the underlying predictor.
 
-        :param dataframe: is the set of instances to be used for the extraction.
+        :param dataframe: the set of instances to be used for the extraction.
         :return: the theory created from the extracted rules.
         """
         raise NotImplementedError('extract')
 
-    def predict_why(self, data: dict[str, float], verbose=True):
+    def predict_why(self, data: dict[str, float], verbose: bool = True):
         """
         Provides a prediction and the corresponding explanation.
-        :param data: is the instance to predict.
-        :param verbose: if the explanation has to be printed.
+        :param data: the instance to predict.
+        :param verbose: if True the explanation is printed.
         """
         raise NotImplementedError('predict_why')
 
-    def predict_counter(self, data: dict[str, float], verbose=True, only_first=True):
+    def predict_counter(self, data: dict[str, float], verbose: bool = True, only_first: bool = True):
         """
         Provides a prediction and counterfactual explanations.
-        :param data: is the instance to predict.
-        :param verbose: if the counterfactual explanation has to be printed.
-        :param only_first: if only the closest counterfactual explanation is provided for each distinct class.
+        :param data: the instance to predict.
+        :param verbose: if True the counterfactual explanation is printed.
+        :param only_first: if True only the closest counterfactual explanation is provided for each distinct class.
         """
         raise NotImplementedError('predict_counter')
 
+    def plot_fairness(self, dataframe: pd.DataFrame, groups: dict[str, list], colormap='seismic_r', filename=None,
+                      figsize=(5, 4)):
+        """
+        Provides a visual estimation of the fairness exhibited by an extractor with respect to the specified groups.
+        :param dataframe: the set of instances to be used for the estimation.
+        :param groups: the set of relevant groups to consider.
+        :param colormap: the colormap to use for the plot.
+        :param filename: if not None, name used to save the plot.
+        :param figsize: size of the plot.
+        """
+        counts = {group: len(dataframe[idx_g]) for group, idx_g in groups.items()}
+        output = {'labels': []}
+        for group in groups:
+            output[group] = []
+        for i, clause in enumerate(self.theory.clauses):
+            if len(dataframe) == 0:
+                break
+            solver = prolog_solver(static_kb=mutable_theory(clause).assertZ(get_in_rule()).assertZ(get_not_in_rule()))
+            idx = np.array([query.is_yes for query in
+                            [solver.solveOnce(data_to_struct(data)) for _, data in dataframe.iterrows()]])
+            # print(f'Rule {i + 1}. Outcome {clause.head.args[-1]}. Affecting', end='')
+            output['labels'].append(str(clause.head.args[-1]))
+            for group, idx_g in groups.items():
+                # print(f' {len(dataframe[idx & idx_g]) / counts[group]:.2f}%{group}', end='')
+                output[group].append(len(dataframe[idx & idx_g]) / counts[group])
+            dataframe = dataframe[~idx]
+            groups = {group: indices[~idx] for group, indices in groups.items()}
+            # print(f'. Left {len(dataframe)} instances')
+
+        binary = len(set(output['labels'])) == 2
+        labels = sorted(set(output['labels']))
+        data = np.vstack([output[group] for group in groups]).T * 100
+        if binary:
+            data[np.array(output['labels']) == labels[0]] *= -1
+
+        plt.figure(figsize=figsize)
+        plt.imshow(data, cmap=colormap, vmin=-100 if binary else 0, vmax=100)
+
+        plt.gca().set_xticks(range(len(groups)), labels=groups.keys())
+        plt.gca().set_yticks(range(len(output['labels'])),
+                             labels=[f'Rule {i + 1}\n{l}' for i, l in enumerate(output['labels'])])
+
+        plt.xlabel('Groups')
+        plt.ylabel('Rules')
+        plt.title("Rule set impact on groups")
+
+        for i in range(len(output['labels'])):
+            for j in range(len(groups)):
+                plt.gca().text(j, i, f'{abs(int(data[i, j]))}%', ha="center", va="center", color="k")
+
+        plt.gca().set_xticks([i + .5 for i in range(len(groups))], minor=True)
+        plt.gca().set_yticks([i + .5 for i in range(len(output['labels']))], minor=True)
+        plt.gca().grid(which='minor', color='k', linestyle='-', linewidth=.8)
+        plt.gca().tick_params(which='minor', bottom=False, left=False)
+        cbarticks = np.linspace(-100 if binary else 0, 100, 9 if binary else 11, dtype=int)
+        cbar = plt.colorbar(fraction=0.046, label='Affected samples (%)', ticks=cbarticks)
+        if binary:
+            ticklabels = [str(-i) if i < 0 else str(i) for i in cbarticks]
+            ticklabels[0] += f' {labels[0]}'
+            ticklabels[-1] += f' {labels[-1]}'
+            cbar.ax.set_yticklabels(ticklabels)
+
+        plt.tight_layout()
+        if filename is not None:
+            plt.savefig(filename, dpi=500)
+        plt.show()
+
+    def make_fair(self, features: Iterable[str]):
+        raise NotImplementedError(f'Fairness for {type(self).__name__} is not supported at the moment')
+
     def mae(self, dataframe: pd.DataFrame, predictor=None, brute: bool = False, criterion: str = 'center',
             n: int = 3) -> float:
         """
         Calculates the predictions' MAE w.r.t. the instances given as input.
 
-        :param dataframe: is the set of instances to be used to calculate the mean absolute error.
+        :param dataframe: the set of instances to be used to calculate the mean absolute error.
         :param predictor: if provided, its predictions on the dataframe are taken instead of the dataframe instances.
         :param brute: if True, a brute prediction is executed.
-        :param criterion: creterion for brute prediction.
+        :param criterion: criterion for brute prediction.
         :param n: number of points for brute prediction with 'perimeter' criterion.
         :return: the mean absolute error (MAE) of the predictions.
         """
@@ -198,10 +273,10 @@ class Extractor(EvaluableModel, ABC):
         """
         Calculates the predictions' MSE w.r.t. the instances given as input.
 
-        :param dataframe: is the set of instances to be used to calculate the mean squared error.
+        :param dataframe: the set of instances to be used to calculate the mean squared error.
         :param predictor: if provided, its predictions on the dataframe are taken instead of the dataframe instances.
         :param brute: if True, a brute prediction is executed.
-        :param criterion: creterion for brute prediction.
+        :param criterion: criterion for brute prediction.
         :param n: number of points for brute prediction with 'perimeter' criterion.
         :return: the mean squared error (MSE) of the predictions.
         """
@@ -213,10 +288,10 @@ class Extractor(EvaluableModel, ABC):
         """
         Calculates the predictions' R2 score w.r.t. the instances given as input.
 
-        :param dataframe: is the set of instances to be used to calculate the R2 score.
+        :param dataframe: the set of instances to be used to calculate the R2 score.
         :param predictor: if provided, its predictions on the dataframe are taken instead of the dataframe instances.
         :param brute: if True, a brute prediction is executed.
-        :param criterion: creterion for brute prediction.
+        :param criterion: criterion for brute prediction.
         :param n: number of points for brute prediction with 'perimeter' criterion.
         :return: the R2 score of the predictions.
         """
@@ -224,14 +299,14 @@ class Extractor(EvaluableModel, ABC):
                           Extractor.Task.REGRESSION, [Extractor.RegressionScore.R2])[Extractor.RegressionScore.R2][-1]
 
     def accuracy(self, dataframe: pd.DataFrame, predictor=None, brute: bool = False, criterion: str = 'center',
-            n: int = 3) -> float:
+                 n: int = 3) -> float:
         """
         Calculates the predictions' accuracy classification score w.r.t. the instances given as input.
 
-        :param dataframe: is the set of instances to be used to calculate the accuracy classification score.
+        :param dataframe: the set of instances to be used to calculate the accuracy classification score.
         :param predictor: if provided, its predictions on the dataframe are taken instead of the dataframe instances.
         :param brute: if True, a brute prediction is executed.
-        :param criterion: creterion for brute prediction.
+        :param criterion: criterion for brute prediction.
         :param n: number of points for brute prediction with 'perimeter' criterion.
         :return: the accuracy classification score of the predictions.
         """
@@ -244,10 +319,10 @@ class Extractor(EvaluableModel, ABC):
         """
         Calculates the predictions' F1 score w.r.t. the instances given as input.
 
-        :param dataframe: is the set of instances to be used to calculate the F1 score.
+        :param dataframe: the set of instances to be used to calculate the F1 score.
         :param predictor: if provided, its predictions on the dataframe are taken instead of the dataframe instances.
         :param brute: if True, a brute prediction is executed.
-        :param criterion: creterion for brute prediction.
+        :param criterion: criterion for brute prediction.
         :param n: number of points for brute prediction with 'perimeter' criterion.
         :return: the F1 score of the predictions.
         """
@@ -331,7 +406,7 @@ class Extractor(EvaluableModel, ABC):
 
     @staticmethod
     def creepy(predictor, clustering, depth: int, error_threshold: float, output: Target = Target.CONSTANT,
-               gauss_components: int = 2, ranks: [(str, float)] = [], ignore_threshold: float = 0.0,
+               gauss_components: int = 2, ranks: Iterable[(str, float)] = tuple(), ignore_threshold: float = 0.0,
                discretization=None, normalization: dict[str, tuple[float, float]] = None,
                seed: int = get_default_random_seed()) -> Extractor:
         """

psyke-0.9.0/psyke/extraction/__init__.py

@@ -0,0 +1,51 @@
+from abc import ABC
+from collections import Iterable
+
+import pandas as pd
+from tuprolog.theory import Theory
+
+from psyke import Extractor
+
+
+class PedagogicalExtractor(Extractor, ABC):
+
+    def __init__(self, predictor, discretization=None, normalization=None):
+        Extractor.__init__(self, predictor=predictor, discretization=discretization, normalization=normalization)
+
+    def _substitute_output(self, dataframe: pd.DataFrame) -> pd.DataFrame:
+        new_y = pd.DataFrame(self.predictor.predict(dataframe.iloc[:, :-1])).set_index(dataframe.index)
+        data = dataframe.iloc[:, :-1].copy().join(new_y)
+        data.columns = dataframe.columns
+        return data
+
+    def extract(self, dataframe: pd.DataFrame) -> Theory:
+        self.theory = self._extract(self._substitute_output(dataframe))
+        return self.theory
+
+    def _extract(self, dataframe: pd.DataFrame) -> Theory:
+        raise NotImplementedError('extract')
+
+
+class FairExtractor(PedagogicalExtractor, ABC):
+
+    def __init__(self, extractor: Extractor, features: Iterable):
+        super().__init__(extractor.predictor, extractor.discretization, extractor.normalization)
+        self.features = features
+        self.extractor = extractor
+        # self.make_fair()
+
+#    def extract(self, dataframe: pd.DataFrame) -> Theory:
+#        self.theory = self.extractor.extract(dataframe)
+#        return self.theory
+
+#    def predict_why(self, data: dict[str, float], verbose: bool = True):
+#        self.extractor.predict_why(data, verbose)
+
+#    def predict_counter(self, data: dict[str, float], verbose: bool = True, only_first: bool = True):
+#        self.extractor.predict_counter(data, verbose, only_first)
+
+#    def _predict(self, dataframe: pd.DataFrame) -> Iterable:
+#        return self.extractor.predict(dataframe)
+
+#    def _brute_predict(self, dataframe: pd.DataFrame, criterion: str = 'corner', n: int = 2) -> Iterable:
+#        return self.extractor.brute_predict(dataframe, criterion, n)

psyke-0.8.14.dev6/psyke/extraction/cart/predictor.py → psyke-0.9.0/psyke/extraction/cart/CartPredictor.py

@@ -1,11 +1,14 @@
 from collections import Iterable
 from typing import Union, Any
 import numpy as np
+import pandas as pd
 from sklearn.tree import DecisionTreeClassifier, DecisionTreeRegressor
-from psyke.schema import Value, LessThan, GreaterThan, SchemaException
+from tuprolog.core import clause, Var, Struct
+from tuprolog.theory import Theory, mutable_theory
 
-LeafConstraints = dict[str, list[Value]]
-LeafSequence = Iterable[tuple[LeafConstraints, Any]]
+from psyke.extraction.cart import LeafConstraints, LeafSequence
+from psyke.schema import LessThan, GreaterThan, SchemaException, DiscreteFeature
+from psyke.utils.logic import create_variable_list, create_head, create_term
 
 
 class CartPredictor:
@@ -14,8 +17,9 @@ class CartPredictor:
     """
 
     def __init__(self, predictor: Union[DecisionTreeClassifier, DecisionTreeRegressor] = DecisionTreeClassifier(),
-                 normalization=None):
+                 discretization=None, normalization=None):
         self._predictor = predictor
+        self.discretization = discretization
         self.normalization = normalization
 
     def __get_constraints(self, nodes: Iterable[(int, bool)]) -> LeafConstraints:
@@ -62,6 +66,47 @@ class CartPredictor:
     def predict(self, data) -> Iterable:
         return self._predictor.predict(data)
 
+    @staticmethod
+    def _simplify_nodes(nodes: list) -> Iterable:
+        simplified = [nodes.pop(0)]
+        while len(nodes) > 0:
+            first_node = nodes[0][0]
+            for k, conditions in first_node.items():
+                for condition in conditions:
+                    if all(k in node[0] and condition in node[0][k] for node in nodes):
+                        [node[0][k].remove(condition) for node in nodes]
+            simplified.append(nodes.pop(0))
+        return [({k: v for k, v in rule.items() if v != []}, prediction) for rule, prediction in simplified]
+
+    def _create_body(self, variables: dict[str, Var], conditions: LeafConstraints) -> Iterable[Struct]:
+        results = []
+        for feature_name, cond_list in conditions.items():
+            for condition in cond_list:
+                feature: DiscreteFeature = [d for d in self.discretization if feature_name in d.admissible_values][0] \
+                    if self.discretization else None
+                results.append(create_term(variables[feature_name], condition) if feature is None else
+                               create_term(variables[feature.name],
+                                           feature.admissible_values[feature_name],
+                                           isinstance(condition, GreaterThan)))
+        return results
+
+    def create_theory(self, data: pd.DataFrame, simplify: True) -> Theory:
+        new_theory = mutable_theory()
+        nodes = [node for node in self]
+        nodes = self._simplify_nodes(nodes) if simplify else nodes
+        for (constraints, prediction) in nodes:
+            if self.normalization is not None and data.columns[-1] in self.normalization:
+                m, s = self.normalization[data.columns[-1]]
+                prediction = prediction * s + m
+            variables = create_variable_list(self.discretization, data)
+            new_theory.assertZ(
+                clause(
+                    create_head(data.columns[-1], list(variables.values()), prediction),
+                    self._create_body(variables, constraints)
+                )
+            )
+        return new_theory
+
     @property
     def predictor(self) -> Union[DecisionTreeClassifier, DecisionTreeRegressor]:
         return self._predictor

psyke-0.9.0/psyke/extraction/cart/FairTree.py

@@ -0,0 +1,196 @@
+import numpy as np
+from collections import Counter
+
+from sklearn.metrics import accuracy_score, r2_score
+
+
+class Node:
+    def __init__(self, feature=None, threshold=None, left=None, right=None, *, value=None):
+        self.feature = feature
+        self.threshold = threshold
+        self.left = left
+        self.right = right
+        self.value = value
+
+    def is_leaf_node(self):
+        return self.value is not None
+
+
+class FairTree:
+    def __init__(self, max_depth=3, max_leaves=None, criterion=None, min_samples_split=2, lambda_penalty=0.0,
+                 protected_attr=None):
+        self.max_depth = max_depth
+        self.max_leaves = max_leaves
+        self.min_samples_split = min_samples_split
+        self.lambda_penalty = lambda_penalty
+        self.protected_attr = protected_attr
+        self.criterion = criterion
+        self.root = None
+        self.n_leaves = 0
+        self.quality_function = None
+
+    def fit(self, X, y):
+        self.n_leaves = 0
+        self.root = self._grow_tree(X, y, depth=0)
+        while self.n_leaves > self.max_leaves:
+            self.prune_least_important_leaf(X, y)
+            self.n_leaves -= 1
+        return self
+
+    @staticmethod
+    def _estimate_output(y):
+        raise NotImplementedError
+
+    def score(self, X, y):
+        raise NotImplementedError
+
+    def predict(self, X):
+        return np.array([self._traverse_tree(x, self.root) for _, x in X.iterrows()])
+
+    def _traverse_tree(self, x, node):
+        if node.is_leaf_node():
+            return node.value
+        if x[node.feature] <= node.threshold:
+            return self._traverse_tree(x, node.left)
+        return self._traverse_tree(x, node.right)
+
+    def _grow_tree(self, X, y, depth):
+        if depth >= self.max_depth or X.shape[0] < self.min_samples_split or len(set(y.values.flatten())) == 1 or \
+                (self.max_leaves is not None and self.n_leaves >= self.max_leaves):
+            self.n_leaves += 1
+            return Node(value=self._estimate_output(y))
+
+        best_feature, best_threshold = self._best_split(X, y)
+        if best_feature is None:
+            self.n_leaves += 1
+            return Node(value=self._estimate_output(y))
+
+        left_idxs = X[best_feature] <= best_threshold
+        right_idxs = X[best_feature] > best_threshold
+
+        left = self._grow_tree(X[left_idxs], y[left_idxs], depth + 1)
+        right = self._grow_tree(X[right_idxs], y[right_idxs], depth + 1)
+        return Node(best_feature, best_threshold, left, right)
+
+    def _best_split(self, X, y):
+        best_gain = -float('inf')
+        split_idx, split_threshold = None, None
+
+        for feature in [feature for feature in X.columns if feature not in self.protected_attr]:
+            for threshold in np.unique(np.quantile(X[feature], np.linspace(0, 1, num=25))):
+                left_idxs = X[feature] <= threshold
+                right_idxs = X[feature] > threshold
+
+                if left_idxs.sum() == 0 or right_idxs.sum() == 0:
+                    continue
+
+                gain = self._fair_gain(y, left_idxs, right_idxs, X[self.protected_attr])
+
+                if gain > best_gain:
+                    best_gain = gain
+                    split_idx = feature
+                    split_threshold = threshold
+        return split_idx, split_threshold
+
+    @staticmethod
+    def _disparity(group):
+        counts = Counter(group)
+        if len(counts) <= 1:
+            return 0.0
+        values = np.array(list(counts.values())) / len(group)
+        return np.abs(values[0] - values[1])
+
+    def _fair_gain(self, y, left_idx, right_idx, protected):
+        child = len(y[left_idx]) / len(y) * self.quality_function(y[left_idx]) + \
+                len(y[right_idx]) / len(y) * self.quality_function(y[right_idx])
+        info_gain = self.quality_function(y) - child
+        penalty = self._disparity(protected[left_idx]) + self._disparity(protected[right_idx])
+        return info_gain - self.lambda_penalty * penalty
+
+    @staticmethod
+    def _match_path(x, path):
+        for node, left in path:
+            if left and x[node.feature] > node.threshold:
+                return False
+            if not left and x[node.feature] <= node.threshold:
+                return False
+        return True
+
+    @staticmethod
+    def candidates(node, parent=None, is_left=None, path=[]):
+        if node is None or node.is_leaf_node():
+            return []
+        leaves = []
+        if node.left.is_leaf_node() and node.right.is_leaf_node():
+            leaves.append((node, parent, is_left, path))
+        leaves += FairTreeClassifier.candidates(node.left, node, True, path + [(node, True)])
+        leaves += FairTreeClassifier.candidates(node.right, node, False, path + [(node, False)])
+        return leaves
+
+    def prune_least_important_leaf(self, X, y):
+        best_score = -np.inf
+        best_prune = None
+
+        for node, parent, is_left, path in self.candidates(self.root):
+            original_left = node.left
+            original_right = node.right
+
+            merged_y = y[(X.apply(lambda x: self._match_path(x, path), axis=1))]
+            if len(merged_y) == 0:
+                continue
+            new_value = self._estimate_output(merged_y)
+            node.left = node.right = None
+            node.value = new_value
+
+            score = self.score(X, y)
+            if score >= best_score:
+                best_score = score
+                best_prune = (node, new_value)
+
+            node.left, node.right, node.value = original_left, original_right, None
+
+        if best_prune:
+            best_prune[0].left = best_prune[0].right = None
+            best_prune[0].value = best_prune[1]
+
+
+class FairTreeClassifier(FairTree):
+    def __init__(self, max_depth=3, max_leaves=None, criterion='entropy', min_samples_split=2, lambda_penalty=0.0,
+                 protected_attr=None):
+        super().__init__(max_depth, max_leaves, criterion, min_samples_split, lambda_penalty, protected_attr)
+        self.quality_function = self._gini if self.criterion == 'gini' else self._entropy
+
+    @staticmethod
+    def _estimate_output(y):
+        return Counter(y.values.flatten()).most_common(1)[0][0]
+
+    def score(self, X, y):
+        return accuracy_score(y.values.flatten(), self.predict(X))
+
+    @staticmethod
+    def _entropy(y):
+        ps = np.unique(y, return_counts=True)[1] / len(y)
+        return -np.sum([p * np.log2(p) for p in ps if p > 0])
+
+    @staticmethod
+    def _gini(y):
+        return 1.0 - np.sum(np.unique(y, return_counts=True)[1] / len(y)**2)
+
+
+class FairTreeRegressor(FairTree):
+    def __init__(self, max_depth=3, max_leaves=None, criterion='mse', min_samples_split=2, lambda_penalty=0.0,
+                 protected_attr=None):
+        super().__init__(max_depth, max_leaves, criterion, min_samples_split, lambda_penalty, protected_attr)
+        self.quality_function = self._mse
+
+    @staticmethod
+    def _estimate_output(y):
+        return np.mean(y.values.flatten())
+
+    def score(self, X, y):
+        return r2_score(y.values.flatten(), self.predict(X))
+
+    @staticmethod
+    def _mse(y):
+        y = y.values.flatten().astype(float)
+        return np.mean((y - np.mean(y))**2)

psyke-0.9.0/psyke/extraction/cart/FairTreePredictor.py

@@ -0,0 +1,62 @@
+import copy
+from collections import Iterable
+from typing import Union, Any
+import pandas as pd
+from sklearn.tree import DecisionTreeClassifier, DecisionTreeRegressor
+from tuprolog.core import clause, Var, Struct
+from tuprolog.theory import Theory, mutable_theory
+
+from psyke.extraction.cart import FairTreeClassifier, FairTreeRegressor, LeafSequence, LeafConstraints
+from psyke.extraction.cart.CartPredictor import CartPredictor
+from psyke.schema import LessThan, GreaterThan, SchemaException, DiscreteFeature, Value
+from psyke.utils.logic import create_variable_list, create_head, create_term
+
+
+class FairTreePredictor(CartPredictor):
+    """
+    A wrapper for fair decision and regression trees of psyke.
+    """
+
+    def __init__(self, predictor: Union[FairTreeClassifier, FairTreeRegressor] = DecisionTreeClassifier(),
+                 discretization=None, normalization=None):
+        super().__init__(predictor, discretization, normalization)
+
+    def __iter__(self) -> LeafSequence:
+        leaves = [node for node in self.recurse(self._predictor.root, {})]
+        return (leaf for leaf in leaves)
+
+    @staticmethod
+    def merge_constraints(constraints: LeafConstraints, constraint: Value, feature: str):
+        if feature in constraints:
+            try:
+                constraints[feature][-1] *= constraint
+            except SchemaException:
+                constraints[feature].append(constraint)
+        else:
+            constraints[feature] = [constraint]
+        return constraints
+
+    def recurse(self, node, constraints) -> Union[LeafSequence, tuple[LeafConstraints, Any]]:
+        if node.is_leaf_node():
+            return constraints, node.value
+
+        feature = node.feature
+        threshold = node.threshold if self.normalization is None else \
+            (node.threshold * self.normalization[feature][1] + self.normalization[feature][0])
+
+        left = self.recurse(node.left, self.merge_constraints(copy.deepcopy(constraints), LessThan(threshold), feature))
+        right = self.recurse(node.right, self.merge_constraints(copy.deepcopy(constraints),
+                                                                GreaterThan(threshold), feature))
+        return (left if isinstance(left, list) else [left]) + (right if isinstance(right, list) else [right])
+
+    @property
+    def predictor(self) -> Union[FairTreeClassifier, FairTreeRegressor]:
+        return self._predictor
+
+    @property
+    def n_leaves(self) -> int:
+        return self._predictor.n_leaves
+
+    @predictor.setter
+    def predictor(self, predictor: Union[FairTreeClassifier, FairTreeRegressor]):
+        self._predictor = predictor

psyke-0.9.0/psyke/extraction/cart/__init__.py

@@ -0,0 +1,71 @@
+from abc import ABC
+
+from sklearn.tree import DecisionTreeClassifier, DecisionTreeRegressor
+
+from psyke.extraction import PedagogicalExtractor
+from psyke import get_default_random_seed
+from psyke.extraction.cart.FairTree import FairTreeClassifier, FairTreeRegressor
+from psyke.schema import DiscreteFeature, Value
+from tuprolog.theory import Theory
+from typing import Iterable, Any
+import pandas as pd
+
+
+TREE_SEED = get_default_random_seed()
+
+LeafConstraints = dict[str, list[Value]]
+LeafSequence = Iterable[tuple[LeafConstraints, Any]]
+
+
+class Cart(PedagogicalExtractor, ABC):
+
+    def __init__(self, predictor, max_depth: int = 3, max_leaves: int = None, max_features=None,
+                 discretization: Iterable[DiscreteFeature] = None,
+                 normalization=None, simplify: bool = True):
+        from psyke.extraction.cart.CartPredictor import CartPredictor
+
+        super().__init__(predictor, discretization, normalization)
+        self.is_fair = None
+        self._cart_predictor = CartPredictor(discretization=discretization, normalization=normalization)
+        self.depth = max_depth
+        self.leaves = max_leaves
+        self.max_features = max_features
+        self._simplify = simplify
+
+    def _extract(self, data: pd.DataFrame) -> Theory:
+        from psyke.extraction.cart.FairTreePredictor import FairTreePredictor
+
+        if self.is_fair:
+            self._cart_predictor = FairTreePredictor(discretization=self.discretization,
+                                                     normalization=self.normalization)
+            fair_tree = FairTreeClassifier if isinstance(data.iloc[0, -1], str) else FairTreeRegressor
+            self._cart_predictor.predictor = fair_tree(max_depth=self.depth, max_leaves=self.leaves,
+                                                       protected_attr=self.is_fair)
+        else:
+            tree = DecisionTreeClassifier if isinstance(data.iloc[0, -1], str) else DecisionTreeRegressor
+            self._cart_predictor.predictor = tree(random_state=TREE_SEED, max_depth=self.depth,
+                                                  max_leaf_nodes=self.leaves, max_features=self.max_features)
+        self._cart_predictor.predictor.fit(data.iloc[:, :-1], data.iloc[:, -1])
+        return self._cart_predictor.create_theory(data, self._simplify)
+
+    def make_fair(self, features: Iterable[str]):
+        self.is_fair = features
+
+    def _predict(self, dataframe: pd.DataFrame) -> Iterable:
+        return self._cart_predictor.predict(dataframe)
+
+    def predict_why(self, data: dict[str, float], verbose=True):
+        prediction = None
+        conditions = {}
+        if self.normalization is not None:
+            data = {k: v * self.normalization[k][1] + self.normalization[k][0] if k in self.normalization else v
+                    for k, v in data.items()}
+        for conditions, prediction in self._cart_predictor:
+            if all(all(interval.is_in(data[variable]) for interval in intervals)
+                   for variable, intervals in conditions.items()):
+                break
+        return prediction, conditions
+
+    @property
+    def n_rules(self) -> int:
+        return self._cart_predictor.n_leaves

{psyke-0.8.14.dev6 → psyke-0.9.0}/psyke/extraction/hypercubic/__init__.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
-import math
 from abc import ABC
+from collections import Iterable
+
 import numpy as np
 import pandas as pd
 from sklearn.base import ClassifierMixin
@@ -13,7 +14,7 @@ from psyke.extraction import PedagogicalExtractor
 from psyke.extraction.hypercubic.hypercube import HyperCube, RegressionCube, ClassificationCube, ClosedCube, Point, \
     GenericCube
 from psyke.hypercubepredictor import HyperCubePredictor
-from psyke.schema import Between, Outside, Value
+from psyke.schema import Value
 from psyke.utils.logic import create_variable_list, create_head, to_var, Simplifier
 from psyke.utils import Target
 from psyke.extraction.hypercubic.strategy import Strategy, FixedStrategy
@@ -209,10 +210,16 @@ class FeatureRanker:
 
 
 class Grid:
-    def __init__(self, iterations: int = 1, strategy: Strategy | list[Strategy] = FixedStrategy()):
+    def __init__(self, iterations: int = 1, strategy: Strategy | Iterable[Strategy] = FixedStrategy()):
         self.iterations = iterations
         self.strategy = strategy
 
+    def make_fair(self, features: Iterable[str]):
+        if isinstance(self.strategy, Strategy):
+            self.strategy.make_fair(features)
+        elif isinstance(self.strategy, Iterable):
+            [strategy.make_fair(features) for strategy in self.strategy]
+
     def get(self, feature: str, depth: int) -> int:
         if isinstance(self.strategy, list):
             return self.strategy[depth].get(feature)

{psyke-0.8.14.dev6 → psyke-0.9.0}/psyke/extraction/hypercubic/creepy/__init__.py

@@ -17,7 +17,7 @@ class CReEPy(HyperCubeExtractor):
     """
 
     def __init__(self, predictor, clustering=Clustering.exact, depth: int = 3, error_threshold: float = 0.1,
-                 output: Target = Target.CONSTANT, gauss_components: int = 5, ranks: list[(str, float)] = [],
+                 output: Target = Target.CONSTANT, gauss_components: int = 5, ranks: Iterable[(str, float)] = tuple(),
                  ignore_threshold: float = 0.0, discretization=None, normalization=None,
                  seed: int = get_default_random_seed()):
         super().__init__(predictor, Target.CLASSIFICATION if isinstance(predictor, ClassifierMixin) else output,

{psyke-0.8.14.dev6 → psyke-0.9.0}/psyke/extraction/hypercubic/gridex/__init__.py

@@ -117,3 +117,6 @@ class GridEx(HyperCubeExtractor):
                 to_split = [cube for cube in to_split if cube not in best[0]] + [best[1]]
                 not_in_cache = [best[1]]
         return to_split
+
+    def make_fair(self, features: Iterable[str]):
+        self.grid.make_fair(features)

{psyke-0.8.14.dev6 → psyke-0.9.0}/psyke/extraction/hypercubic/iter/__init__.py

@@ -23,6 +23,7 @@ class ITER(HyperCubeExtractor):
             raise NotImplementedError
         self.predictor = predictor
         self.min_update = min_update
+        self._init_points = n_points
         self.n_points = n_points
         self.max_iterations = max_iterations
         self.min_examples = min_examples
@@ -33,6 +34,10 @@ class ITER(HyperCubeExtractor):
         self.seed = seed
         self.ignore_dimensions = ignore_dimensions if ignore_dimensions is not None else []
 
+    def make_fair(self, features: Iterable[str]):
+        self.n_points = self._init_points
+        self.ignore_dimensions += list(features)
+
     def _best_cube(self, dataframe: pd.DataFrame, cube: GenericCube, cubes: Iterable[Expansion]) -> Expansion | None:
         expansions = []
         for limit in cubes:

{psyke-0.8.14.dev6 → psyke-0.9.0}/psyke/extraction/hypercubic/strategy.py

@@ -1,16 +1,20 @@
 from __future__ import annotations
 
 from functools import reduce
-from typing import Iterable
+from collections import Iterable
 
 
 class Strategy:
-    def __init__(self):
-        self._partitions = None
+    def __init__(self, partitions = None):
+        self._partitions = partitions
+        self._no_features = []
 
     def get(self, feature: str) -> int:
         raise NotImplementedError
 
+    def make_fair(self, features: Iterable[str]):
+        self._no_features = features
+
     def partition_number(self, features: Iterable[str]) -> int:
         return reduce(lambda x, y: x * y, map(self.get, features), 1)
 
@@ -29,23 +33,23 @@ class Strategy:
 
 class FixedStrategy(Strategy):
     def __init__(self, partitions: int = 2):
-        super().__init__()
-        self._partitions = partitions
+        super().__init__(partitions)
 
     def get(self, feature: str) -> int:
-        return self._partitions
+        return 1 if feature in self._no_features else self._partitions
 
     def __str__(self):
         return "Fixed ({})".format(super().__str__())
 
 
 class AdaptiveStrategy(Strategy):
-    def __init__(self, features: Iterable[str], partitions: Iterable[tuple[float, float]] | None = None):
-        super().__init__()
+    def __init__(self, features: Iterable[(str, float)], partitions: Iterable[tuple[float, float]] | None = None):
+        super().__init__(partitions if partitions is not None else [(0.33, 2), (0.67, 3)])
         self.features = features
-        self._partitions = partitions if partitions is not None else [(0.33, 2), (0.67, 3)]
 
     def get(self, feature: str) -> int:
+        if feature in self._no_features:
+            return 1
         importance = next(filter(lambda t: t[0] == feature, self.features))[1]
         n = 1
         for (imp, part) in self._partitions:

{psyke-0.8.14.dev6 → psyke-0.9.0}/psyke/tuning/pedro/__init__.py

@@ -55,8 +55,10 @@ class PEDRO(SKEOptimizer, IterativeOptimizer):
         patience = self.patience
         while patience > 0:
             print("{}. {}. Threshold = {:.2f}. ".format(self.algorithm_name, grid, threshold), end="")
-            extractor = self.algorithm(self.predictor, grid, min_examples=25, output=self.output,
-                                       threshold=threshold, normalization=self.normalization)
+            param_dict = dict(min_examples=25, threshold=threshold, normalization=self.normalization)
+            if self.algorithm != Extractor.gridrex:
+                param_dict['output'] = self.output
+            extractor = self.algorithm(self.predictor, grid, **param_dict)
             _ = extractor.extract(self.dataframe)
             error_function = (lambda *x: 1 - extractor.accuracy(*x)) if self.output == Target.CLASSIFICATION \
                 else extractor.mae

{psyke-0.8.14.dev6 → psyke-0.9.0}/psyke/utils/logic.py

@@ -126,7 +126,7 @@ def to_var(name: str) -> Var:
 def create_variable_list(features: list[DiscreteFeature], dataset: pd.DataFrame = None) -> dict[str, Var]:
     dataset = dataset.columns[:-1] if dataset is not None else None
     values = {feature.name: to_var(feature.name) for feature in features} \
-        if len(features) > 0 else {name: to_var(name) for name in dataset}
+        if features else {name: to_var(name) for name in dataset}
     return values
 
 

{psyke-0.8.14.dev6 → psyke-0.9.0/psyke.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: psyke
-Version: 0.8.14.dev6
+Version: 0.9.0
 Summary: Python-based implementation of PSyKE, i.e. a Platform for Symbolic Knowledge Extraction
 Home-page: https://github.com/psykei/psyke-python
 Author: Matteo Magnini

{psyke-0.8.14.dev6 → psyke-0.9.0}/psyke.egg-info/SOURCES.txt

@@ -17,8 +17,10 @@ psyke/clustering/utils.py
 psyke/clustering/cream/__init__.py
 psyke/clustering/exact/__init__.py
 psyke/extraction/__init__.py
+psyke/extraction/cart/CartPredictor.py
+psyke/extraction/cart/FairTree.py
+psyke/extraction/cart/FairTreePredictor.py
 psyke/extraction/cart/__init__.py
-psyke/extraction/cart/predictor.py
 psyke/extraction/hypercubic/__init__.py
 psyke/extraction/hypercubic/hypercube.py
 psyke/extraction/hypercubic/strategy.py

psyke-0.8.14.dev6/VERSION

@@ -1 +0,0 @@
-0.8.14.dev6

psyke-0.8.14.dev6/psyke/extraction/__init__.py

@@ -1,21 +0,0 @@
-from abc import ABC
-
-import pandas as pd
-from tuprolog.theory import Theory
-
-from psyke import Extractor
-
-
-class PedagogicalExtractor(Extractor, ABC):
-
-    def __init__(self, predictor, discretization=None, normalization=None):
-        Extractor.__init__(self, predictor=predictor, discretization=discretization, normalization=normalization)
-
-    def extract(self, dataframe: pd.DataFrame) -> Theory:
-        new_y = pd.DataFrame(self.predictor.predict(dataframe.iloc[:, :-1])).set_index(dataframe.index)
-        data = dataframe.iloc[:, :-1].copy().join(new_y)
-        data.columns = dataframe.columns
-        return self._extract(data)
-
-    def _extract(self, dataframe: pd.DataFrame) -> Theory:
-        raise NotImplementedError('extract')

psyke-0.8.14.dev6/psyke/extraction/cart/__init__.py

@@ -1,96 +0,0 @@
-from abc import ABC
-
-from sklearn.tree import DecisionTreeClassifier, DecisionTreeRegressor
-
-from psyke.extraction import PedagogicalExtractor
-from psyke.extraction.cart.predictor import CartPredictor, LeafConstraints, LeafSequence
-from psyke import get_default_random_seed
-from psyke.schema import GreaterThan, DiscreteFeature
-from psyke.utils.logic import create_variable_list, create_head, create_term
-from tuprolog.core import clause, Var, Struct
-from tuprolog.theory import Theory, mutable_theory
-from typing import Iterable
-import pandas as pd
-
-
-TREE_SEED = get_default_random_seed()
-
-
-class Cart(PedagogicalExtractor, ABC):
-
-    def __init__(self, predictor, max_depth: int = 3, max_leaves: int = None, max_features=None,
-                 discretization: Iterable[DiscreteFeature] = None,
-                 normalization=None, simplify: bool = True):
-        super().__init__(predictor, discretization, normalization)
-        self._cart_predictor = CartPredictor(normalization=normalization)
-        self.depth = max_depth
-        self.leaves = max_leaves
-        self.max_features = max_features
-        self._simplify = simplify
-
-    def _create_body(self, variables: dict[str, Var], conditions: LeafConstraints) -> Iterable[Struct]:
-        results = []
-        for feature_name, cond_list in conditions.items():
-            for condition in cond_list:
-                features = [d for d in self.discretization if feature_name in d.admissible_values]
-                feature: DiscreteFeature = features[0] if len(features) > 0 else None
-                results.append(create_term(variables[feature_name], condition) if feature is None else
-                               create_term(variables[feature.name],
-                                           feature.admissible_values[feature_name],
-                                           isinstance(condition, GreaterThan)))
-        return results
-
-    @staticmethod
-    def _simplify_nodes(nodes: list) -> Iterable:
-        simplified = [nodes.pop(0)]
-        while len(nodes) > 0:
-            first_node = nodes[0][0]
-            for k, conditions in first_node.items():
-                for condition in conditions:
-                    if all(k in node[0] and condition in node[0][k] for node in nodes):
-                        [node[0][k].remove(condition) for node in nodes]
-            simplified.append(nodes.pop(0))
-        return [({k: v for k, v in rule.items() if v != []}, prediction) for rule, prediction in simplified]
-
-    def _create_theory(self, data: pd.DataFrame) -> Theory:
-        new_theory = mutable_theory()
-        nodes = [node for node in self._cart_predictor]
-        nodes = Cart._simplify_nodes(nodes) if self._simplify else nodes
-        for (constraints, prediction) in nodes:
-            if self.normalization is not None and data.columns[-1] in self.normalization:
-                m, s = self.normalization[data.columns[-1]]
-                prediction = prediction * s + m
-            variables = create_variable_list(self.discretization, data)
-            new_theory.assertZ(
-                clause(
-                    create_head(data.columns[-1], list(variables.values()), prediction),
-                    self._create_body(variables, constraints)
-                )
-            )
-        return new_theory
-
-    def _extract(self, data: pd.DataFrame) -> Theory:
-        tree = DecisionTreeClassifier if isinstance(data.iloc[0, -1], str) else DecisionTreeRegressor
-        self._cart_predictor.predictor = tree(random_state=TREE_SEED, max_depth=self.depth,
-                                              max_leaf_nodes=self.leaves, max_features=self.max_features)
-        self._cart_predictor.predictor.fit(data.iloc[:, :-1], data.iloc[:, -1])
-        return self._create_theory(data)
-
-    def _predict(self, dataframe: pd.DataFrame) -> Iterable:
-        return self._cart_predictor.predict(dataframe)
-
-    def predict_why(self, data: dict[str, float], verbose=True):
-        prediction = None
-        conditions = {}
-        if self.normalization is not None:
-            data = {k: v * self.normalization[k][1] + self.normalization[k][0] if k in self.normalization else v
-                    for k, v in data.items()}
-        for conditions, prediction in self._cart_predictor:
-            if all(all(interval.is_in(data[variable]) for interval in intervals)
-                   for variable, intervals in conditions.items()):
-                break
-        return prediction, conditions
-
-    @property
-    def n_rules(self) -> int:
-        return self._cart_predictor.n_leaves