FAI-903: Add group fairness Python bindings (#129)

Add group fairness Python bindings.

* Add group statistical parity difference
* Add Disparate Impact Ratio (DIR)
* Add average odds difference
* Add Average Predictive Value Difference
* Add column selectors
* Add SPD for when providing models
* Add model-based DIR metric
* Update dev requirements
* Add model-based AOD
* Add model-based APVD
* Add biased and unbiased synthetic income dataset
* Update tests
* Change to binary serialised model

* Downgrade XGBoost version for CI compatibility
* Fix linting and formatting
* Fix test files relative paths

Author: ruivieira

requirements-dev.txt

@@ -1,15 +1,15 @@
-JPype1==1.3.0
-black==21.6b0
+JPype1==1.4.1
+black==22.10.0
 click==8.0.4
 joblib==1.2.0
 jupyter==1.0.0
 scikit-learn==0.24.2
-pylint==2.15.6
-pytest==6.2.4
-setuptools
-wheel
-xgboost==1.4.2
-twine==3.4.2
+pylint==2.15.7
+pytest==7.2.0
+setuptools==65.6.3
+wheel==0.38.4
+xgboost==1.6.2
+twine==4.0.2
 pyarrow==7.0.0
 numpydoc
 matplotlib==3.5.1

scripts/local.sh

@@ -0,0 +1,176 @@
+"""Group fairness metrics"""
+# pylint: disable = import-error
+from typing import List, Optional, Any, Union
+
+import pandas as pd
+from jpype import JInt
+from org.kie.trustyai.explainability.metrics import FairnessMetrics
+
+from trustyai.model import Output, Value, PredictionProvider, Model
+from trustyai.utils.data_conversions import pandas_to_trusty
+
+ColumSelector = Union[List[int], List[str]]
+
+
+def _column_selector_to_index(columns: ColumSelector, dataframe: pd.DataFrame):
+    if isinstance(columns[0], str):  # passing column
+        columns = dataframe.columns.get_indexer(columns)
+    indices = [JInt(c) for c in columns]  # Java casting
+    return indices
+
+
+def statistical_parity_difference(
+    privileged: pd.DataFrame,
+    unprivileged: pd.DataFrame,
+    favorable: List[Output],
+    outputs: Optional[List[int]] = None,
+) -> float:
+    """Calculate Statistical Parity Difference between privileged and unprivileged dataframes"""
+    return FairnessMetrics.groupStatisticalParityDifference(
+        pandas_to_trusty(privileged, outputs),
+        pandas_to_trusty(unprivileged, outputs),
+        favorable,
+    )
+
+
+# pylint: disable = line-too-long
+def statistical_parity_difference_model(
+    samples: pd.DataFrame,
+    model: Union[PredictionProvider, Model],
+    privilege_columns: ColumSelector,
+    privilege_values: List[Any],
+    favorable: List[Output],
+) -> float:
+    """Calculate Statistical Parity Difference using a samples dataframe and a model"""
+    _privilege_values = [Value(v) for v in privilege_values]
+    _jsamples = pandas_to_trusty(samples, no_outputs=True)
+    return FairnessMetrics.groupStatisticalParityDifference(
+        _jsamples,
+        model,
+        _column_selector_to_index(privilege_columns, samples),
+        _privilege_values,
+        favorable,
+    )
+
+
+def disparate_impact_ratio(
+    privileged: pd.DataFrame,
+    unprivileged: pd.DataFrame,
+    favorable: List[Output],
+    outputs: Optional[List[int]] = None,
+) -> float:
+    """Calculate Disparate Impact Ration between privileged and unprivileged dataframes"""
+    return FairnessMetrics.groupDisparateImpactRatio(
+        pandas_to_trusty(privileged, outputs),
+        pandas_to_trusty(unprivileged, outputs),
+        favorable,
+    )
+
+
+# pylint: disable = line-too-long
+def disparate_impact_ratio_model(
+    samples: pd.DataFrame,
+    model: Union[PredictionProvider, Model],
+    privilege_columns: ColumSelector,
+    privilege_values: List[Any],
+    favorable: List[Output],
+) -> float:
+    """Calculate Disparate Impact Ration using a samples dataframe and a model"""
+    _privilege_values = [Value(v) for v in privilege_values]
+    _jsamples = pandas_to_trusty(samples, no_outputs=True)
+    return FairnessMetrics.groupDisparateImpactRatio(
+        _jsamples,
+        model,
+        _column_selector_to_index(privilege_columns, samples),
+        _privilege_values,
+        favorable,
+    )
+
+
+# pylint: disable = too-many-arguments
+def average_odds_difference(
+    test: pd.DataFrame,
+    truth: pd.DataFrame,
+    privilege_columns: ColumSelector,
+    privilege_values: List[Any],
+    positive_class: List[Any],
+    outputs: Optional[List[int]] = None,
+) -> float:
+    """Calculate Average Odds between two dataframes"""
+    if test.shape != truth.shape:
+        raise ValueError(
+            f"Dataframes have different shapes ({test.shape} and {truth.shape})"
+        )
+    _privilege_values = [Value(v) for v in privilege_values]
+    _positive_class = [Value(v) for v in positive_class]
+    # 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),
+        _privilege_columns,
+        _privilege_values,
+        _positive_class,
+    )
+
+
+def average_odds_difference_model(
+    samples: pd.DataFrame,
+    model: Union[PredictionProvider, Model],
+    privilege_columns: ColumSelector,
+    privilege_values: List[Any],
+    positive_class: List[Any],
+) -> float:
+    """Calculate Average Odds for a sample dataframe using the provided model"""
+    _jsamples = pandas_to_trusty(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
+    _privilege_columns = _column_selector_to_index(privilege_columns, samples)
+    return FairnessMetrics.groupAverageOddsDifference(
+        _jsamples, model, _privilege_columns, _privilege_values, _positive_class
+    )
+
+
+def average_predictive_value_difference(
+    test: pd.DataFrame,
+    truth: pd.DataFrame,
+    privilege_columns: ColumSelector,
+    privilege_values: List[Any],
+    positive_class: List[Any],
+    outputs: Optional[List[int]] = None,
+) -> float:
+    """Calculate Average Predictive Value Difference between two dataframes"""
+    if test.shape != truth.shape:
+        raise ValueError(
+            f"Dataframes have different shapes ({test.shape} and {truth.shape})"
+        )
+    _privilege_values = [Value(v) for v in privilege_values]
+    _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),
+        _privilege_columns,
+        _privilege_values,
+        _positive_class,
+    )
+
+
+# pylint: disable = line-too-long
+def average_predictive_value_difference_model(
+    samples: pd.DataFrame,
+    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)
+    _privilege_values = [Value(v) for v in privilege_values]
+    _positive_class = [Value(v) for v in positive_class]
+    # determine privileged columns
+    _privilege_columns = _column_selector_to_index(privilege_columns, samples)
+    return FairnessMetrics.groupAveragePredictiveValueDifference(
+        _jsamples, model, _privilege_columns, _privilege_values, _positive_class
+    )

src/trustyai/metrics/fairness/__init__.py

@@ -8,7 +8,7 @@
 
 from org.kie.trustyai.explainability.model import (
     PredictionInput,
-    PredictionInputsDataDistribution
+    PredictionInputsDataDistribution,
 )
 from org.kie.trustyai.explainability.local import LocalExplainer
 
@@ -20,9 +20,13 @@
 from . import ExplainabilityMetrics
 
 
-def impact_score(model: PredictionProvider, pred_input: PredictionInput,
-                 explainer: Union[LimeExplainer, SHAPExplainer],
-                 k: int, is_model_callable: bool = False):
+def impact_score(
+    model: PredictionProvider,
+    pred_input: PredictionInput,
+    explainer: Union[LimeExplainer, SHAPExplainer],
+    k: int,
+    is_model_callable: bool = False,
+):
     """
     Parameters
     ----------
@@ -53,8 +57,13 @@ def impact_score(model: PredictionProvider, pred_input: PredictionInput,
     return ExplainabilityMetrics.impactScore(model, pred, top_k_features)
 
 
-def mean_impact_score(explainer: Union[LimeExplainer, SHAPExplainer],
-                      model: PredictionProvider, data: list, is_model_callable=False, k=2):
+def mean_impact_score(
+    explainer: Union[LimeExplainer, SHAPExplainer],
+    model: PredictionProvider,
+    data: list,
+    is_model_callable=False,
+    k=2,
+):
     """
     Parameters
     ----------
@@ -76,13 +85,18 @@ def mean_impact_score(explainer: Union[LimeExplainer, SHAPExplainer],
     """
     m_is = 0
     for features in data:
-        m_is += impact_score(model, features, explainer, k, is_model_callable=is_model_callable)
+        m_is += impact_score(
+            model, features, explainer, k, is_model_callable=is_model_callable
+        )
     return m_is / len(data)
 
 
-def classification_fidelity(explainer: Union[LimeExplainer, SHAPExplainer],
-                            model: PredictionProvider, inputs: list,
-                            is_model_callable: bool = False):
+def classification_fidelity(
+    explainer: Union[LimeExplainer, SHAPExplainer],
+    model: PredictionProvider,
+    inputs: list,
+    is_model_callable: bool = False,
+):
     """
     Parameters
     ----------
@@ -111,11 +125,16 @@ def classification_fidelity(explainer: Union[LimeExplainer, SHAPExplainer],
         pairs.append(_Pair.of(saliency, simple_prediction(c_input, output)))
     return ExplainabilityMetrics.classificationFidelity(pairs)
 
+
 # pylint: disable = too-many-arguments
-def local_saliency_f1(output_name: str, model: PredictionProvider,
-                      explainer: Union[LimeExplainer, SHAPExplainer],
-                      distribution: PredictionInputsDataDistribution, k: int,
-                      chunk_size: int):
+def local_saliency_f1(
+    output_name: str,
+    model: PredictionProvider,
+    explainer: Union[LimeExplainer, SHAPExplainer],
+    distribution: PredictionInputsDataDistribution,
+    k: int,
+    chunk_size: int,
+):
     """
     Parameters
     ----------
@@ -143,5 +162,6 @@ def local_saliency_f1(output_name: str, model: PredictionProvider,
         local_explainer = JObject(explainer._explainer, LocalExplainer)
     else:
         local_explainer = explainer
-    return ExplainabilityMetrics.getLocalSaliencyF1(output_name, model, local_explainer,
-                                                    distribution, k, chunk_size)
+    return ExplainabilityMetrics.getLocalSaliencyF1(
+        output_name, model, local_explainer, distribution, k, chunk_size
+    )

src/trustyai/metrics/fairness/group.py

@@ -2,11 +2,13 @@
 # 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
+from typing import Union, List, Optional
+from itertools import filterfalse
 
 import trustyai.model
 from trustyai.model.domain import feature_domain
 from org.kie.trustyai.explainability.model import (
+    Dataframe,
     Feature,
     Output,
     PredictionInput,
@@ -417,3 +419,39 @@ def prediction_object_to_pandas(
             ]
         )
     return df
+
+
+def pandas_to_trusty(
+    df: pd.DataFrame, outputs: Optional[List[int]] = None, no_outputs=False
+) -> Dataframe:
+    """
+    Converts a Pandas :class:`pandas.DataFrame` 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
+    """
+    df = df.reset_index(drop=True)
+    n_columns = len(df.columns)
+    indices = list(range(n_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))
+        else:
+            output_indices = outputs
+            input_indices = list(filterfalse(outputs.__contains__, indices))
+
+        pi = many_inputs_convert(df.iloc[:, input_indices])
+        po = many_outputs_convert(df.iloc[:, output_indices])
+
+        return Dataframe.createFrom(pi, po)
+
+    pi = many_inputs_convert(df)
+    return Dataframe.createFromInputs(pi)