empulse 0.4.2__tar.gz → 0.4.4__tar.gz

{empulse-0.4.2 → empulse-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: empulse
-Version: 0.4.2
+Version: 0.4.4
 Summary: Value-driven and cost-sensitive tools for scikit-learn
 Author-email: Shimanto Rahman <shimanto.rahman@ugent.be>
 License: MIT License
@@ -146,6 +146,7 @@ Provides-Extra: dev
 Requires-Dist: empulse[docs,test]; extra == "dev"
 Requires-Dist: twine>=4.0.2; extra == "dev"
 
+[![PyPI Downloads](https://static.pepy.tech/badge/empulse)](https://pepy.tech/projects/empulse)
 [![Python Version](https://img.shields.io/pypi/v/empulse)](https://pypi.org/project/empulse/)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ShimantoRahman/empulse)
 ![](https://img.shields.io/pypi/pyversions/empulse)

{empulse-0.4.2 → empulse-0.4.4}/README.md

@@ -1,3 +1,4 @@
+[![PyPI Downloads](https://static.pepy.tech/badge/empulse)](https://pepy.tech/projects/empulse)
 [![Python Version](https://img.shields.io/pypi/v/empulse)](https://pypi.org/project/empulse/)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ShimantoRahman/empulse)
 ![](https://img.shields.io/pypi/pyversions/empulse)

empulse-0.4.4/empulse/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.4"

{empulse-0.4.2 → empulse-0.4.4}/empulse/metrics/churn/cost.py

@@ -136,6 +136,9 @@ def mpc_cost_score(
     Only a fraction of churners accepts the incentive offer.
     For detailed information, consult the paper [1]_.
 
+    .. seealso::
+        :class:`~empulse.models.B2BoostClassifier` : Uses the instance-specific cost function as objective function.
+
     Parameters
     ----------
 
@@ -190,9 +193,6 @@ def mpc_cost_score(
         clf.fit(X_train, y_train)
         y_pred = clf.predict(X_test)
 
-    .. seealso::
-        :class:`~empulse.models.B2BoostClassifier` : Uses the instance-specific cost function as objective function.
-
     References
     ----------
     .. [1] Janssens, B., Bogaert, M., Bagué, A., & Van den Poel, D. (2022).

{empulse-0.4.2 → empulse-0.4.4}/empulse/metrics/emp.py

@@ -22,6 +22,11 @@ def emp_score(
     """
     :func:`~empulse.metrics.emp()` but only returning the EMP score
 
+    .. seealso::
+        :func:`~empulse.metrics.emp` : To also return the threshold at which the EMP score is achieved.
+
+        :func:`~empulse.metrics.mp_score` : For a deterministic version of the EMP score.
+
     Parameters
     ----------
     y_true : 1D array-like, shape=(n_samples,)
@@ -164,6 +169,11 @@ def emp(
     """
     Expected Maximum Profit Measure (EMP)
 
+    .. seealso::
+        :func:`~empulse.metrics.emp_score` : To only return the EMP score.
+
+        :func:`~empulse.metrics.mp` : For a deterministic version of the EMP.
+
     Parameters
     ----------
     y_true : 1D array-like, shape=(n_samples,)
@@ -230,14 +240,10 @@ def emp(
     Returns
     -------
     emp : float
-        Expected Maximum Profit
+        Expected Maximum Profit.
 
     threshold : float
-        Threshold at which the expected maximum profit is achieved
-
-    .. seealso::
-        :func:`~empulse.metrics.emp_score` : Convenience function around :func:`~empulse.metrics.emp()`
-        only returning EMP score
+        Threshold at which the expected maximum profit is achieved.
 
     Notes
     -----

{empulse-0.4.2 → empulse-0.4.4}/empulse/metrics/mp.py

@@ -16,6 +16,11 @@ def mp_score(
     """
     :func:`~empulse.metrics.mp()` but only returning the MP score
 
+    .. seealso::
+        :func:`~empulse.metrics.mp` : To also return the threshold at which the maximum profit is achieved.
+
+        :func:`~empulse.metrics.emp` : For a stochastic version of the maximum profit.
+
     Parameters
     ----------
     y_true : 1D array-like, shape=(n_samples,)
@@ -93,6 +98,11 @@ def mp(
     """
     Maximum Profit Measure (MP)
 
+    .. seealso::
+        :func:`~empulse.metrics.mp_score` : To only return the maximum profit score.
+
+        :func:`~empulse.metrics.emp` : For a stochastic version of the maximum profit.
+
     Parameters
     ----------
     y_true : 1D array-like, shape=(n_samples,)

{empulse-0.4.2 → empulse-0.4.4}/empulse/metrics/savings.py

@@ -95,21 +95,6 @@ def cost_loss(
     the cost of a false negative (not detecting a fraudulent transaction) is higher than
     the cost of a false positive (flagging a non-fraudulent transaction as fraudulent).
 
-    The cost of each instance :math:`C_i` is calculated as [3]_:
-
-    .. math:: C_i = y_i \\cdot (\\hat y_i \\cdot C_i(1|1) + (1 - \\hat y_i) \\cdot C_i(0|1)) + (1 - \\hat y_i) \\cdot (\\hat y_i \\cdot C_i(1|0) + (1 - \\hat y_i) \\cdot C_i(0|0))
-
-    where
-
-        - :math:`y_i` is the true label,
-        - :math:`\\hat y_i` is the predicted label,
-        - :math:`C_i(1|1)` is the cost of a true positive ``tp_cost``,
-        - :math:`C_i(0|1)` is the cost of a false positive ``fp_cost``,
-        - :math:`C_i(1|0)` is the cost of a false negative ``fn_cost``, and
-        - :math:`C_i(0|0)` is the cost of a true negative ``tn_cost``.
-
-    Code modified from `costcla.metrics.cost_loss`.
-
     .. seealso::
 
         :func:`~empulse.metrics.expected_cost_loss` : Expected cost of a classifier.
@@ -160,6 +145,23 @@ def cost_loss(
     cost_loss : float
         Cost of a classifier.
 
+    Notes
+    -----
+    The cost of each instance :math:`C_i` is calculated as [3]_:
+
+    .. math:: C_i = y_i \\cdot (\\hat y_i \\cdot C_i(1|1) + (1 - \\hat y_i) \\cdot C_i(0|1)) + (1 - \\hat y_i) \\cdot (\\hat y_i \\cdot C_i(1|0) + (1 - \\hat y_i) \\cdot C_i(0|0))
+
+    where
+
+        - :math:`y_i` is the true label,
+        - :math:`\\hat y_i` is the predicted label,
+        - :math:`C_i(1|1)` is the cost of a true positive ``tp_cost``,
+        - :math:`C_i(0|1)` is the cost of a false positive ``fp_cost``,
+        - :math:`C_i(1|0)` is the cost of a false negative ``fn_cost``, and
+        - :math:`C_i(0|0)` is the cost of a true negative ``tn_cost``.
+
+    Code modified from `costcla.metrics.cost_loss`.
+
     References
     ----------
     .. [1] C. Elkan, "The foundations of Cost-Sensitive Learning",
@@ -225,21 +227,6 @@ def expected_cost_loss(
     the cost of a false negative (not detecting a fraudulent transaction) is higher than
     the cost of a false positive (flagging a non-fraudulent transaction as fraudulent).
 
-    The expected cost of each instance :math:`\\mathbb{E}[C_i]` is calculated as [3]_:
-
-    .. math:: \\mathbb{E}[C_i] = y_i \\cdot (s_i \\cdot C_i(1|1) + (1 - s_i) \\cdot C_i(0|1)) + (1 - s_i) \\cdot (s_i \\cdot C_i(1|0) + (1 - s_i) \\cdot C_i(0|0))
-
-    where
-
-    - :math:`y_i` is the true label,
-    - :math:`s_i` is the predicted probability,
-    - :math:`C_i(1|1)` is the cost of a true positive ``tp_cost``,
-    - :math:`C_i(0|1)` is the cost of a false positive ``fp_cost``,
-    - :math:`C_i(1|0)` is the cost of a false negative ``fn_cost``, and
-    - :math:`C_i(0|0)` is the cost of a true negative ``tn_cost``.
-
-    Code modified from `costcla.metrics.cost_loss`.
-
     .. seealso::
 
         :func:`~empulse.metrics.cost_loss` : Cost of a classifier.
@@ -283,6 +270,23 @@ def expected_cost_loss(
     cost_loss : float
         Cost of a classifier.
 
+    Notes
+    -----
+    The expected cost of each instance :math:`\\mathbb{E}[C_i]` is calculated as [3]_:
+
+    .. math:: \\mathbb{E}[C_i] = y_i \\cdot (s_i \\cdot C_i(1|1) + (1 - s_i) \\cdot C_i(0|1)) + (1 - s_i) \\cdot (s_i \\cdot C_i(1|0) + (1 - s_i) \\cdot C_i(0|0))
+
+    where
+
+    - :math:`y_i` is the true label,
+    - :math:`s_i` is the predicted probability,
+    - :math:`C_i(1|1)` is the cost of a true positive ``tp_cost``,
+    - :math:`C_i(0|1)` is the cost of a false positive ``fp_cost``,
+    - :math:`C_i(1|0)` is the cost of a false negative ``fn_cost``, and
+    - :math:`C_i(0|0)` is the cost of a true negative ``tn_cost``.
+
+    Code modified from `costcla.metrics.cost_loss`.
+
     References
     ----------
     .. [1] C. Elkan, "The foundations of Cost-Sensitive Learning",
@@ -341,22 +345,6 @@ def expected_log_cost_loss(
     the cost of a false negative (not detecting a fraudulent transaction) is higher than
     the cost of a false positive (flagging a non-fraudulent transaction as fraudulent).
 
-    The expected log cost of each instance :math:`\\mathbb{E}[C^l_i]` is calculated as [3]_:
-
-    .. math:: \\mathbb{E}[C^l_i] = y_i \\cdot (\\log(s_i) \\cdot C_i(1|1) + \\log(1 - s_i) \\cdot C_i(0|1)) + (1 - s_i) \\cdot (\\log(s_i) \\cdot C_i(1|0) + \\log(1 - s_i) \\cdot C_i(0|0))
-
-    where
-
-    - :math:`y_i` is the true label,
-    - :math:`s_i` is the predicted probability,
-    - :math:`C_i(1|1)` is the cost of a true positive ``tp_cost``,
-    - :math:`C_i(0|1)` is the cost of a false positive ``fp_cost``,
-    - :math:`C_i(1|0)` is the cost of a false negative ``fn_cost``, and
-    - :math:`C_i(0|0)` is the cost of a true negative ``tn_cost``.
-
-    When ``tp_cost`` and ``tn_cost`` equal -1, and `fp_cost`` and ``tn_cost`` equal 0,
-    the expected log cost is equivalent to the log loss :func:`sklearn:sklearn.metrics.log_loss`.
-
     .. seealso::
 
         :func:`~empulse.metrics.expected_cost_loss` : Expected cost of a classifier.
@@ -396,6 +384,37 @@ def expected_log_cost_loss(
     -------
     log_expected_cost : float
         Log expected cost.
+
+    Notes
+    -----
+    The expected log cost of each instance :math:`\\mathbb{E}[C^l_i]` is calculated as:
+
+    .. math:: \\mathbb{E}[C^l_i] = y_i \\cdot (\\log(s_i) \\cdot C_i(1|1) + \\log(1 - s_i) \\cdot C_i(0|1)) + (1 - s_i) \\cdot (\\log(s_i) \\cdot C_i(1|0) + \\log(1 - s_i) \\cdot C_i(0|0))
+
+    where
+
+    - :math:`y_i` is the true label,
+    - :math:`s_i` is the predicted probability,
+    - :math:`C_i(1|1)` is the cost of a true positive ``tp_cost``,
+    - :math:`C_i(0|1)` is the cost of a false positive ``fp_cost``,
+    - :math:`C_i(1|0)` is the cost of a false negative ``fn_cost``, and
+    - :math:`C_i(0|0)` is the cost of a true negative ``tn_cost``.
+
+    When ``tp_cost`` and ``tn_cost`` equal -1, and `fp_cost`` and ``tn_cost`` equal 0,
+    the expected log cost is equivalent to the log loss :func:`sklearn:sklearn.metrics.log_loss`.
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+        import numpy as np
+        from empulse.metrics import expected_log_cost_loss
+        y_pred = [0.1, 0.9, 0.8, 0.2]
+        y_true = [0, 1, 1, 0]
+        fp_cost = np.array([4, 1, 2, 2])
+        fn_cost = np.array([1, 3, 3, 1])
+        expected_log_cost_loss(y_true, y_pred, fp_cost=fp_cost, fn_cost=fn_cost)
     """
     y_true, y_pred, tp_cost, fp_cost, tn_cost, fn_cost = _validate_input(
         y_true, y_pred, tp_cost, fp_cost, tn_cost, fn_cost, check_input
@@ -417,18 +436,18 @@ def savings_score(
         check_input: bool = True,
 ) -> float:
     """
-    Cost savings of a classifier compared to using no algorithm at all.
+    Cost savings of a classifier compared to using a naive algorithm.
 
-    This function calculates the savings cost of using y_pred on y_true with a
-    cost-matrix, as the difference of y_pred and the cost_loss of a naive
-    classification model.
+    The cost savings of a classifiers is the cost the classifier saved over a naive classification model
+    (predicting all ones or zeros whichever is better).
+    With 1 being the perfect model, 0 being not better than the naive model.
 
     Modified from `costcla.metrics.savings_score`.
 
     .. seealso::
 
         :func:`~empulse.metrics.expected_savings_score` : Expected savings of a classifier
-        compared to using no algorithm at all.
+        compared to using a naive algorithm.
 
         :func:`~empulse.metrics.cost_loss` : Cost of a classifier.
 
@@ -477,7 +496,40 @@ def savings_score(
     score : float
         Cost savings of a classifier compared to using no algorithm at all.
 
-        The best performance is 1.
+    Notes
+    -----
+    The cost of each instance :math:`C_i` is calculated as [1]_:
+
+    .. math:: C_i(s_i) = y_i \\cdot (\\hat y_i \\cdot C_i(1|1) + (1 - \\hat y_i) \\cdot C_i(0|1)) + (1 - \\hat y_i) \\cdot (\\hat y_i \\cdot C_i(1|0) + (1 - \\hat y_i) \\cdot C_i(0|0))
+
+    The savings over a naive model is calculated as:
+
+    .. math::  \\text{Savings} = 1 - \\frac{\\sum_{i=1}^N C_i(s_i)}{\\min(\\sum_{i=1}^N C_i(0), \\sum_{i=1}^N C_i(1))}
+
+    where
+
+        - :math:`y_i` is the true label,
+        - :math:`\\hat y_i` is the predicted label,
+        - :math:`C_i(1|1)` is the cost of a true positive ``tp_cost``,
+        - :math:`C_i(0|1)` is the cost of a false positive ``fp_cost``,
+        - :math:`C_i(1|0)` is the cost of a false negative ``fn_cost``, and
+        - :math:`C_i(0|0)` is the cost of a true negative ``tn_cost``.
+        - :math:`N` is the number of samples.
+
+    Code modified from `costcla.metrics.cost_loss`.
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+        import numpy as np
+        from empulse.metrics import savings_score
+        y_pred = [0, 1, 0, 0]
+        y_true = [0, 1, 1, 0]
+        fp_cost = np.array([4, 1, 2, 2])
+        fn_cost = np.array([1, 3, 3, 1])
+        savings_score(y_true, y_pred, fp_cost=fp_cost, fn_cost=fn_cost)
 
     References
     ----------
@@ -489,21 +541,6 @@ def savings_score(
     .. [2] Höppner, S., Baesens, B., Verbeke, W., & Verdonck, T. (2022).
            Instance-dependent cost-sensitive learning for detecting transfer fraud.
            European Journal of Operational Research, 297(1), 291-300.
-
-    See also
-    --------
-    cost_loss
-
-    Examples
-    --------
-    >>> import numpy as np
-    >>> from empulse.metrics import savings_score
-    >>> y_pred = [0, 1, 0, 0]
-    >>> y_true = [0, 1, 1, 0]
-    >>> fp_cost = np.array([4, 1, 2, 2])
-    >>> fn_cost = np.array([1, 3, 3, 1])
-    >>> savings_score(y_true, y_pred, fp_cost=fp_cost, fn_cost=fn_cost)
-    0.5
     """
 
     y_true, y_pred, tp_cost, fp_cost, tn_cost, fn_cost = _validate_input(
@@ -534,15 +571,15 @@ def expected_savings_score(
         check_input: bool = True,
 ) -> float:
     """
-    Expected savings of a classifier compared to using no algorithm at all.
+    Expected savings of a classifier compared to using a naive algorithm.
 
-    This function calculates the expected savings cost of using y_pred on y_true with a
-    cost-matrix, as the difference of y_pred and the cost_loss of a naive
-    classification model.
+    The expected cost savings of a classifiers is the expected cost the classifier saved
+    over a naive classification model (predicting all ones or zeros whichever is better).
+    With 1 being the perfect model, 0 being not better than the naive model.
 
     .. seealso::
 
-        :func:`~empulse.metrics.savings_score` : Cost savings of a classifier compared to using no algorithm at all.
+        :func:`~empulse.metrics.savings_score` : Cost savings of a classifier compared to using a naive algorithm.
 
         :func:`~empulse.metrics.expected_cost_loss` : Expected cost of a classifier.
 
@@ -578,29 +615,44 @@ def expected_savings_score(
     score : float
         Expected savings of a classifier compared to using no algorithm at all.
 
-        The best performance is 1.
+        Notes
+    -----
+    The expected cost of each instance :math:`\\mathbb{E}[C_i]` is calculated as [2]_:
 
-    References
-    ----------
+    .. math:: \\mathbb{E}[C_i(s_i)] = y_i \\cdot (s_i \\cdot C_i(1|1) + (1 - s_i) \\cdot C_i(0|1)) + (1 - s_i) \\cdot (s_i \\cdot C_i(1|0) + (1 - s_i) \\cdot C_i(0|0))
 
-    .. [1] Höppner, S., Baesens, B., Verbeke, W., & Verdonck, T. (2022).
-           Instance-dependent cost-sensitive learning for detecting transfer fraud.
-           European Journal of Operational Research, 297(1), 291-300.
+    The expected savings over a naive model is calculated as:
 
-    See also
-    --------
-    savings_score
+    .. math::  \\text{Expected Savings} = 1 - \\frac{\\sum_{i=1}^N \\mathbb{E}[C_i(s_i)]}{\\min(\\sum_{i=1}^N C_i(0), \\sum_{i=1}^N C_i(1))}
+
+    where
+
+        - :math:`y_i` is the true label,
+        - :math:`\\hat y_i` is the predicted label,
+        - :math:`C_i(1|1)` is the cost of a true positive ``tp_cost``,
+        - :math:`C_i(0|1)` is the cost of a false positive ``fp_cost``,
+        - :math:`C_i(1|0)` is the cost of a false negative ``fn_cost``, and
+        - :math:`C_i(0|0)` is the cost of a true negative ``tn_cost``.
+        - :math:`N` is the number of samples.
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from empulse.metrics import expected_savings_score
-    >>> y_pred = [0.4, 0.8, 0.75, 0.1]
-    >>> y_true = [0, 1, 1, 0]
-    >>> fp_cost = np.array([4, 1, 2, 2])
-    >>> fn_cost = np.array([1, 3, 3, 1])
-    >>> expected_savings_score(y_true, y_pred, fp_cost=fp_cost, fn_cost=fn_cost)
-    0.475
+
+    .. code-block:: python
+
+        import numpy as np
+        from empulse.metrics import expected_savings_score
+        y_pred = [0.4, 0.8, 0.75, 0.1]
+        y_true = [0, 1, 1, 0]
+        fp_cost = np.array([4, 1, 2, 2])
+        fn_cost = np.array([1, 3, 3, 1])
+        expected_savings_score(y_true, y_pred, fp_cost=fp_cost, fn_cost=fn_cost)
+
+    References
+    ----------
+    .. [1] Höppner, S., Baesens, B., Verbeke, W., & Verdonck, T. (2022).
+           Instance-dependent cost-sensitive learning for detecting transfer fraud.
+           European Journal of Operational Research, 297(1), 291-300.
     """
     y_true, y_pred, tp_cost, fp_cost, tn_cost, fn_cost = _validate_input(
         y_true, y_pred, tp_cost, fp_cost, tn_cost, fn_cost, check_input
@@ -675,11 +727,14 @@ def make_objective_aec(
 
         import xgboost as xgb
         from empulse.metrics import make_objective_aec
+        from sklearn.datasets import make_classification
+
+        X, y = make_classification()
+        objective = make_objective_aec('xgboost', fp_cost=1, fn_cost=1)
 
-        objective = make_objective_aec()
         clf = xgb.XGBClassifier(objective=objective, n_estimators=100, max_depth=3)
-        clf.fit(X_train, y_train)
-        y_pred = clf.predict(X_test)
+        clf.fit(X, y)
+        y_pred = clf.predict(X)
 
     References
     ----------
@@ -692,8 +747,15 @@ def make_objective_aec(
         objective = partial(_objective_xgboost, tp_cost=tp_cost, tn_cost=tn_cost, fn_cost=fn_cost, fp_cost=fp_cost)
         update_wrapper(objective, _objective_xgboost)
     elif model == 'lightgbm':
-        objective = partial(_objective_lightgbm, tp_cost=tp_cost, tn_cost=tn_cost, fn_cost=fn_cost, fp_cost=fp_cost)
-        update_wrapper(objective, _objective_lightgbm)
+        def objective(y_pred, train_data):
+            return _objective_lightgbm(
+                y_pred,
+                train_data,
+                tp_cost=tp_cost,
+                tn_cost=tn_cost,
+                fn_cost=fn_cost,
+                fp_cost=fp_cost
+            )
     elif model == 'catboost':
         objective = partial(_objective_catboost, tp_cost=tp_cost, tn_cost=tn_cost, fn_cost=fn_cost, fp_cost=fp_cost)
         update_wrapper(objective, _objective_catboost)
@@ -793,7 +855,18 @@ def _objective_lightgbm(
         fn_cost=0.0,
         fp_cost=0.0,
 ) -> tuple[np.ndarray, np.ndarray]:
-    raise NotImplementedError("Objective function for LightGBM is not implemented yet.")
+    if hasattr(train_data, 'get_label'):
+        y_true = train_data.get_label()
+    elif isinstance(train_data, np.ndarray):
+        y_true = train_data
+    else:
+        raise TypeError(f"Invalid train data type, got {type(train_data)}.")
+
+    y_pred = expit(y_pred)
+    cost = y_true * (tp_cost - fn_cost) + (1 - y_true) * (fp_cost - tn_cost)
+    gradient = y_pred * (1 - y_pred) * cost
+    hessian = np.abs((1 - 2 * y_pred) * gradient)
+    return gradient, hessian
 
 
 def _objective_catboost(

{empulse-0.4.2 → empulse-0.4.4}/empulse/models/bias_mitigation/bias_relabeling.py

@@ -20,18 +20,18 @@ class BiasRelabelingClassifier(ClassifierMixin, BaseEstimator):
         Base estimator which is used for fitting and predicting.
     strategy : {'statistical parity', 'demographic parity'} or Callable, default='statistical parity'
         Determines how the group weights are computed.
-        Group weights determine how many instances to relabel for each combination of target and protected attribute.
+        Group weights determine how many instances to relabel for each combination of target and sensitive feature.
 
         - ``'statistical_parity'`` or ``'demographic parity'``: \
-        probability of positive predictions are equal between subgroups of protected attribute.
+        probability of positive predictions are equal between subgroups of sensitive feature.
 
-        - ``Callable``: function which computes the group weights based on the target and protected attribute. \
-        Callable accepts two arguments: y_true and protected_attr and returns the group weights. \
+        - ``Callable``: function which computes the group weights based on the target and sensitive feature. \
+        Callable accepts two arguments: y_true and sensitive_feature and returns the group weights. \
         Group weights are a 2x2 matrix where the rows represent the target variable and the columns represent the \
-        protected attribute. \
-        The element at position (i, j) is the weight for the pair (y_true == i, protected_attr == j).
-    transform_attr : Optional[Callable], default=None
-        Function which transforms protected attribute before resampling the training data.
+        sensitive feature. \
+        The element at position (i, j) is the weight for the pair (y_true == i, sensitive_feature == j).
+    transform_feature : Optional[Callable], default=None
+        Function which transforms sensitive feature before resampling the training data.
 
     Attributes
     ----------
@@ -55,7 +55,7 @@ class BiasRelabelingClassifier(ClassifierMixin, BaseEstimator):
         high_clv = np.random.randint(0, 2, size=X.shape[0])
 
         model = BiasRelabelingClassifier(estimator=LogisticRegression())
-        model.fit(X, y, protected_attr=high_clv)
+        model.fit(X, y, sensitive_feature=high_clv)
 
     2. Converting a continuous attribute to a binary attribute:
 
@@ -70,9 +70,9 @@ class BiasRelabelingClassifier(ClassifierMixin, BaseEstimator):
 
         model = BiasRelabelingClassifier(
             estimator=LogisticRegression(),
-            transform_attr=lambda clv: (clv > np.quantile(clv, 0.8)).astype(int)
+            transform_feature=lambda clv: (clv > np.quantile(clv, 0.8)).astype(int)
         )
-        model.fit(X, y, protected_attr=clv)
+        model.fit(X, y, sensitive_feature=clv)
 
     3. Using a custom strategy function:
 
@@ -85,8 +85,8 @@ class BiasRelabelingClassifier(ClassifierMixin, BaseEstimator):
         X, y = make_classification()
         high_clv = np.random.randint(0, 2, size=X.shape[0])
 
-        # Simple strategy to double the weight for the protected attribute
-        def strategy(y_true, protected_attr):
+        # Simple strategy to double the weight for the sensitive feature
+        def strategy(y_true, sensitive_feature):
             return np.array([
                 [1, 2],
                 [1, 2]
@@ -96,9 +96,9 @@ class BiasRelabelingClassifier(ClassifierMixin, BaseEstimator):
             estimator=LogisticRegression(),
             strategy=strategy
         )
-        model.fit(X, y, protected_attr=high_clv)
+        model.fit(X, y, sensitive_feature=high_clv)
 
-    4. Passing the protected attribute in a cross-validation grid search:
+    4. Passing the sensitive feature in a cross-validation grid search:
 
     .. code-block:: python
 
@@ -120,9 +120,9 @@ class BiasRelabelingClassifier(ClassifierMixin, BaseEstimator):
                 ('model', BiasRelabelingClassifier(LogisticRegression()))
             ])
             search = GridSearchCV(pipeline, param_grid)
-            search.fit(X, y, model__protected_attr=high_clv)
+            search.fit(X, y, model__sensitive_feature=high_clv)
 
-    5. Passing the protected attribute through metadata routing in a cross-validation grid search:
+    5. Passing the sensitive feature through metadata routing in a cross-validation grid search:
 
     .. code-block:: python
 
@@ -141,24 +141,29 @@ class BiasRelabelingClassifier(ClassifierMixin, BaseEstimator):
             param_grid = {'model__estimator__C': [0.1, 1, 10]}
             pipeline = Pipeline([
                 ('scaler', StandardScaler()),
-                ('model', BiasRelabelingClassifier(LogisticRegression()).set_fit_request(protected_attr=True))
+                ('model', BiasRelabelingClassifier(LogisticRegression()).set_fit_request(sensitive_feature=True))
             ])
             search = GridSearchCV(pipeline, param_grid)
-            search.fit(X, y, protected_attr=high_clv)
-    """
+            search.fit(X, y, sensitive_feature=high_clv)
+
+    References
+    ----------
 
-    __metadata_request__fit = {'protected_attr': True}
+    .. [1] Rahman, S., Janssens, B., & Bogaert, M. (2025).
+           Profit-driven pre-processing in B2B customer churn modeling using fairness techniques.
+           Journal of Business Research, 189, 115159. doi:10.1016/j.jbusres.2024.115159
+    """
 
     def __init__(
             self,
             estimator,
             *,
             strategy: Union[StrategyFn, Strategy] = 'statistical parity',
-            transform_attr: Optional[Callable[[np.ndarray], np.ndarray]] = None
+            transform_feature: Optional[Callable[[np.ndarray], np.ndarray]] = None
     ):
         self.estimator = estimator
         self.strategy = strategy
-        self.transform_attr = transform_attr
+        self.transform_feature = transform_feature
 
     def __sklearn_tags__(self):
         tags = super().__sklearn_tags__()
@@ -171,7 +176,7 @@ class BiasRelabelingClassifier(ClassifierMixin, BaseEstimator):
             X: ArrayLike,
             y: ArrayLike,
             *,
-            protected_attr: Optional[ArrayLike] = None,
+            sensitive_feature: Optional[ArrayLike] = None,
             **fit_params
     ) -> 'BiasRelabelingClassifier':
         """
@@ -183,8 +188,8 @@ class BiasRelabelingClassifier(ClassifierMixin, BaseEstimator):
             Training data.
         y : 1D array-like, shape=(n_samples,)
             Target values.
-        protected_attr : 1D array-like, shape=(n_samples,), default = None
-            Protected attribute used to determine the sample group weights.
+        sensitive_feature : 1D array-like, shape=(n_samples,), default = None
+            Sensitive feature used to determine the sample group weights.
         fit_params : dict
             Additional parameters passed to the estimator's `fit` method.
 
@@ -202,18 +207,18 @@ class BiasRelabelingClassifier(ClassifierMixin, BaseEstimator):
         self.classes_ = np.unique(y)
         if len(self.classes_) == 1:
             raise ValueError("Classifier can't train when only one class is present.")
-        if protected_attr is None:
+        if sensitive_feature is None:
             self.estimator_ = clone(self.estimator)
             self.estimator_.fit(X, y, **fit_params)
             return self
-        protected_attr = np.asarray(protected_attr)
+        sensitive_feature = np.asarray(sensitive_feature)
 
         sampler = BiasRelabler(
             estimator=self.estimator,
             strategy=self.strategy,
-            transform_attr=self.transform_attr
+            transform_feature=self.transform_feature
         )
-        X, y = sampler.fit_resample(X, y, sensitive_feature=protected_attr)
+        X, y = sampler.fit_resample(X, y, sensitive_feature=sensitive_feature)
         self.estimator_ = clone(self.estimator)
         self.estimator_.fit(X, y, **fit_params)