humancompatible-detect 0.1.4__py3-none-any.whl

humancompatible/detect/__init__.py

@@ -0,0 +1,13 @@
+from .detect_bias import most_biased_subgroup, most_biased_subgroup_csv, most_biased_subgroup_two_samples
+from .evaluate_bias import evaluate_biased_subgroup, evaluate_biased_subgroup_csv, evaluate_biased_subgroup_two_samples
+from .helpers.utils import detect_and_score
+
+__all__ = [
+    "detect_and_score",
+    "most_biased_subgroup",
+    "most_biased_subgroup_csv",
+    "most_biased_subgroup_two_samples",
+    "evaluate_biased_subgroup",
+    "evaluate_biased_subgroup_csv",
+    "evaluate_biased_subgroup_two_samples",
+]

humancompatible/detect/binarizer/Binarizer.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+from enum import Enum
+
+import numpy as np
+import pandas as pd
+
+from ..data_handler import DataHandler
+from ..data_handler.features import Binary, Categorical, Contiguous, Feature, Mixed
+from ..data_handler.types import CategValue, DataLike, OneDimData
+
+BinValue = float | tuple[float, float] | CategValue | list[CategValue] | bool
+
+
+class Operation(Enum):
+    EQ = "="
+    NE = "!="
+    LE = "<="
+    LT = "<"
+    GE = ">="
+    GT = ">"
+    IN = "in"
+    NOT_IN = "not in"
+    BETWEEN = "between"
+    OUTSIDE = "outside"
+
+    # TODO move the perform to the Bin class
+    @classmethod
+    def perform(
+        cls, op: Operation, vals: np.ndarray[int | float | str], reference: BinValue
+    ) -> np.ndarray[bool]:
+        if op == Operation.EQ:
+            return vals == reference
+        elif op == Operation.NE:
+            return vals != reference
+        elif op == Operation.LE:
+            return vals <= reference
+        elif op == Operation.LT:
+            return vals < reference
+        elif op == Operation.GE:
+            return vals >= reference
+        elif op == Operation.GT:
+            return vals > reference
+        elif op == Operation.IN:
+            result = np.zeros_like(vals, dtype=bool)
+            for r in reference:
+                result |= vals == r
+            return result
+        elif op == Operation.NOT_IN:
+            return ~Operation.perform(Operation.IN, vals, reference)
+        elif op == Operation.BETWEEN:
+            return (vals >= reference[0]) & (vals < reference[1])
+        elif op == Operation.OUTSIDE:
+            return ~Operation.perform(Operation.BETWEEN, vals, reference)
+        else:
+            raise NotImplementedError(f"Operation {op} is not implemented")
+
+    @classmethod
+    def negated(cls, op) -> Operation:
+        return {
+            Operation.EQ: Operation.NE,
+            Operation.NE: Operation.EQ,
+            Operation.LE: Operation.GT,
+            Operation.LT: Operation.GE,
+            Operation.GE: Operation.LT,
+            Operation.GT: Operation.LE,
+            Operation.IN: Operation.NOT_IN,
+            Operation.NOT_IN: Operation.IN,
+            Operation.BETWEEN: Operation.OUTSIDE,
+            Operation.OUTSIDE: Operation.BETWEEN,
+        }[op]
+
+
+class Bin:
+    def __init__(self, feature: Feature, operation: Operation, value: BinValue):
+        self.feature = feature
+        self.operation = operation
+        self.value = value
+
+    def negate_self(self):
+        if isinstance(self.feature, Binary):
+            vals = list(self.feature.value_mapping.keys())
+            negated_value = vals[0] if vals[1] == self.value else vals[1]
+            return Bin(self.feature, self.operation, negated_value)
+        else:
+            return Bin(self.feature, Operation.negated(self.operation), self.value)
+
+    def evaluate(self, values: np.ndarray[int | float | str]) -> np.ndarray[bool]:
+        return Operation.perform(self.operation, values, self.value)
+
+    def __repr__(self):
+        return f"Bin({repr(self.feature)}, {repr(self.operation)}, {repr(self.value)})"
+
+    def __str__(self):
+        return f"{str(self.feature)} {self.operation.value} {str(self.value)}"
+
+    def __eq__(self, other):
+        return (
+            self.feature == other.feature
+            and self.operation == other.operation
+            and self.value == other.value
+        )
+
+
+class Binarizer:
+    """Handles binarizing the dataset"""
+
+    # TODO add specific options for binarization of categoricals (only positive and custom sets) and continuous (custom bins - i.e. quantiles)
+    def __init__(
+        self,
+        data_handler: DataHandler,
+        target_positive_vals: list[CategValue] | None = None,
+    ):
+        self.__original_dhandler = data_handler
+
+        binarized_features: list[list[Bin]] = []
+        binarized_negations: list[list[Bin]] = []
+        for feature in data_handler.features:
+            if isinstance(feature, Contiguous):
+                binarizations = []
+                negations = []
+                minval, maxval = feature.bounds
+                # to make the last bin include the max value
+                eps = (maxval - minval) / 10000
+                n_bins = 10
+                prev = minval
+                for curr in np.linspace(minval, maxval + eps, n_bins + 1)[1:]:
+                    bounds = (prev, curr)
+                    binarizations.append(Bin(feature, Operation.BETWEEN, bounds))
+                    negations.append(Bin(feature, Operation.OUTSIDE, bounds))
+                    prev = curr
+                binarized_features.append(binarizations)
+                binarized_negations.append(negations)
+            elif isinstance(feature, Mixed):
+                raise NotImplementedError("Mixed features are not yet implemented")
+            elif isinstance(feature, Binary):
+                inv_map = {i: v for v, i in feature.value_mapping.items()}
+                binarized_features.append([Bin(feature, Operation.EQ, inv_map[1])])
+                binarized_negations.append([Bin(feature, Operation.EQ, inv_map[0])])
+            elif isinstance(feature, Categorical):
+                binarizations = []
+                negations = []
+                for value in feature.orig_vals:
+                    binarizations.append(Bin(feature, Operation.EQ, value))
+                    negations.append(Bin(feature, Operation.NE, value))
+                binarized_features.append(binarizations)
+                binarized_negations.append(negations)
+            else:
+                raise ValueError("Unsupported feature type")
+
+        # TARGET
+        target = data_handler.target_feature
+        if isinstance(target, Binary):
+            inv_map = {i: v for v, i in target.value_mapping.items()}
+            self.binarized_target = Bin(target, Operation.EQ, inv_map[1])
+            self.binarized_target_neg = Bin(target, Operation.EQ, inv_map[0])
+        elif isinstance(target, Categorical) and (target_positive_vals is not None):
+            self.binarized_target = Bin(target, Operation.IN, target_positive_vals)
+            negative_vals = [
+                v for v in target.orig_vals if v not in target_positive_vals
+            ]
+            self.binarized_target_neg = Bin(target, Operation.IN, negative_vals)
+        else:
+            raise NotImplementedError(
+                "Target feature must be Binary or Categorical with single binarization"
+            )
+
+        self.__binarized_features = binarized_features
+        self.__binarized_negations = binarized_negations
+
+    def encode(
+        self, X: DataLike, include_negations=False, include_binary_negations=False
+    ) -> np.ndarray[bool]:
+        if isinstance(X, pd.DataFrame):
+            X = X.values
+
+        values = []
+        for i, binariaztions in enumerate(self.__binarized_features):
+            for bin in binariaztions:
+                values.append(Operation.perform(bin.operation, X[:, [i]], bin.value))
+        if include_negations:
+            for i, binariaztions in enumerate(self.__binarized_negations):
+                for bin in binariaztions:
+                    values.append(
+                        Operation.perform(bin.operation, X[:, [i]], bin.value)
+                    )
+        elif include_binary_negations:
+            for i, binariaztions in enumerate(self.__binarized_negations):
+                for bin in binariaztions:
+                    if isinstance(bin.feature, Binary):
+                        values.append(
+                            Operation.perform(bin.operation, X[:, [i]], bin.value)
+                        )
+        return np.hstack(values)
+
+    def encode_y(self, y: OneDimData) -> np.ndarray[bool]:
+        if isinstance(y, pd.Series):
+            y = y.values
+        res = Operation.perform(
+            self.binarized_target.operation, y, self.binarized_target.value
+        )
+        return res.flatten()
+
+    def __feature_name_tuples(self, include_negations, include_binary_negations):
+        names = []
+        if include_negations:
+            feats = self.__binarized_features + self.__binarized_negations
+        else:
+            feats = [f for f in self.__binarized_features]
+            if include_binary_negations:
+                for binarization in self.__binarized_negations:
+                    if isinstance(binarization[0].feature, Binary):
+                        feats.append(binarization)
+        for binarization in feats:
+            for bin in binarization:
+                names.append((bin.feature.name, bin.operation.value, str(bin.value)))
+        return names
+
+    def feature_names(
+        self, include_negations=False, include_binary_negations=False
+    ) -> list[str]:
+        return [
+            f"{feat} {op} {val}"
+            for (feat, op, val) in self.__feature_name_tuples(
+                include_negations, include_binary_negations
+            )
+        ]
+
+    def target_name(self) -> tuple[str, str]:
+        bin = self.binarized_target
+        positive = f"{bin.feature} {bin.operation.value} {bin.value}"
+        bin = self.binarized_target_neg
+        negative = f"{bin.feature} {bin.operation.value} {bin.value}"
+        return positive, negative
+
+    def multi_index_feats(
+        self, include_negations=False, include_binary_negations=False
+    ) -> pd.MultiIndex:
+        return pd.MultiIndex.from_tuples(
+            self.__feature_name_tuples(include_negations, include_binary_negations),
+            names=["feature", "operation", "value"],
+        )
+
+    def get_bin_encodings(
+        self, include_negations=False, include_binary_negations=False, return_flat=True
+    ):
+        if include_negations:
+            feats = self.__binarized_features + self.__binarized_negations
+        else:
+            feats = [f for f in self.__binarized_features]
+            if include_binary_negations:
+                for binarization in self.__binarized_negations:
+                    if isinstance(binarization[0].feature, Binary):
+                        feats.append(binarization)
+        if not return_flat:
+            return feats
+        flat = []
+        for binariaztions in feats:
+            for bin in binariaztions:
+                flat.append(bin)
+        return flat
+
+    @property
+    def data_handler(self):
+        return self.__original_dhandler

humancompatible/detect/binarizer/__init__.py

@@ -0,0 +1,3 @@
+from .Binarizer import Bin, Binarizer, Operation
+
+__all__ = ["Bin", "Binarizer", "Operation"]

humancompatible/detect/data_handler/DataHandler.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from .features import (
+    Binary,
+    Categorical,
+    Contiguous,
+    Feature,
+    Monotonicity,
+    make_feature,
+)
+from .types import CategValue, DataLike, FeatureID, OneDimData
+
+
+class DataHandler:
+    """
+    Performs all data processing from a pandas DataFrame/numpy array to a normalized and encoded input
+    Expected use is to initialize this with training data and then use it to encode all data.
+    Supports mixed encoding, where only some values are categorical
+    Normalizes contiguous data to [0, 1] range
+    Produces either one-hot encoded data or direct data with mapped categorical data to negative integers
+    """
+
+    def __init__(
+        self,
+        features: list[Feature],
+        target: Feature | None = None,
+        causal_inc: list[tuple[Feature, Feature]] | None = None,
+        greater_than: list[tuple[Feature, Feature]] | None = None,
+    ):
+        self.__input_features = features
+        self.__target_feature = target
+        self.__causal_inc = causal_inc if causal_inc is not None else []
+        self.__greater_than = greater_than if greater_than is not None else []
+
+    @classmethod
+    def from_data(
+        cls,
+        X: DataLike,
+        y: OneDimData | None = None,
+        categ_map: dict[FeatureID, list[CategValue]] = {},
+        ordered: list[FeatureID] = [],
+        bounds_map: dict[FeatureID, tuple[int, int]] = {},
+        discrete: list[FeatureID] = [],
+        immutable: list[FeatureID] = [],
+        monotonicity: dict[FeatureID, Monotonicity] = {},
+        # TODO more general causality
+        causal_inc: list[tuple[FeatureID, FeatureID]] = [],
+        greater_than: list[tuple[FeatureID, FeatureID]] = [],
+        regression: bool = False,
+        feature_names: list[str] | None = None,
+        target_name: str | None = None,
+    ) -> DataHandler:
+        """
+        Construct a DataHandler instance.
+
+        Parameters:
+        -----------
+            X : array-like (2 dimensional)
+                Input features. Shape: (num_samples, num_features)
+            y : array-like (1 dimensional)
+                Target feature (e.g., labels or regression targets). Shape: (num_samples,)
+            categ : dictionary
+                Dictionary with indices (or column names for DataFrame) of categorical features as keys
+                and a list of unique categorical values as values.
+                
+                If the list is empty, each unique value of the feature is considered categorical
+                If the list is non-empty, but does not cover all values, the feature is considered mixed
+            regression : bool
+                True if the task is regression, False if y is categorical and task is classification.
+            feature_names : optional list of strings
+                List of feature names, if None it is recovered from column names if X is a DataFrame
+            target_name : optional string
+                Name of the target feature, if None it is recovered from X if X is a pandas Series
+        """
+        if isinstance(X, pd.DataFrame):
+            if feature_names is None:
+                feature_names = X.columns
+            if target_name is not None and y is None:
+                print("Taking target values from the X matrix")
+                y = X[target_name]
+                X = X.drop(columns=target_name)
+            X = X.to_numpy()
+
+        if y is not None:
+            if target_name is None:
+                if isinstance(y, pd.Series):
+                    target_name = y.name
+                else:
+                    target_name = "target"
+
+            if regression:
+                target_feature = Contiguous(y, target_name)
+            else:
+                if len(np.unique(y)) > 2:
+                    target_feature = Categorical(y, name=target_name)
+                else:
+                    target_feature = Binary(y, name=target_name)
+                    # TODO make the target values specifiable
+        else:
+            target_feature = None
+
+        n_features = X.shape[1]
+        if feature_names is None:
+            feature_names = [None] * n_features
+        if len(feature_names) != n_features:
+            raise ValueError("Incorrect length of list of feature names.")
+
+        input_features: list[Feature] = []
+        # stores lists of categorical values of applicable features, used for mapping to integer values
+        for feat_i, feat_name in enumerate(feature_names):
+            input_features.append(
+                make_feature(
+                    X[:, feat_i],
+                    feat_name,
+                    categ_map.get(feat_name, None),
+                    bounds_map.get(feat_name, None),
+                    feat_name in ordered,
+                    feat_name in discrete,
+                    monotone=monotonicity.get(feat_name, Monotonicity.NONE),
+                    modifiable=feat_name not in immutable,
+                )
+            )
+
+        causal_inc = [
+            (
+                input_features[feature_names.index(i)],
+                input_features[feature_names.index(j)],
+            )
+            for i, j in causal_inc
+        ]
+        greater_than = [
+            (
+                input_features[feature_names.index(i)],
+                input_features[feature_names.index(j)],
+            )
+            for i, j in greater_than
+        ]
+        return DataHandler(input_features, target_feature, causal_inc, greater_than)
+
+    @property
+    def causal_inc(self) -> list[tuple[Feature, Feature]]:
+        return self.__causal_inc
+
+    @property
+    def greater_than(self) -> list[tuple[Feature, Feature]]:
+        return self.__greater_than
+
+    @property
+    def n_features(self) -> int:
+        """Number of features in the input space"""
+        return len(self.__input_features)
+
+    @property
+    def features(self) -> list[Feature]:
+        """List of input features"""
+        return self.__input_features
+
+    @property
+    def target_feature(self) -> Feature:
+        """Target feature"""
+        return self.__target_feature
+
+    @property
+    def feature_names(self) -> list[str]:
+        """List of feature names"""
+        return [f.name for f in self.__input_features]
+
+    def encode(
+        self, X: DataLike, normalize: bool = True, one_hot: bool = True
+    ) -> np.ndarray[np.float64]:
+        """
+        Encode input features.
+
+        Parameters:
+        -----------
+        X : array-like
+            Input features (data matrix or DataFrame). Shape: (num_samples, num_features)
+        normalize : bool, optional
+            Whether to normalize the features (default is True).
+        one_hot : bool, optional
+            Whether to perform one-hot encoding for categorical values (default is True).
+
+        Returns:
+        --------
+        encoded_X : numpy array
+            Encoded input features. Shape: (num_samples, one_hot_features) when one hot encoding is performed, (num_samples, num_features) otherwise
+        """
+        if isinstance(X, pd.DataFrame):
+            X = X.to_numpy()
+        if isinstance(X, pd.Series):
+            X = X.to_numpy()
+
+        if len(X.shape) == 1:
+            Xmat = X.reshape(1, -1)
+            return self.encode(Xmat, normalize=normalize, one_hot=one_hot)[0]
+
+        enc = []
+        for feat_i, feature in enumerate(self.__input_features):
+            enc.append(
+                feature.encode(X[:, feat_i], normalize, one_hot).reshape(X.shape[0], -1)
+            )
+
+        return np.concatenate(enc, axis=1).astype(np.float64)
+
+    def encode_y(
+        self, y: OneDimData, normalize: bool = True, one_hot: bool = True
+    ) -> np.ndarray[np.float64]:
+        """
+        Encode target feature.
+
+        Parameters:
+        -----------
+        y : array-like
+            Target feature (data matrix or DataFrame of labels or regression targets). Shape: (num_samples,)
+        normalize : bool, optional
+            Whether to normalize the features (default is True).
+        one_hot : bool, optional
+            Whether to perform one-hot encoding for categorical values (default is True).
+
+        Returns:
+        --------
+        encoded_y : numpy array
+            Encoded target feature. Shape: (num_samples, num_values) for one hot encoding or (num_samples,) otherwise
+        """
+        return self.__target_feature.encode(y, normalize, one_hot)
+
+    def encode_all(self, X_all: np.ndarray, normalize: bool, one_hot: bool):
+        return np.concatenate(
+            [
+                self.encode(X_all[:, :-1], normalize, one_hot),
+                self.encode_y(X_all[:, -1], normalize, one_hot).reshape(-1, 1),
+            ],
+            axis=1,
+        )
+
+    def decode(
+        self,
+        X: np.ndarray[np.float64],
+        denormalize: bool = True,
+        encoded_one_hot: bool = True,
+        as_dataframe: bool = True,
+    ) -> np.ndarray[np.float64]:
+        """
+        Decode input features.
+
+        Parameters:
+        -----------
+        X : array-like
+            Input data matrix. Shape: (num_samples, num_enc_features)
+                where num_enc_features can be higher than num_features, because of one-hot encoding
+        denormalize : bool, optional
+            Whether to invert the normalization of the features (default is True).
+        encoded_one_hot : bool, optional
+            Whether the input matrix is one-hot encoded (default is True).
+        as_dataframe : bool, optional
+            Whether to return a pandas DataFrame or numpy array (default is True - DataFrame).
+
+        Returns:
+        --------
+        decoded_X : numpy array
+            Decoded features in the original format. Shape: (num_samples, num_features)
+        """
+        if X.shape[0] == 0:
+            if as_dataframe:
+                return pd.DataFrame([], columns=[f.name for f in self.__input_features])
+            return np.empty((0, self.n_features))
+        dec = []
+        curr_col = 0
+        for feature in self.__input_features:
+            w = feature.encoding_width(encoded_one_hot)
+            dec.append(
+                feature.decode(X[:, curr_col : curr_col + w], denormalize, as_dataframe)
+            )
+            curr_col += w
+        if as_dataframe:
+            return pd.concat(dec, axis=1)
+        return np.concatenate([x.reshape(X.shape[0], -1) for x in dec], axis=1)
+
+    def decode_y(
+        self,
+        y: np.ndarray[np.float64],
+        denormalize: bool = True,
+        as_series: bool = True,
+    ) -> np.ndarray[np.float64]:
+        """
+        Decode target feature.
+
+        Parameters:
+        -----------
+        y : array-like
+            Target feature data. Shape: (num_samples,) for general case
+                or (num_samples, num_categorical_values) in case of one-hot encoding
+        denormalize : bool, optional
+            Whether to invert the normalization of the feature (default is True).
+        as_series : bool, optional
+            Whether to return a pandas Series or numpy array (default is True - Series).
+
+        Returns:
+        --------
+        decoded_y : numpy array
+            Decoded target feature data. Shape: (num_samples,)
+        """
+        return self.__target_feature.decode(y, denormalize, as_series)
+
+    def encoding_width(self, one_hot: bool) -> int:
+        return sum([f.encoding_width(one_hot) for f in self.__input_features])
+
+    def allowed_changes(self, pre_vals, post_vals):
+        for f, pre, pos in zip(self.features, pre_vals, post_vals):
+            if not f.allowed_change(pre, pos):
+                return False
+
+        for cause, effect in self.__causal_inc:
+            cause_i = self.features.index(cause)
+            pre_cause = cause.encode(pre_vals[cause_i], normalize=False, one_hot=False)
+            pos_cause = cause.encode(post_vals[cause_i], normalize=False, one_hot=False)
+            if isinstance(cause, Categorical):
+                applied = pos_cause in cause.greater_than(pre_cause)
+            elif isinstance(cause, Contiguous):
+                applied = pos_cause > pre_cause
+            else:
+                raise ValueError("invalid feature type")
+            if applied:
+                effect_i = self.features.index(effect)
+                pre_effect = effect.encode(
+                    pre_vals[effect_i], normalize=False, one_hot=False
+                )
+                pos_effect = effect.encode(
+                    post_vals[effect_i], normalize=False, one_hot=False
+                )
+                if isinstance(effect, Categorical):
+                    if pos_effect not in effect.greater_than(pre_effect):
+                        return False
+                elif isinstance(effect, Contiguous):
+                    if pos_effect <= pre_effect:
+                        return False
+                else:
+                    raise ValueError("invalid feature type")
+
+        for greater, smaller in self.__greater_than:
+            if (
+                post_vals[self.features.index(smaller)]
+                > post_vals[self.features.index(greater)]
+            ):
+                return False
+        return True
+
+    # TODO dalsi nadstavba - datawrapper - ktera si bude pamatovat jestli se slo one-hot, normalizovalo atd

humancompatible/detect/data_handler/__init__.py

@@ -0,0 +1,3 @@
+from .DataHandler import DataHandler
+
+__all__ = ["DataHandler"]