Add NumPy support for group fairness metrics (#135)

Author: ruivieira

src/trustyai/metrics/fairness/group.py

@@ -2,21 +2,23 @@
 # pylint: disable = import-error
 from typing import List, Optional, Any, Union
 
+import numpy as np
 import pandas as pd
 from jpype import JInt
 from org.kie.trustyai.explainability.metrics import FairnessMetrics
 
 from trustyai.model import Value, PredictionProvider, Model
 from trustyai.utils.data_conversions import (
-    pandas_to_trusty,
     OneOutputUnionType,
     one_output_convert,
+    to_trusty_dataframe,
 )
 
 ColumSelector = Union[List[int], List[str]]
 
 
 def _column_selector_to_index(columns: ColumSelector, dataframe: pd.DataFrame):
+    """Returns a list of input and output indices, given an index size and output indices"""
     if len(columns) == 0:
         raise ValueError("Must specify at least one column")
 
@@ -27,32 +29,40 @@ def _column_selector_to_index(columns: ColumSelector, dataframe: pd.DataFrame):
 
 
 def statistical_parity_difference(
-    privileged: pd.DataFrame,
-    unprivileged: pd.DataFrame,
+    privileged: Union[pd.DataFrame, np.ndarray],
+    unprivileged: Union[pd.DataFrame, np.ndarray],
     favorable: OneOutputUnionType,
     outputs: Optional[List[int]] = None,
+    feature_names: Optional[List[str]] = None,
 ) -> float:
     """Calculate Statistical Parity Difference between privileged and unprivileged dataframes"""
     favorable_prediction_object = one_output_convert(favorable)
     return FairnessMetrics.groupStatisticalParityDifference(
-        pandas_to_trusty(privileged, outputs),
-        pandas_to_trusty(unprivileged, outputs),
+        to_trusty_dataframe(
+            data=privileged, outputs=outputs, feature_names=feature_names
+        ),
+        to_trusty_dataframe(
+            data=unprivileged, outputs=outputs, feature_names=feature_names
+        ),
         favorable_prediction_object.outputs,
     )
 
 
-# pylint: disable = line-too-long
+# pylint: disable = line-too-long, too-many-arguments
 def statistical_parity_difference_model(
-    samples: pd.DataFrame,
+    samples: Union[pd.DataFrame, np.ndarray],
     model: Union[PredictionProvider, Model],
     privilege_columns: ColumSelector,
     privilege_values: List[Any],
     favorable: OneOutputUnionType,
+    feature_names: Optional[List[str]] = None,
 ) -> float:
     """Calculate Statistical Parity Difference using a samples dataframe and a model"""
     favorable_prediction_object = one_output_convert(favorable)
     _privilege_values = [Value(v) for v in privilege_values]
-    _jsamples = pandas_to_trusty(samples, no_outputs=True)
+    _jsamples = to_trusty_dataframe(
+        data=samples, no_outputs=True, feature_names=feature_names
+    )
     return FairnessMetrics.groupStatisticalParityDifference(
         _jsamples,
         model,
@@ -63,32 +73,40 @@ def statistical_parity_difference_model(
 
 
 def disparate_impact_ratio(
-    privileged: pd.DataFrame,
-    unprivileged: pd.DataFrame,
+    privileged: Union[pd.DataFrame, np.ndarray],
+    unprivileged: Union[pd.DataFrame, np.ndarray],
     favorable: OneOutputUnionType,
     outputs: Optional[List[int]] = None,
+    feature_names: Optional[List[str]] = None,
 ) -> float:
     """Calculate Disparate Impact Ration between privileged and unprivileged dataframes"""
     favorable_prediction_object = one_output_convert(favorable)
     return FairnessMetrics.groupDisparateImpactRatio(
-        pandas_to_trusty(privileged, outputs),
-        pandas_to_trusty(unprivileged, outputs),
+        to_trusty_dataframe(
+            data=privileged, outputs=outputs, feature_names=feature_names
+        ),
+        to_trusty_dataframe(
+            data=unprivileged, outputs=outputs, feature_names=feature_names
+        ),
         favorable_prediction_object.outputs,
     )
 
 
 # pylint: disable = line-too-long
 def disparate_impact_ratio_model(
-    samples: pd.DataFrame,
+    samples: Union[pd.DataFrame, np.ndarray],
     model: Union[PredictionProvider, Model],
     privilege_columns: ColumSelector,
     privilege_values: List[Any],
     favorable: OneOutputUnionType,
+    feature_names: Optional[List[str]] = None,
 ) -> float:
     """Calculate Disparate Impact Ration using a samples dataframe and a model"""
     favorable_prediction_object = one_output_convert(favorable)
     _privilege_values = [Value(v) for v in privilege_values]
-    _jsamples = pandas_to_trusty(samples, no_outputs=True)
+    _jsamples = to_trusty_dataframe(
+        data=samples, no_outputs=True, feature_names=feature_names
+    )
     return FairnessMetrics.groupDisparateImpactRatio(
         _jsamples,
         model,
@@ -100,12 +118,13 @@ def disparate_impact_ratio_model(
 
 # pylint: disable = too-many-arguments
 def average_odds_difference(
-    test: pd.DataFrame,
-    truth: pd.DataFrame,
+    test: Union[pd.DataFrame, np.ndarray],
+    truth: Union[pd.DataFrame, np.ndarray],
     privilege_columns: ColumSelector,
     privilege_values: OneOutputUnionType,
     positive_class: List[Any],
     outputs: Optional[List[int]] = None,
+    feature_names: Optional[List[str]] = None,
 ) -> float:
     """Calculate Average Odds between two dataframes"""
     if test.shape != truth.shape:
@@ -117,23 +136,26 @@ def average_odds_difference(
     # determine privileged columns
     _privilege_columns = _column_selector_to_index(privilege_columns, test)
     return FairnessMetrics.groupAverageOddsDifference(
-        pandas_to_trusty(test, outputs),
-        pandas_to_trusty(truth, outputs),
+        to_trusty_dataframe(data=test, outputs=outputs, feature_names=feature_names),
+        to_trusty_dataframe(data=truth, outputs=outputs, feature_names=feature_names),
         _privilege_columns,
         _privilege_values,
         _positive_class,
     )
 
 
 def average_odds_difference_model(
-    samples: pd.DataFrame,
+    samples: Union[pd.DataFrame, np.ndarray],
     model: Union[PredictionProvider, Model],
     privilege_columns: ColumSelector,
     privilege_values: List[Any],
     positive_class: List[Any],
+    feature_names: Optional[List[str]] = None,
 ) -> float:
     """Calculate Average Odds for a sample dataframe using the provided model"""
-    _jsamples = pandas_to_trusty(samples, no_outputs=True)
+    _jsamples = to_trusty_dataframe(
+        data=samples, no_outputs=True, feature_names=feature_names
+    )
     _privilege_values = [Value(v) for v in privilege_values]
     _positive_class = [Value(v) for v in positive_class]
     # determine privileged columns
@@ -144,12 +166,13 @@ def average_odds_difference_model(
 
 
 def average_predictive_value_difference(
-    test: pd.DataFrame,
-    truth: pd.DataFrame,
+    test: Union[pd.DataFrame, np.ndarray],
+    truth: Union[pd.DataFrame, np.ndarray],
     privilege_columns: ColumSelector,
     privilege_values: List[Any],
     positive_class: List[Any],
     outputs: Optional[List[int]] = None,
+    feature_names: Optional[List[str]] = None,
 ) -> float:
     """Calculate Average Predictive Value Difference between two dataframes"""
     if test.shape != truth.shape:
@@ -160,8 +183,8 @@ def average_predictive_value_difference(
     _positive_class = [Value(v) for v in positive_class]
     _privilege_columns = _column_selector_to_index(privilege_columns, test)
     return FairnessMetrics.groupAveragePredictiveValueDifference(
-        pandas_to_trusty(test, outputs),
-        pandas_to_trusty(truth, outputs),
+        to_trusty_dataframe(data=test, outputs=outputs, feature_names=feature_names),
+        to_trusty_dataframe(data=truth, outputs=outputs, feature_names=feature_names),
         _privilege_columns,
         _privilege_values,
         _positive_class,
@@ -170,14 +193,14 @@ def average_predictive_value_difference(
 
 # pylint: disable = line-too-long
 def average_predictive_value_difference_model(
-    samples: pd.DataFrame,
+    samples: Union[pd.DataFrame, np.ndarray],
     model: Union[PredictionProvider, Model],
     privilege_columns: ColumSelector,
     privilege_values: List[Any],
     positive_class: List[Any],
 ) -> float:
     """Calculate Average Predictive Value Difference for a sample dataframe using the provided model"""
-    _jsamples = pandas_to_trusty(samples, no_outputs=True)
+    _jsamples = to_trusty_dataframe(samples, no_outputs=True)
     _privilege_values = [Value(v) for v in privilege_values]
     _positive_class = [Value(v) for v in positive_class]
     # determine privileged columns

src/trustyai/utils/data_conversions.py

@@ -2,7 +2,7 @@
 # pylint: disable = import-error, line-too-long, trailing-whitespace, unused-import, cyclic-import
 # pylint: disable = consider-using-f-string, invalid-name, wrong-import-order
 import warnings
-from typing import Union, List, Optional
+from typing import Union, List, Optional, Tuple
 from itertools import filterfalse
 
 import trustyai.model
@@ -442,8 +442,49 @@ def prediction_object_to_pandas(
     return df
 
 
-def pandas_to_trusty(
-    df: pd.DataFrame, outputs: Optional[List[int]] = None, no_outputs=False
+def __partition_column_indices(
+    size: int, outputs: Optional[List[int]] = None
+) -> Tuple[List[int], List[int]]:
+    indices = list(range(size))
+    if not outputs:  # If no output column supplied, assume the right-most
+        output_indices = [size - 1]
+        input_indices = list(filterfalse(output_indices.__contains__, indices))
+    else:
+        output_indices = outputs
+        input_indices = list(filterfalse(outputs.__contains__, indices))
+    return input_indices, output_indices
+
+
+def to_trusty_dataframe(
+    data: Union[pd.DataFrame, np.ndarray],
+    outputs: Optional[List[int]] = None,
+    no_outputs=False,
+    feature_names: Optional[List[str]] = None,
+) -> Dataframe:
+    """Convert Pandas dataframes or NumPy arrays into TrustyAI dataframes"""
+    if isinstance(data, pd.DataFrame):
+        return df_to_trusty_dataframe(
+            data=data,
+            outputs=outputs,
+            no_outputs=no_outputs,
+            feature_names=feature_names,
+        )
+    if isinstance(data, np.ndarray):
+        return numpy_to_trusty_dataframe(
+            arr=data,
+            outputs=outputs,
+            no_outputs=no_outputs,
+            feature_names=feature_names,
+        )
+
+    raise ValueError("Only Pandas dataframes and NumPy arrays supported at the moment.")
+
+
+def df_to_trusty_dataframe(
+    data: pd.DataFrame,
+    outputs: Optional[List[int]] = None,
+    no_outputs=False,
+    feature_names: Optional[List[str]] = None,
 ) -> Dataframe:
     """
     Converts a Pandas :class:`pandas.DataFrame` into a TrustyAI :class:`Dataframe`.
@@ -457,22 +498,74 @@ def pandas_to_trusty(
 
     no_outputs : bool
         Specify if the :class:`Dataframe` is inputs-only
+
+    feature_names : Optional[List[str]]
+        Optional list of feature names. If not provided, the Pandas dataframe column names will be used
     """
-    df = df.reset_index(drop=True)
-    n_columns = len(df.columns)
-    indices = list(range(n_columns))
+    data = data.reset_index(drop=True)
+    n_columns = len(data.columns)
     if not no_outputs:
-        if not outputs:  # If no output column supplied, assume the right-most
-            output_indices = [n_columns - 1]
-            input_indices = list(filterfalse(output_indices.__contains__, indices))
+
+        input_indices, output_indices = __partition_column_indices(n_columns, outputs)
+
+        if feature_names:
+            input_names = [feature_names[i] for i in input_indices]
+            output_names = [feature_names[i] for i in output_indices]
         else:
-            output_indices = outputs
-            input_indices = list(filterfalse(outputs.__contains__, indices))
+            input_names = None
+            output_names = None
+
+        pi = many_inputs_convert(
+            python_inputs=data.iloc[:, input_indices], feature_names=input_names
+        )
+        po = many_outputs_convert(
+            python_outputs=data.iloc[:, output_indices], names=output_names
+        )
+
+        return Dataframe.createFrom(pi, po)
+
+    pi = many_inputs_convert(data)
+    return Dataframe.createFromInputs(pi)
+
 
-        pi = many_inputs_convert(df.iloc[:, input_indices])
-        po = many_outputs_convert(df.iloc[:, output_indices])
+def numpy_to_trusty_dataframe(
+    arr: np.ndarray,
+    feature_names: List[str],
+    outputs: Optional[List[int]] = None,
+    no_outputs=False,
+) -> Dataframe:
+    """
+    Converts a NumPy :class:`np.ndarray` into a TrustyAI :class:`Dataframe`.
+    Either outputs can be provided as a list of column indices or `no_outputs` can be specified, for an inputs-only
+    :class:`Dataframe`.
+
+    Parameters
+    ----------
+    outputs : List[int]
+        Optional list of column indices to be marked as outputs
+
+    no_outputs : bool
+        Specify if the :class:`Dataframe` is inputs-only
+
+    feature_names : Optional[List[str]]
+        Optional list of feature names. If not provided, the Pandas dataframe column names will be used
+    """
+    n_columns = arr.shape[1]
+    if not no_outputs:
+        input_indices, output_indices = __partition_column_indices(n_columns, outputs)
+
+        input_names = [feature_names[i] for i in input_indices]
+        output_names = [feature_names[i] for i in output_indices]
+        axis = 1
+
+        pi = many_inputs_convert(
+            python_inputs=np.take(arr, input_indices, axis), feature_names=input_names
+        )
+        po = many_outputs_convert(
+            python_outputs=np.take(arr, output_indices, axis), names=output_names
+        )
 
         return Dataframe.createFrom(pi, po)
 
-    pi = many_inputs_convert(df)
+    pi = many_inputs_convert(arr)
     return Dataframe.createFromInputs(pi)

tests/general/common.py

@@ -2,6 +2,8 @@
 """Common methods and models for tests"""
 import os
 import sys
+from typing import Optional, List
+
 import numpy as np
 import pandas as pd  # pylint: disable=unused-import
 
@@ -21,3 +23,20 @@ def mock_feature(value, name='f-num'):
 def sum_skip_model(inputs: np.ndarray) -> np.ndarray:
     """SumSkip test model"""
     return np.sum(inputs[:, [i for i in range(inputs.shape[1]) if i != 5]], 1)
+
+
+def create_random_dataframe(weights: Optional[List[float]] = None):
+    """Create a simple random Pandas dataframe"""
+    from sklearn.datasets import make_classification
+    if not weights:
+        weights = [0.9, 0.1]
+
+    X, y = make_classification(n_samples=5000, n_features=2, n_informative=2, n_redundant=0, n_repeated=0, n_classes=2,
+                               n_clusters_per_class=2, class_sep=2, flip_y=0, weights=weights,
+                               random_state=23)
+
+    return pd.DataFrame({
+        'x1': X[:, 0],
+        'x2': X[:, 1],
+        'y': y
+    })