FEAT export InterpolatedThresholder as a public object and update its API (e.g., rename an argument)

CHANGES.md

@@ -5,6 +5,9 @@
 * Relaxed checks made on `X` in `_validate_and_reformat_input()` since that
   is the concern of the underlying estimator and not Fairlearn
 * Add support for Python 3.9
+* Make `InterpolatedThresholder` more visible by directly including it in
+  `fairlearn.postprocessing` and rename its `interpolation_dict` argument
+  to `threshold_interpolation`.
 
 ### v0.7.0
 

fairlearn/postprocessing/__init__.py

@@ -7,10 +7,12 @@
 learn how to adjust the predictor's output from the training data.
 """
 
+from ._interpolated_thresholder import InterpolatedThresholder  # noqa: F401
 from ._threshold_optimizer import ThresholdOptimizer  # noqa: F401
 from ._plotting import plot_threshold_optimizer  # noqa: F401
 
 __all__ = [
-    "ThresholdOptimizer",
-    "plot_threshold_optimizer"
+    "InterpolatedThresholder",
+    "plot_threshold_optimizer",
+    "ThresholdOptimizer"
 ]

fairlearn/postprocessing/_interpolated_thresholder.py

@@ -21,14 +21,13 @@ class InterpolatedThresholder(BaseEstimator, MetaEstimatorMixin):
 
     At prediction time, the predictor takes as input both standard and sensitive features.
     Based on the values of sensitive features, it then applies a randomized thresholding
-    transformation according to the provided `interpolation_dict`.
+    transformation according to the provided `threshold_interpolation`.
 
     Parameters
     ----------
     estimator :
         base estimator
-
-    interpolation_dict : dict
+    threshold_interpolation : dict
         maps sensitive feature values to `Bunch` that describes the
         interpolation transformation via the following fields:
 
@@ -78,10 +77,10 @@ class InterpolatedThresholder(BaseEstimator, MetaEstimatorMixin):
        [Online]. Available: https://arxiv.org/abs/1610.02413.
     """
 
-    def __init__(self, estimator, interpolation_dict, prefit=False,
+    def __init__(self, estimator, threshold_interpolation, prefit=False,
                  predict_method='deprecated'):
         self.estimator = estimator
-        self.interpolation_dict = interpolation_dict
+        self.threshold_interpolation = threshold_interpolation
         self.prefit = prefit
         self.predict_method = predict_method
 
@@ -141,7 +140,7 @@ def _pmf_predict(self, X, *, sensitive_features):
             enforce_binary_labels=False)
 
         positive_probs = 0.0*base_predictions_vector
-        for a, interpolation in self.interpolation_dict.items():
+        for a, interpolation in self.threshold_interpolation.items():
             interpolated_predictions = \
                 interpolation.p0 * interpolation.operation0(base_predictions_vector) + \
                 interpolation.p1 * interpolation.operation1(base_predictions_vector)

fairlearn/postprocessing/_threshold_optimizer.py

@@ -459,12 +459,12 @@ def _threshold_optimization_for_simple_constraints(
 
         # Create the solution as interpolation of multiple points with a separate
         # interpolation per sensitive feature value.
-        interpolation_dict = {}
+        threshold_interpolation = {}
         for sensitive_feature_value in self._tradeoff_curve.keys():
             best_interpolation = self._tradeoff_curve[
                 sensitive_feature_value
             ].transpose()[i_best]
-            interpolation_dict[sensitive_feature_value] = Bunch(
+            threshold_interpolation[sensitive_feature_value] = Bunch(
                 p0=best_interpolation.p0,
                 operation0=best_interpolation.operation0,
                 p1=best_interpolation.p1,
@@ -484,7 +484,7 @@ def _threshold_optimization_for_simple_constraints(
 
         return InterpolatedThresholder(
             self.estimator_,
-            interpolation_dict,
+            threshold_interpolation,
             prefit=True,
             predict_method=self._predict_method,
         ).fit(None, None)
@@ -578,7 +578,7 @@ def _threshold_optimization_for_equalized_odds(
 
         # create the solution as interpolation of multiple points with a separate
         # interpolation per sensitive feature
-        interpolation_dict = {}
+        threshold_interpolation = {}
         for sensitive_feature_value in self._tradeoff_curve.keys():
             roc_result = self._tradeoff_curve[
                 sensitive_feature_value
@@ -599,7 +599,7 @@ def _threshold_optimization_for_equalized_odds(
                     / vertical_distance_from_diagonal
                 )
 
-            interpolation_dict[sensitive_feature_value] = Bunch(
+            threshold_interpolation[sensitive_feature_value] = Bunch(
                 p_ignore=p_ignore,
                 prediction_constant=self._x_best,
                 p0=roc_result.p0,
@@ -621,7 +621,7 @@ def _threshold_optimization_for_equalized_odds(
 
         return InterpolatedThresholder(
             self.estimator_,
-            interpolation_dict,
+            threshold_interpolation,
             prefit=True,
             predict_method=self._predict_method,
         ).fit(None, None)

test/unit/postprocessing/test_threshold_optimization.py

@@ -648,7 +648,7 @@ def test_constraints_objective_pairs(constraints, objective):
         assert str(error_info.value).startswith(expected)
     else:
         thr_optimizer.fit(X, y, sensitive_features=sf)
-        res = thr_optimizer.interpolated_thresholder_.interpolation_dict
+        res = thr_optimizer.interpolated_thresholder_.threshold_interpolation
         for key in [0, 1]:
             assert res[key]['p0'] == pytest.approx(expected[key]['p0'], PREC)
             assert res[key]['operation0']._operator == expected[key]['op0']

test/unit/postprocessing/test_threshold_optimizer_multiple_sensitive_features.py

@@ -117,11 +117,11 @@ def test_threshold_optimizer_multiple_sensitive_features():
             metricframe_multi.by_group.loc[(a2, a4)]).all()
 
     # comparing string representations of interpolation dicts is sufficient
-    assert str(postprocess_est_combined.interpolated_thresholder_.interpolation_dict[a1+a3]) == \
-        str(postprocess_est_multi.interpolated_thresholder_.interpolation_dict[a13])
-    assert str(postprocess_est_combined.interpolated_thresholder_.interpolation_dict[a1+a4]) == \
-        str(postprocess_est_multi.interpolated_thresholder_.interpolation_dict[a14])
-    assert str(postprocess_est_combined.interpolated_thresholder_.interpolation_dict[a2+a3]) == \
-        str(postprocess_est_multi.interpolated_thresholder_.interpolation_dict[a23])
-    assert str(postprocess_est_combined.interpolated_thresholder_.interpolation_dict[a2+a4]) == \
-        str(postprocess_est_multi.interpolated_thresholder_.interpolation_dict[a24])
+    combined_interpolation = \
+        postprocess_est_combined.interpolated_thresholder_.threshold_interpolation
+    multi_interpolation = \
+        postprocess_est_multi.interpolated_thresholder_.threshold_interpolation
+    assert str(combined_interpolation[a1+a3]) == str(multi_interpolation[a13])
+    assert str(combined_interpolation[a1+a4]) == str(multi_interpolation[a14])
+    assert str(combined_interpolation[a2+a3]) == str(multi_interpolation[a23])
+    assert str(combined_interpolation[a2+a4]) == str(multi_interpolation[a24])