From e2f388e633ddbd0c2d1671abf809bb273fe24d48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Mu=C3=B1oz?= Date: Wed, 24 Jul 2024 07:25:59 -0300 Subject: [PATCH 1/2] docs: improve docstring and remove old dependenceis (#169) * docs: improve docstring and remove old dependenceis * chore: hatch format --- .../getting_started/bias/mitigation.rst | 5 +- .../explainability/metrics/stability.rst | 95 +++++++------------ docs/source/reference/bias/plots.rst | 6 +- .../reference/explainability/metrics.rst | 4 +- docs/source/utils/xai_image_plots.py | 15 ++- .../metrics/global_importance/_alpha_score.py | 6 +- .../global_importance/_importance_spread.py | 20 ++-- .../global_importance/_position_parity.py | 40 ++++---- .../global_importance/_rank_alignment.py | 42 +++++--- .../global_importance/_xai_ease_score.py | 3 +- .../metrics/local_importance/_stability.py | 4 + .../plots/_feature_importance.py | 2 +- src/holisticai/explainability/plots/_tree.py | 2 +- 13 files changed, 119 insertions(+), 125 deletions(-) diff --git a/docs/source/getting_started/bias/mitigation.rst b/docs/source/getting_started/bias/mitigation.rst index df972941..bcac69cf 100644 --- a/docs/source/getting_started/bias/mitigation.rst +++ b/docs/source/getting_started/bias/mitigation.rst @@ -1,7 +1,10 @@ - Mitigation ========== +.. warning:: + + This page is currently under construction. Please check back later for updates. + .. contents:: **Contents:** :depth: 2 diff --git a/docs/source/getting_started/explainability/metrics/stability.rst b/docs/source/getting_started/explainability/metrics/stability.rst index 5f29a6c3..565bcc4c 100644 --- a/docs/source/getting_started/explainability/metrics/stability.rst +++ b/docs/source/getting_started/explainability/metrics/stability.rst @@ -1,3 +1,5 @@ +.. default-role:: math + Stability Metrics ================= @@ -8,106 +10,73 @@ The Data Stability and Feature Stability metrics are designed to evaluate the co :depth: 1 Data Stability --------------- - -Data Stability measures the consistency of feature importance across different instances in the dataset. A high data stability score indicates that the importance of features remains relatively stable across various data points, enhancing interpretability and reliability. +---------------------- Methodology ~~~~~~~~~~~ - -1. **Compute Feature Importance for Each Instance:** - - Calculate the feature importance for each instance in the dataset. - -2. **Calculate Median and Interquartile Range (IQR) for Each Instance:** - - Compute the median feature importance for each instance. - - Compute the interquartile range (IQR) for each instance, defined as the difference between the 75th percentile (Q3) and the 25th percentile (Q1) of feature importance values. - -3. **Calculate Normalized Interquartile Range (nIQR) for Each Instance:** - - Normalize the IQR by dividing it by the median feature importance for each instance. - -4. **Compute Data Stability Score:** - - Aggregate the normalized IQR values across all instances to compute the Data Stability Score. A lower normalized IQR indicates higher stability. +The **Data Stability** metric evaluates the consistency of local feature importances across different instances. It measures how much the importances of features vary for different instances in a dataset. Mathematical Representation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Let \( F_i \) denote the feature importance vector for instance \( i \). The median and IQR for instance \( i \) are given by: - -.. math:: - - \text{Median}_i = \text{median}(F_i) - - \text{IQR}_i = Q3(F_i) - Q1(F_i) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Let :math:`\mathbf{I} = \{I_1, I_2, \ldots, I_n\}` be the set of local feature importances for \( n \) instances, where each \( I_i \) is a vector of feature importances. -The normalized IQR (nIQR) for instance \( i \) is: +1. **Calculation of Spread Divergence:** .. math:: - \text{nIQR}_i = \frac{\text{IQR}_i}{\text{Median}_i} + S_i = \text{spread_divergence}(I_i) -The Data Stability Score \( \lambda_D \) is the mean of the nIQR values: +2. **Calculation of Data Stability:** .. math:: - \lambda_D = \frac{1}{N} \sum_{i=1}^{N} \text{nIQR}_i - -where \( N \) is the number of instances. + \text{Data_Stability} = \text{spread_divergence}(\{S_i \mid i = 1, \ldots, n\}) Interpretation -~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~ +- **High value:** Indicates that the feature importances are consistent across instances. This suggests that the model has a uniform understanding of the data, facilitating interpretation and increasing confidence in the model's explanations. +- **Low value:** Indicates that the feature importances vary significantly between instances. This can make the model harder to interpret and reduce confidence in its predictions. -- **High Score:** Indicates that the importance of features is consistent across different instances, making the model more interpretable and reliable. -- **Low Score:** Indicates that the importance of features varies significantly across different instances, making the model less interpretable and potentially less reliable. +The **Data Stability** metric uses spread divergence to evaluate the stability of feature importances. This divergence measures the dispersion of importances across different instances, providing a quantitative measure of consistency. Feature Stability ----------------- -Feature Stability measures the consistency of feature importance across different features in the dataset. A high feature stability score indicates that the importance of features remains relatively stable across various data points, enhancing interpretability and reliability. - Methodology -~~~~~~~~~~~ - -1. **Compute Feature Importance for Each Feature:** - - Calculate the feature importance for each feature across all instances in the dataset. - -2. **Calculate Median and Interquartile Range (IQR) for Each Feature:** - - Compute the median feature importance for each feature. - - Compute the interquartile range (IQR) for each feature, defined as the difference between the 75th percentile (Q3) and the 25th percentile (Q1) of feature importance values. - -3. **Calculate Normalized Interquartile Range (nIQR) for Each Feature:** - - Normalize the IQR by dividing it by the median feature importance for each feature. - -4. **Compute Feature Stability Score:** - - Aggregate the normalized IQR values across all features to compute the Feature Stability Score. A lower normalized IQR indicates higher stability. +~~~~~~~~~~~~ +The **Feature Stability** metric measures the stability of individual feature importances across different instances. It focuses on the consistency of the importance of a specific feature throughout the dataset. Mathematical Representation ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Let :math:`\mathbf{I} = \{I_1, I_2, \ldots, I_n\}` be the set of local feature importances for \( n \) instances, where each \( I_i \) is a vector of feature importances. -Let \( F_j \) denote the feature importance vector for feature \( j \). The median and IQR for feature \( j \) are given by: +1. **Normalization and Transposition of Data:** .. math:: - \text{Median}_j = \text{median}(F_j) + \mathbf{I}^T = \begin{pmatrix} + I_{1,1} & I_{1,2} & \cdots & I_{1,n} \\ + I_{2,1} & I_{2,2} & \cdots & I_{2,n} \\ + \vdots & \vdots & \ddots & \vdots \\ + I_{m,1} & I_{m,2} & \cdots & I_{m,n} + \end{pmatrix} - \text{IQR}_j = Q3(F_j) - Q1(F_j) - -The normalized IQR (nIQR) for feature \( j \) is: +2. **Calculation of Spread Divergence for Each Feature:** .. math:: - \text{nIQR}_j = \frac{\text{IQR}_j}{\text{Median}_j} + S_j = \text{spread_divergence}(I_j^T) -The Feature Stability Score \( \lambda_F \) is the mean of the nIQR values: +3. **Calculation of Feature Stability:** .. math:: - \lambda_F = \frac{1}{M} \sum_{j=1}^{M} \text{nIQR}_j - -where \( M \) is the number of features. + \text{Feature_Stability} = \text{spread_divergence}(\{S_j \mid j = 1, \ldots, m\}) Interpretation -~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~ +- **High value:** Indicates that the importance of a specific feature is consistent across instances. This suggests that the feature is robust and its relationship with the model's target is reliable. +- **Low value:** Indicates that the importance of a feature varies significantly between instances. This may suggest that the feature is less reliable and its relationship with the model's target may be weak. -- **High Score:** Indicates that the importance of features is consistent across different features, making the model more interpretable and reliable. -- **Low Score:** Indicates that the importance of features varies significantly across different features, making the model less interpretable and potentially less reliable. \ No newline at end of file +The **Feature Stability** metric uses spread divergence to evaluate the stability of individual feature importances. This divergence measures the dispersion of the importances of each feature across different instances, providing a quantitative measure of their consistency. diff --git a/docs/source/reference/bias/plots.rst b/docs/source/reference/bias/plots.rst index 0acf569f..67af973e 100644 --- a/docs/source/reference/bias/plots.rst +++ b/docs/source/reference/bias/plots.rst @@ -1,7 +1,7 @@ -=============== -Bias Plots -=============== +===== +Plots +===== `holisticai.bias.plots` implements the visualizations for **bias** tasks. diff --git a/docs/source/reference/explainability/metrics.rst b/docs/source/reference/explainability/metrics.rst index 72663831..54b1c24d 100644 --- a/docs/source/reference/explainability/metrics.rst +++ b/docs/source/reference/explainability/metrics.rst @@ -1,5 +1,5 @@ -Explainability Metrics -====================== +Metrics +======= `holisticai.explainability.metrics` is a python module measuring *bias* in algorithms. Metrics are included for *classification*, *regression*, *clustering*, *recommender* and *multiclass* tasks. diff --git a/docs/source/utils/xai_image_plots.py b/docs/source/utils/xai_image_plots.py index b4301c26..c62d78ed 100644 --- a/docs/source/utils/xai_image_plots.py +++ b/docs/source/utils/xai_image_plots.py @@ -1,7 +1,7 @@ import numpy as np import matplotlib.pyplot as plt from holisticai.explainability.plots import plot_partial_dependence,plot_feature_importance -from holisticai.explainability.commons import PartialDependence, Importances +from holisticai.utils import PartialDependence, Importances static_image_folder = '_static/images' def image_plot_partial_dependence(): @@ -15,8 +15,8 @@ def image_plot_partial_dependence(): ]) ranked_feature_importance = Importances(values=[0.123], feature_names=["Feature 1"]) - fig = plot_partial_dependence(partial_dependence, ranked_feature_importance) - fig.savefig(f"{static_image_folder}/xai_plot_partial_dependence.png") + plot_partial_dependence(partial_dependence, ranked_feature_importance) + plt.savefig(f"{static_image_folder}/xai_plot_partial_dependence.png") def image_plot_feature_importance(): feature_importance = Importances(values=np.array([0.1, 0.2, 0.3, 0.4]), feature_names=['A', 'B', 'C', 'D']) @@ -27,7 +27,7 @@ def image_plot_feature_importance(): def image_plot_surrogate(): from holisticai.explainability.plots import plot_surrogate - from holisticai.explainability.commons import Importances + from holisticai.utils import Importances from holisticai.datasets import load_dataset from sklearn.tree import DecisionTreeClassifier import matplotlib.pyplot as plt @@ -37,9 +37,6 @@ def image_plot_surrogate(): surrogate.fit(ds['X'], ds['y']) importance = Importances(values=surrogate.feature_importances_, feature_names=ds['X'].columns, extra_attrs={'surrogate': surrogate}) - fig,ax = plt.subplots(1,1) + fig,ax = plt.subplots(1,1, figsize=(20, 10)) plot_surrogate(importance, ax) - fig.savefig(f"{static_image_folder}/xai_plot_surrogate.png") - - - + fig.savefig(f"{static_image_folder}/xai_plot_surrogate.png") \ No newline at end of file diff --git a/src/holisticai/explainability/metrics/global_importance/_alpha_score.py b/src/holisticai/explainability/metrics/global_importance/_alpha_score.py index b1c7e129..d61812b8 100644 --- a/src/holisticai/explainability/metrics/global_importance/_alpha_score.py +++ b/src/holisticai/explainability/metrics/global_importance/_alpha_score.py @@ -56,7 +56,7 @@ def __call__(self, feature_importances: Importances): def alpha_score(feature_importance: Importances, alpha: float = 0.8): """ - Calculates the alpha importance score using the given feature importance and ranked feature importance. + Alpha Score calculates the proportion of features that account for the alpha percentage of the overall feature importance. Parameters ---------- @@ -70,13 +70,13 @@ def alpha_score(feature_importance: Importances, alpha: float = 0.8): Returns ------- float - The alpha importance score. + The alpha importance score Examples -------- >>> from holisticai.explainability.commons import Importance >>> from holisticai.explainability.metrics import alpha_score - >>> values = np.array([0.10, 0.20, 0.30]) + >>> values = np.array([0.50, 0.30, 0.20]) >>> feature_names = ["feature_1", "feature_2", "feature_3"] >>> feature_importance = Importance(values=values, feature_names=feature_names) >>> alpha_score(feature_importance) diff --git a/src/holisticai/explainability/metrics/global_importance/_importance_spread.py b/src/holisticai/explainability/metrics/global_importance/_importance_spread.py index ce2f9bb6..dffc5e67 100644 --- a/src/holisticai/explainability/metrics/global_importance/_importance_spread.py +++ b/src/holisticai/explainability/metrics/global_importance/_importance_spread.py @@ -47,6 +47,7 @@ def spread_ratio(feature_importance: Importances): Calculates the spread ratio of the given feature importance. The spread ratio measures the degree of evenness or concentration in the distribution of feature importance values. A higher spread ratio indicates a more evenly distributed feature importance, while a lower spread ratio indicates a more concentrated feature importance. + A lower ratio concentrates the importances and facilitates interpretability. Parameters ---------- @@ -58,8 +59,9 @@ def spread_ratio(feature_importance: Importances): float: The spread ratio of the feature importance. - Exemplo - ------- + Examples + -------- + >>> from holisticai.explainability.commons import Importances >>> from holisticai.explainability.metrics.global_importance import spread_ratio >>> values = np.array([0.10, 0.20, 0.30]) @@ -75,11 +77,13 @@ def spread_ratio(feature_importance: Importances): def spread_divergence(feature_importance: Importances): """ - Calculates the spread divergence metric for a given feature importance. + Calculates the spread divergence metric based on the inverse of the Jensen-Shannon distance + (square root of the Jensen-Shannon divergence), for a given feature importance. + A lower ratio concentrates the importances and facilitates interpretability. Parameters ---------- - - feature_importance: Importances + feature_importance: Importances The feature importance values for the features. Returns @@ -88,13 +92,15 @@ def spread_divergence(feature_importance: Importances): Example ------- + >>> from holisticai.explainability.commons import Importances >>> from holisticai.explainability.metrics.global_importance import ( ... spread_divergence, ... ) - >>> values = np.array([0.10, 0.20, 0.30]) - >>> feature_names = ["feature_1", "feature_2", "feature_3"] - >>> feature_importance = Importances(values=values, feature_names=feature_names) + >>> feature_importance = Importances( + ... values=np.array([0.10, 0.20, 0.30]), + ... feature_names=["feature_1", "feature_2", "feature_3"], + ... ) >>> score = spread_divergence(feature_importance) 0.8196393599933761 diff --git a/src/holisticai/explainability/metrics/global_importance/_position_parity.py b/src/holisticai/explainability/metrics/global_importance/_position_parity.py index 5ce8abdc..02f67134 100644 --- a/src/holisticai/explainability/metrics/global_importance/_position_parity.py +++ b/src/holisticai/explainability/metrics/global_importance/_position_parity.py @@ -27,10 +27,10 @@ def position_parity(conditional_feature_importance: ConditionalImportance, ranke Parameters ---------- - conditional_feature_importance: ConditionalFeatureImportance - A list of conditional feature importance values. + conditional_feature_importance: ConditionalImportance + The feature importance for each output label (classification) or output region (regression). ranked_feature_importance: Importances - A list of ranked feature importance values. + The ranked feature importance values. Returns ------- @@ -41,25 +41,27 @@ def position_parity(conditional_feature_importance: ConditionalImportance, ranke -------- >>> import numpy as np >>> from holisticai.explainability.commons import ( - ... ConditionalFeatureImportance, + ... ConditionalImportance, ... Importances, ... ) >>> from holisticai.explainability.metrics import position_parity - >>> values = np.array([0.50, 0.40, 0.10]) - >>> feature_names = ["feature_1", "feature_2", "feature_3"] - >>> feature_importance = Importances(values=values, feature_names=feature_names) - >>> values = { - ... "group1": Importances( - ... values=np.array([0.40, 0.35, 0.25]), - ... feature_names=["feature_1", "feature_2", "feature_3"], - ... ), - ... "group2": Importances( - ... values=np.array([0.50, 0.30, 0.20]), - ... feature_names=["feature_3", "feature_2", "feature_1"], - ... ), - ... } - >>> conditional_feature_importance = ConditionalFeatureImportance(values=values) - >>> position_parity(conditional_feature_importance, feature_importance) + >>> conditional_feature_importance = ConditionalImportance( + ... values={ + ... "group1": Importances( + ... values=np.array([0.40, 0.35, 0.25]), + ... feature_names=["feature_1", "feature_2", "feature_3"], + ... ), + ... "group2": Importances( + ... values=np.array([0.50, 0.30, 0.20]), + ... feature_names=["feature_3", "feature_2", "feature_1"], + ... ), + ... } + ... ) + >>> ranked_feature_importance = Importances( + ... values=np.array([0.50, 0.40, 0.10]), + ... feature_names=["feature_1", "feature_2", "feature_3"], + ... ) + >>> position_parity(conditional_feature_importance, ranked_feature_importance) 0.6388888888888888 """ metric = PositionParity() diff --git a/src/holisticai/explainability/metrics/global_importance/_rank_alignment.py b/src/holisticai/explainability/metrics/global_importance/_rank_alignment.py index 3b38bab9..8b51c52a 100644 --- a/src/holisticai/explainability/metrics/global_importance/_rank_alignment.py +++ b/src/holisticai/explainability/metrics/global_importance/_rank_alignment.py @@ -10,6 +10,16 @@ class RankAlignment(BaseModel): reference: float = 1.0 def __call__(self, conditional_feature_importance: ConditionalImportance, feature_importance: Importances): + """ + Calculates the rank alignment metric between conditional feature importance and overall feature importance. + + Args: + conditional_feature_importance (ConditionalImportance): Conditional feature importance object. + feature_importance (Importances): Overall feature importance object. + + Returns: + float: The rank alignment metric value. + """ feature_names = feature_importance.feature_names conditional_position_parity = {} for group_name, cond_features in conditional_feature_importance: @@ -26,12 +36,13 @@ def __call__(self, conditional_feature_importance: ConditionalImportance, featur def rank_alignment(conditional_feature_importance: ConditionalImportance, ranked_feature_importance: Importances): """ - Calculates the rank alignment metric between conditional feature importance and ranked feature importance. + The `Rank Alignment` metric is used to measure the alignment between conditional feature importance and overall feature importance. + It provides a way to assess how well the importance rankings of features in a conditional context match the rankings in the overall context. Parameters ---------- - conditional_feature_importance: ConditionalFeatureImportance - The conditional feature importance values. + conditional_feature_importance: ConditionalImportance + The feature importance for each output label (classification) or output region (regression). ranked_feature_importance: Importances The ranked feature importance values. @@ -42,21 +53,22 @@ def rank_alignment(conditional_feature_importance: ConditionalImportance, ranked Example ------- >>> from holisticai.explainability.commons import ( - ... ConditionalFeatureImportance, + ... ConditionalImportance, ... Importances, ... ) >>> from holisticai.explainability.metrics import rank_alignment - >>> values = { - ... "0": Importances( - ... values=[0.1, 0.2, 0.3, 0.4], - ... feature_names=["feature_2", "feature_3", "feature_4"], - ... ), - ... "1": Importances( - ... values=[0.4, 0.3, 0.2, 0.1], - ... feature_names=["feature_1", "feature_2", "feature_3", "feature_4"], - ... ), - ... } - >>> conditional_feature_importance = ConditionalFeatureImportance(values=values) + >>> conditional_feature_importance = ConditionalImportance( + ... values={ + ... "0": Importances( + ... values=[0.1, 0.2, 0.3, 0.4], + ... feature_names=["feature_2", "feature_3", "feature_4"], + ... ), + ... "1": Importances( + ... values=[0.4, 0.3, 0.2, 0.1], + ... feature_names=["feature_1", "feature_2", "feature_3", "feature_4"], + ... ), + ... } + ... ) >>> ranked_feature_importance = Importances( ... values=[0.5, 0.3, 0.2], ... feature_names=["feature_1", "feature_2", "feature_3"], diff --git a/src/holisticai/explainability/metrics/global_importance/_xai_ease_score.py b/src/holisticai/explainability/metrics/global_importance/_xai_ease_score.py index 372bd529..0f369087 100644 --- a/src/holisticai/explainability/metrics/global_importance/_xai_ease_score.py +++ b/src/holisticai/explainability/metrics/global_importance/_xai_ease_score.py @@ -172,7 +172,8 @@ def xai_ease_score(partial_dependence: PartialDependence, ranked_feature_importa Calculates the XAI Ease Score metric. This metric measures the ease of explaining a model's predictions using partial dependence plots - and ranked feature importance. + and ranked feature importance. The XAI Ease Score takes into account the similarity between regions + of the partial dependence plots of different features and assigns scores based on the similarity values. Parameters ---------- diff --git a/src/holisticai/explainability/metrics/local_importance/_stability.py b/src/holisticai/explainability/metrics/local_importance/_stability.py index cdbf625e..e52bb907 100644 --- a/src/holisticai/explainability/metrics/local_importance/_stability.py +++ b/src/holisticai/explainability/metrics/local_importance/_stability.py @@ -24,6 +24,8 @@ def __call__(self, local_feature_importance: LocalImportances): def data_stability(local_feature_importance: LocalImportances): """ Calculate the data stability score based on the local feature importances. + Data Stability measures the stability of the feature importance values across different instances. + Higher values indicate more stable feature importance values across instances. Parameters ---------- @@ -74,6 +76,8 @@ def __call__(self, local_feature_importance: LocalImportances): def feature_stability(local_feature_importance: LocalImportances): """ Calculate the feature stability score based on the local feature importances. + Feature Stability measures the stability of the feature importance values across different features. + Higher values indicate more stable feature importance values across features. Parameters ---------- diff --git a/src/holisticai/explainability/plots/_feature_importance.py b/src/holisticai/explainability/plots/_feature_importance.py index 21d8f7bc..3ca18c14 100644 --- a/src/holisticai/explainability/plots/_feature_importance.py +++ b/src/holisticai/explainability/plots/_feature_importance.py @@ -1,4 +1,4 @@ -from holisticai.explainability.commons import Importances +from holisticai.utils import Importances from matplotlib import pyplot as plt diff --git a/src/holisticai/explainability/plots/_tree.py b/src/holisticai/explainability/plots/_tree.py index aaab576b..29d27ea9 100644 --- a/src/holisticai/explainability/plots/_tree.py +++ b/src/holisticai/explainability/plots/_tree.py @@ -2,7 +2,7 @@ import matplotlib.pyplot as plt import numpy as np -from holisticai.explainability.commons import Importances +from holisticai.utils import Importances from sklearn.tree._export import _MPLTreeExporter From 410bd425eb80306cd63d792841dea114214f7dea Mon Sep 17 00:00:00 2001 From: Franklin Cardenoso <44931423+fracarfer5@users.noreply.github.com> Date: Wed, 24 Jul 2024 08:04:14 -0300 Subject: [PATCH 2/2] docs: adding descriptions for inprocessing methods (#151) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: adding descriptions for inprocessing methods * docs: updating method descriptions, adding index and reformatting sectinos * docs: adding learning task note for all methods * docs: adding documentation for adversarial debiasing and debiasing learning methods --------- Co-authored-by: Cristian Muñoz --- .../getting_started/bias/bias_mitigation.csv | 30 ++++++++ .../bias/methods/inprocessing.rst | 24 +++++++ ...sarial_debiasing_adversarial_debiasing.rst | 45 ++++++++++++ ...earch_exponentiated_gradient_reduction.rst | 27 ++++++++ .../bc_exp_grad_grid_search_grid_search.rst | 21 ++++++ .../bc_meta_fair_classifier_rho_fair.rst | 26 +++++++ ..._remover_prejudice_remover_regularizer.rst | 69 +++++++++++++++++++ .../c_fair_k_center_fair_k_center.rst | 24 +++++++ .../c_fair_k_median_fair_k_median.rst | 23 +++++++ ...irlet_clustering_fairlet_decomposition.rst | 33 +++++++++ ...clustering_variational_fair_clustering.rst | 42 +++++++++++ ..._scoring_classifier_fairscoringsystems.rst | 49 +++++++++++++ ..._blind_spot_aware_matrix_factorization.rst | 31 +++++++++ ...larity_propensity_matrix_factorization.rst | 49 +++++++++++++ ...sity_propensity_scored_recommendations.rst | 24 +++++++ ...ed_fairness_fairrec_two_sided_fairness.rst | 25 +++++++ .../getting_started/bias/mitigation.rst | 59 ++++++++-------- docs/source/getting_started/index.rst | 16 ++++- 18 files changed, 585 insertions(+), 32 deletions(-) create mode 100644 docs/source/getting_started/bias/bias_mitigation.csv create mode 100644 docs/source/getting_started/bias/methods/inprocessing.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/bc_adversarial_debiasing_adversarial_debiasing.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/bc_exp_grad_grid_search_exponentiated_gradient_reduction.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/bc_exp_grad_grid_search_grid_search.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/bc_meta_fair_classifier_rho_fair.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/bc_prejudice_remover_prejudice_remover_regularizer.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/c_fair_k_center_fair_k_center.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/c_fair_k_median_fair_k_median.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/c_fairlet_clustering_fairlet_decomposition.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/c_variational_fair_clustering_variational_fair_clustering.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/mc_fair_scoring_classifier_fairscoringsystems.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/rs_blind_spot_aware_blind_spot_aware_matrix_factorization.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/rs_popularity_propensity_matrix_factorization.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/rs_popularity_propensity_propensity_scored_recommendations.rst create mode 100644 docs/source/getting_started/bias/methods/inprocessing/rs_two_sided_fairness_fairrec_two_sided_fairness.rst diff --git a/docs/source/getting_started/bias/bias_mitigation.csv b/docs/source/getting_started/bias/bias_mitigation.csv new file mode 100644 index 00000000..ddbcbd4d --- /dev/null +++ b/docs/source/getting_started/bias/bias_mitigation.csv @@ -0,0 +1,30 @@ +Preprocessing,Correlation Remover,X,X,X,, +Preprocessing,Disparate Impact Remover,X,X,X,X, +Preprocessing,Learning Fair Representation,X,,,, +Preprocessing,Reweighing,X,X,,, +Preprocessing,Fair Clustering,,,,X, +Inprocessing,"Adversarial Debiasing ",X,,,, +Inprocessing,Exponentiated Gradient,X,,X,, +Inprocessing,Fair K Center Clustering,,,,X, +Inprocessing,Fair K Median Clustering,,,,X, +Inprocessing,Fair Scoring Classifier,,X,,, +Inprocessing,Fairlet Clustering,,,,X, +Inprocessing,Grid Search,X,,X,, +Inprocessing,Debiasing Learning,,,,,X +Inprocessing,Blind Spot Aware,,,,,X +Inprocessing,Popularity Propensity,,,,,X +Inprocessing,Meta Fair Classifier,X,,,, +Inprocessing,Prejudice Remover,X,,,, +Inprocessing,Two Sided Fairness,,,,,X +Inprocessing,Variational Fair Clustering,,,,X, +Postprocessing,Debiasing Exposure,,,,,X +Postprocessing,Fair Top-K,,,,,X +Postprocessing,LP Debiaser,X,X,,, +Postprocessing,MCMF Clustering,,,,X, +Postprocessing,ML Debiaser,X,X,,, +Postprocessing,Plugin Estimator and Recalibration,,,X,, +Postprocessing,Wasserstein Barycenters,,,X,, +Postprocessing,Calibrated Equalized Odds,X,,,, +Postprocessing,Equalized Odds,X,,,, +Postprocessing,Reject Option Classification,X,,,, +Postprocessing,Disparate Impact Remover for RS,,,,,X \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing.rst b/docs/source/getting_started/bias/methods/inprocessing.rst new file mode 100644 index 00000000..6159e943 --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing.rst @@ -0,0 +1,24 @@ +In-processing Methods +===================== + +In-processing techniques modify the learning algorithm itself to reduce bias during the model training phase. These methods work by incorporating fairness constraints or objectives directly into the training process, ensuring that the model learns to make unbiased decisions. In-processing methods can include adversarial debiasing, fairness constraints, and regularization techniques. By addressing bias during the training phase, these methods aim to create models that are intrinsically fair and less likely to produce biased outcomes. + +Here are the in-processing methods implemented in the Holistic AI package: + + .. toctree:: + :maxdepth: 1 + + inprocessing/bc_exp_grad_grid_search_exponentiated_gradient_reduction.rst + inprocessing/bc_exp_grad_grid_search_grid_search.rst + inprocessing/bc_meta_fair_classifier_rho_fair.rst + inprocessing/bc_prejudice_remover_prejudice_remover_regularizer.rst + inprocessing/c_fair_k_center_fair_k_center.rst + inprocessing/c_fair_k_median_fair_k_median.rst + inprocessing/c_fairlet_clustering_fairlet_decomposition.rst + inprocessing/c_variational_fair_clustering_variational_fair_clustering.rst + inprocessing/mc_fair_scoring_classifier_fairscoringsystems.rst + inprocessing/rs_blind_spot_aware_blind_spot_aware_matrix_factorization.rst + inprocessing/rs_popularity_propensity_propensity_scored_recommendations.rst + inprocessing/rs_two_sided_fairness_fairrec_two_sided_fairness.rst + inprocessing/bc_adversarial_debiasing_adversarial_debiasing.rst + inprocessing/rs_popularity_propensity_matrix_factorization.rst \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/bc_adversarial_debiasing_adversarial_debiasing.rst b/docs/source/getting_started/bias/methods/inprocessing/bc_adversarial_debiasing_adversarial_debiasing.rst new file mode 100644 index 00000000..31efe3dd --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/bc_adversarial_debiasing_adversarial_debiasing.rst @@ -0,0 +1,45 @@ +Adversarial Debiasing +---------------------- + +.. note:: + **Learning tasks:** Binary classification. + + +Introduction +~~~~~~~~~~~~~~~ +Adversarial Debiasing is a method designed to mitigate unwanted biases in machine learning models by leveraging adversarial learning techniques. The method aims to ensure that the predictions made by a model are not influenced by protected variables, such as gender or race, which are considered sensitive and should not affect the decision-making process. This approach is significant because it addresses the ethical and fairness concerns in machine learning, ensuring that models do not perpetuate existing biases present in the training data. + +Description +~~~~~~~~~~~~~~ + +- **Problem definition** + + Machine learning models often inherit biases from the training data, leading to unfair predictions that can discriminate against certain demographic groups. The goal of Adversarial Debiasing is to train a model that accurately predicts an output variable :math:`Y` from an input variable :math:`X`, while ensuring that the predictions are unbiased with respect to a protected variable :math:`Z`. The protected variable :math:`Z` could be any sensitive attribute such as gender, race, or zip code. + +- **Main features** + + The Adversarial Debiasing method incorporates an adversarial network into the training process. This adversarial network is designed to predict the protected variable :math:`Z` from the model's predictions :math:`\hat{Y}`. The main features of this method include: + + - Simultaneous training of a predictor and an adversary. + - The predictor aims to maximize the accuracy of predicting :math:`Y`. + - The adversary aims to minimize its ability to predict :math:`Z` from :math:`\hat{Y}`. + - The method can be applied to various definitions of fairness, such as Demographic Parity and Equality of Odds. + - It is flexible and can be used with different types of gradient-based learning models, including both regression and classification tasks. + +- **Step-by-step description of the approach** + + 1. **Predictor Training**: The primary model, referred to as the predictor, is trained to predict the output variable :math:`Y` from the input variable :math:`X`. The predictor's objective is to minimize the prediction loss :math:`L_P(\hat{y}, y)`, where :math:`\hat{y}` is the predicted value and :math:`y` is the true value. + + 2. **Adversary Training**: An adversarial network is introduced, which takes the predictor's output :math:`\hat{Y}` as input and attempts to predict the protected variable :math:`Z`. The adversary's objective is to minimize its prediction loss :math:`L_A(\hat{z}, z)`, where :math:`\hat{z}` is the adversary's predicted value of :math:`Z` and :math:`z` is the true value of :math:`Z`. + + 3. **Adversarial Objective**: The adversarial network's loss is incorporated into the predictor's training process. The predictor is trained not only to minimize its own prediction loss :math:`L_P`, but also to maximize the adversary's loss :math:`L_A`. This is achieved by updating the predictor's weights in a way that reduces the information about :math:`Z` contained in :math:`\hat{Y}`. + + 4. **Fairness Constraints**: Depending on the desired fairness definition, the adversary's input may vary. For Demographic Parity, the adversary only receives :math:`\hat{Y}` as input. For Equality of Odds, the adversary also receives the true label :math:`Y` as input, ensuring that any information about :math:`Z` in :math:`\hat{Y}` is limited to what is already contained in :math:`Y`. + + 5. **Training Process**: The training process involves alternating updates between the predictor and the adversary. The predictor is updated to improve its prediction accuracy while deceiving the adversary. The adversary is updated to improve its ability to predict :math:`Z` from :math:`\hat{Y}`. This adversarial training continues until a balance is achieved where the predictor makes accurate predictions of :math:`Y` without revealing information about :math:`Z`. + + 6. **Evaluation**: The trained model is evaluated to ensure that it meets the desired fairness criteria. Metrics such as False Positive Rate (FPR) and False Negative Rate (FNR) are used to assess whether the model's predictions are unbiased with respect to the protected variable :math:`Z`. + +References +~~~~~~~~~~~~~~ +1. B. H. Zhang, B. Lemoine, and M. Mitchell, "Mitigating Unwanted Biases with Adversarial Learning," AAAI/ACM Conference on Artificial Intelligence, Ethics, and Society, 2018. \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/bc_exp_grad_grid_search_exponentiated_gradient_reduction.rst b/docs/source/getting_started/bias/methods/inprocessing/bc_exp_grad_grid_search_exponentiated_gradient_reduction.rst new file mode 100644 index 00000000..01eb6f3d --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/bc_exp_grad_grid_search_exponentiated_gradient_reduction.rst @@ -0,0 +1,27 @@ +Exponentiated Gradient Reduction Method +------------------------------------------- + +.. note:: + **Learning tasks:** Binary classification, regression. + +Introduction +~~~~~~~~~~~~~~~~ +The Exponentiated Gradient (EG) reduction method is a technique used to achieve fairness in binary classification tasks. It is designed to optimize the tradeoff between accuracy and fairness by incorporating fairness constraints into the learning process. This method is particularly useful for ensuring that classifiers do not exhibit bias against protected attributes such as race or gender. + +Description +~~~~~~~~~~~~~~~ +The EG reduction method addresses the problem of fair classification by transforming it into a cost-sensitive classification problem. The main characteristics of this approach include: + +- **Problem Definition:** The goal is to minimize classification error while satisfying fairness constraints, such as demographic parity or equalized odds. +- **Main Characteristics:** The method uses a Lagrangian formulation to incorporate fairness constraints into the objective function. It iteratively adjusts the costs associated with different training examples to achieve the desired fairness. +- **Step-by-Step Description:** + + 1. **Formulate the Lagrangian:** Introduce Lagrange multipliers for each fairness constraint and form the Lagrangian function. + 2. **Saddle Point Problem:** Rewrite the problem as a saddle point problem, where the objective is to find a pair of solutions that minimize the Lagrangian with respect to the classifier and maximize it with respect to the Lagrange multipliers. + 3. **Iterative Algorithm:** Use an iterative algorithm to find the saddle point. The algorithm alternates between updating the classifier and the Lagrange multipliers. + 4. **Exponentiated Gradient Updates:** Use the exponentiated gradient algorithm to update the Lagrange multipliers, ensuring that they remain non-negative and sum to a bounded value. + 5. **Best Response Calculation:** At each iteration, calculate the best response of the classifier and the Lagrange multipliers. + +References +~~~~~~~~~~~~~~ +1. Agarwal, A., Beygelzimer, A., Dudik, M., Langford, J., & Wallach, H. (2018). A reductions approach to fair classification. In Advances in Neural Information Processing Systems (pp. 656-666). \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/bc_exp_grad_grid_search_grid_search.rst b/docs/source/getting_started/bias/methods/inprocessing/bc_exp_grad_grid_search_grid_search.rst new file mode 100644 index 00000000..6bd0af72 --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/bc_exp_grad_grid_search_grid_search.rst @@ -0,0 +1,21 @@ +Grid Search +--------------- + +.. note:: + **Learning tasks:** Binary classification, regression. + +Introduction +~~~~~~~~~~~~~~~~ +Grid search is a method used to select a deterministic classifier from a set of candidate classifiers obtained from the saddle point of a Lagrangian function. This method is particularly useful when the number of constraints is small, such as in demographic parity or equalized odds with a binary protected attribute. The goal is to find a classifier that balances the tradeoff between accuracy and fairness. + +Description +~~~~~~~~~~~~~~~~ +Grid search involves the following steps: + +1. **Candidate Classifiers**: A set of candidate classifiers is obtained from the saddle point :math:`(Q^\dagger, \lambda^\dagger)`. Since :math:`Q^\dagger` is a minimizer of :math:`L(Q, \lambda^\dagger)` and :math:`L` is linear in :math:`Q` the distribution :math:`Q^\dagger` puts non-zero mass only on classifiers that are the Q-player’s best responses to :math:`\lambda^\dagger`. +2. **Best Response Calculation**: If :math:`\lambda^\dagger` is known, one can retrieve a best response via a reduction to cost-sensitive learning. +3. **Grid Search**: When the number of constraints is small, a grid of values for :math:`\lambda` is considered. For each value, the best response is calculated, and the value with the desired tradeoff between accuracy and fairness is selected. + +References +~~~~~~~~~~~~~~~~ +1. Agarwal, A., Beygelzimer, A., Dudik, M., Langford, J., & Wallach, H. (2018). A reductions approach to fair classification. In Advances in Neural Information Processing Systems (pp. 656-666). \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/bc_meta_fair_classifier_rho_fair.rst b/docs/source/getting_started/bias/methods/inprocessing/bc_meta_fair_classifier_rho_fair.rst new file mode 100644 index 00000000..f550dfbc --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/bc_meta_fair_classifier_rho_fair.rst @@ -0,0 +1,26 @@ +ρ-Fair Method +----------------- + +.. note:: + **Learning tasks:** Binary classification. + +Introduction +~~~~~~~~~~~~~~~~ +The ρ-Fair method is designed to address fairness in machine learning classification tasks. It aims to ensure that the classifier's performance is equitable across different groups defined by sensitive attributes. This method is significant as it provides a structured approach to mitigate biases and ensure fairness in predictive models. + +Description +~~~~~~~~~~~~~~~~ +The ρ-Fair method involves reducing the fairness problem to a series of Group-Fair problems, which are easier to solve. The main characteristics of the method include: + +- **Problem Definition**: The goal is to find a classifier :math:`f` that minimizes prediction error while satisfying fairness constraints defined by a parameter :math:`\tau \in [0,1]`. +- **Main Characteristics**: The method uses a meta-algorithm that iteratively solves Group-Fair problems to approximate a solution for the ρ-Fair problem. +- **Step-by-Step Description**: + + 1. **Estimate Distribution**: Compute an estimated distribution :math:`\hat{\mathcal{D}}` from the given samples. + 2. **Iterative Group-Fair Solutions**: For each iteration, define intervals :math:`a_i` and :math:`b_i` based on the fairness parameter :math:`\tau` and error parameter :math:`\epsilon`. + 3. **Compute Classifiers**: Solve the Group-Fair problem for each interval to obtain a set of classifiers. + 4. **Select Optimal Classifier**: Choose the classifier that minimizes the prediction error. + +References +~~~~~~~~~~~~~~~~ +1. Celis, L. Elisa, et al. "Classification with fairness constraints: A meta-algorithm with provable guarantees." Proceedings of the conference on fairness, accountability, and transparency. 2019. \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/bc_prejudice_remover_prejudice_remover_regularizer.rst b/docs/source/getting_started/bias/methods/inprocessing/bc_prejudice_remover_prejudice_remover_regularizer.rst new file mode 100644 index 00000000..48f96a23 --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/bc_prejudice_remover_prejudice_remover_regularizer.rst @@ -0,0 +1,69 @@ +Prejudice Remover Regularizer +----------------------------- + +.. note:: + **Learning tasks:** Binary classification. + +Introduction +~~~~~~~~~~~~ +The Prejudice Remover Regularizer is a method designed to enforce fairness in classification tasks by reducing indirect prejudice. This method is integrated into logistic regression models and aims to ensure that the predictions are not unfairly influenced by sensitive features. The regularizer is designed to be computationally efficient and easy to implement, making it a practical solution for fairness-aware machine learning. + +Description +~~~~~~~~~~~ + +- **Problem definition** + + In classification tasks, we often deal with a target variable :math:`Y`, non-sensitive features :math:`X`, and a sensitive feature :math:`S`. The goal is to predict the class :math:`Y` based on :math:`X` and :math:`S` while ensuring that the sensitive feature :math:`S` does not unfairly influence the prediction. The training dataset is denoted as :math:`D = \{(y, x, s)\}`, where :math:`y`, :math:`x`, and :math:`s` are instances of :math:`Y`, :math:`X`, and :math:`S`, respectively. + +- **Main features** + + The method incorporates two types of regularizers into the logistic regression model: + + 1. **L2 Regularizer**: This is a standard regularizer used to avoid overfitting. It is represented as :math:`\|\Theta\|_2^2`, where :math:`\Theta` is the set of model parameters. + + 2. **Prejudice Remover Regularizer**: This regularizer, denoted as :math:`R_{PR}`, is specifically designed to reduce indirect prejudice by minimizing the prejudice index (PI). The PI quantifies the statistical dependence between the sensitive feature :math:`S` and the target variable :math:`Y`. + +- **Step-by-step description of the approach** + + 1. **Model Definition**: The conditional probability of a class given non-sensitive and sensitive features is modeled by :math:`M[Y|X,S;\Theta]`, where :math:`\Theta` is the set of model parameters. The logistic regression model is used as the prediction model: + + .. math:: + M[y|x,s;\Theta] = y\sigma(x^\top w_s) + (1-y)(1-\sigma(x^\top w_s)), + + where :math:`\sigma(\cdot)` is the sigmoid function, and :math:`w_s` are the weight vectors for :math:`x`. + + 2. **Log-Likelihood Maximization**: The parameters are estimated based on the maximum likelihood principle, aiming to maximize the log-likelihood: + + .. math:: + L(D;\Theta) = \sum_{(y_i, x_i, s_i) \in D} \ln M[y_i|x_i, s_i; \Theta]. + + 3. **Objective Function**: The objective function to minimize is obtained by adding the L2 regularizer and the prejudice remover regularizer to the negative log-likelihood: + + .. math:: + -L(D;\Theta) + \eta R(D, \Theta) + \frac{\lambda}{2} \|\Theta\|_2^2, + + where :math:`\lambda` and :math:`\eta` are positive regularization parameters. + + 4. **Prejudice Index Calculation**: The prejudice index (PI) is defined as: + + .. math:: + PI = \sum_{Y,S} \hat{Pr}[Y,S] \ln \frac{\hat{Pr}[Y,S]}{\hat{Pr}[S] \hat{Pr}[Y]}. + + This can be approximated using the training data: + + .. math:: + PI \approx \sum_{(x_i, s_i) \in D} \sum_{y \in \{0,1\}} M[y|x_i, s_i; \Theta] \ln \frac{\hat{Pr}[y|s_i]}{\hat{Pr}[y]}. + + 5. **Normalization**: The normalized prejudice index (NPI) is calculated to quantify the degree of indirect prejudice: + + .. math:: + NPI = \frac{PI}{\sqrt{H(Y)H(S)}}, + + where :math:`H(\cdot)` is the entropy function. + + 6. **Trade-off Efficiency**: The efficiency of the trade-off between prediction accuracy and prejudice removal is measured by the ratio :math:`PI/MI`, where :math:`MI` is the mutual information between the predicted and true labels. + + +References +~~~~~~~~~~~~~~~~ +1. Kamishima, Toshihiro, et al. "Fairness-aware classifier with prejudice remover regularizer." Joint European conference on machine learning and knowledge discovery in databases. Springer, Berlin, Heidelberg, 2012. \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/c_fair_k_center_fair_k_center.rst b/docs/source/getting_started/bias/methods/inprocessing/c_fair_k_center_fair_k_center.rst new file mode 100644 index 00000000..8a9dca7d --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/c_fair_k_center_fair_k_center.rst @@ -0,0 +1,24 @@ +Fair k-Center Clustering Method +---------------- + +.. note:: + **Learning tasks:** Clustering. + +Introduction +~~~~~~~~~~~~~~~~ +The Fair k-Center Clustering method addresses the problem of centroid-based clustering, such as k-center, in a way that ensures fair representation of different demographic groups. This method is particularly relevant in scenarios where the data set comprises multiple demographic groups, and there is a need to select a fixed number of representatives (centers) from each group to form a summary. The method extends the traditional k-center clustering problem by incorporating fairness constraints, ensuring that each group is fairly represented in the selected centers. + +Description +~~~~~~~~~~~~~~~~ +The Fair k-Center Clustering method aims to minimize the maximum distance between any data point and its closest center while ensuring that a specified number of centers are chosen from each demographic group. + +The method involves a recursive algorithm that handles the fairness constraints by iteratively selecting centers and ensuring the required representation from each group. The algorithm can be broken down into the following steps: + +1. **Initialization**: Start with an empty set of centers and the given parameters. +2. **Center Selection**: Use a greedy strategy to select centers that maximize the distance to the current set of centers. +3. **Fairness Adjustment**: Adjust the selected centers to ensure the required number of centers from each group. +4. **Recursion**: If the fairness constraints are not met, recursively apply the algorithm to a subset of the data until the constraints are satisfied. + +References +~~~~~~~~~~~~~~~~ +1. Kleindessner, Matthäus, Pranjal Awasthi, and Jamie Morgenstern. "Fair k-center clustering for data summarization." International Conference on Machine Learning. PMLR, 2019. \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/c_fair_k_median_fair_k_median.rst b/docs/source/getting_started/bias/methods/inprocessing/c_fair_k_median_fair_k_median.rst new file mode 100644 index 00000000..e28252a3 --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/c_fair_k_median_fair_k_median.rst @@ -0,0 +1,23 @@ +Fair k-Median Method +-------------------- + +.. note:: + **Learning tasks:** Clustering. + +Introduction +~~~~~~~~~~~~~~~~ +The fair k-median method aims to address the issue of fairness in clustering by ensuring that the clustering solution does not disproportionately favor any particular group. This method is particularly relevant in scenarios where data points belong to different demographic groups, and it is crucial to provide equitable representation and minimize bias in the clustering process. + +Description +~~~~~~~~~~~~~~~~ +The fair k-median method involves several key steps to ensure fairness in clustering: + +1. **Bundling**: For each point :math:`u \in S`, a bundle :math:`B_u` is created, which consists of the centers that exclusively serve :math:`u`. During the rounding procedure, each bundle :math:`B_u` is treated as a single entity, where at most one center from it will be opened. The probability of opening a center from a bundle, :math:`B_u`, is the sum of :math:`y_c` for all :math:`c \in B_u`, referred to as the bundle's volume. + +2. **Matching**: The generated bundles have the property that their volume lies within the range :math:`[1/2, 1]`. Therefore, given any two bundles, at least one center from them should be opened. While there are at least two unmatched points in :math:`S`, the corresponding bundles of the two closest unmatched points in :math:`S` are matched. + +3. **Sampling**: Given the matching generated in the previous phase, the algorithm iterates over its members and considers the bundle volumes as probabilities to open :math:`k` centers in expectation. The centers picked in the sampling phase are returned as the final :math:`k` centers. + +References +~~~~~~~~~~~~~~~~ +1. Abbasi, Mohsen, Aditya Bhaskara, and Suresh Venkatasubramanian. "Fair clustering via equitable group representations." Proceedings of the 2021 ACM Conference on Fairness, Accountability, and Transparency. 2021. \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/c_fairlet_clustering_fairlet_decomposition.rst b/docs/source/getting_started/bias/methods/inprocessing/c_fairlet_clustering_fairlet_decomposition.rst new file mode 100644 index 00000000..4652c9f6 --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/c_fairlet_clustering_fairlet_decomposition.rst @@ -0,0 +1,33 @@ +Fairlet Decomposition Method +------------------------------ + +.. note:: + **Learning tasks:** Clustering. + +Introduction +~~~~~~~~~~~~~~~~ +The Fairlet Decomposition method is a scalable algorithm designed to partition a set of points into fairlets, which are small clusters that maintain a specified balance between two types of points (e.g., red and blue points). This method is particularly useful in fair clustering tasks where the goal is to ensure that each cluster has a balanced representation of different types of points. + +Description +~~~~~~~~~~~~~~~~ +The Fairlet Decomposition method operates on a hierarchical space tree (HST) embedding of the input points. The main goal is to partition the points into fairlets that are balanced according to given parameters :math:`(r, b)`, where :math:`r` and :math:`b` denote the number of red and blue points, respectively. + +The method consists of three main steps: + +1. **Approximately Minimize the Total Number of Heavy Points:** + + - For each non-empty child of a node :math:`v` in the HST, compute the number of red and blue points that need to be removed to make the remaining points :math:`(r, b)`-balanced. + - Solve the Minimum Heavy Points Problem to find the optimal number of points to remove. + +2. **Find an (r, b)-Fairlet Decomposition of Heavy Points:** + + - Remove the computed number of red and blue points from each child and add them to a set :math:`P_v`. + - Output an :math:`(r, b)`-fairlet decomposition of the points in :math:`P_v`. + +3. **Proceed to the Children of the Node:** + + - Recursively apply the Fairlet Decomposition method to each non-empty child of the node. + +References +~~~~~~~~~~~~~~~~ +1. Backurs, Arturs, et al. "Scalable fair clustering." International Conference on Machine Learning. PMLR, 2019. \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/c_variational_fair_clustering_variational_fair_clustering.rst b/docs/source/getting_started/bias/methods/inprocessing/c_variational_fair_clustering_variational_fair_clustering.rst new file mode 100644 index 00000000..265ae09f --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/c_variational_fair_clustering_variational_fair_clustering.rst @@ -0,0 +1,42 @@ +Variational Fair Clustering +----------------- + +.. note:: + **Learning tasks:** Clustering. + +Introduction +~~~~~~~~~~~~~~~~ +The Variational Fair Clustering method integrates a Kullback-Leibler (KL) fairness term with a variety of clustering objectives, including prototype-based and graph-based methods. This approach allows for controlling the trade-off between fairness and clustering quality, providing a scalable solution with convergence guarantees. Unlike existing combinatorial and spectral methods, this variational framework does not require eigenvalue decomposition, making it suitable for large-scale datasets. + +Description +~~~~~~~~~~~~~~~~ +The problem involves assigning :math:`N` data points to :math:`K` clusters while ensuring that the clusters are balanced with respect to :math:`J` different demographic groups. The method introduces a fairness term based on the Kullback-Leibler (KL) divergence to measure the deviation from a target demographic distribution within each cluster. + +- **Problem Definition:** + Given a set of data points :math:`X = \{ x_p \in \mathbb{R}^M, p = 1, \ldots, N \}` and :math:`J` demographic groups, the goal is to assign these points to :math:`K` clusters such that the clusters are fair with respect to the demographic groups. + +- **Main Characteristics:** + - Integrates a KL fairness term with clustering objectives. + - Provides a tight upper bound based on concave-convex decomposition. + - Scalable and suitable for large datasets. + - Allows independent updates for each assignment variable, facilitating distributed computation. + +- **Step-by-Step Description:** + + 1. **Initialization:** + + - Initialize cluster labels from initial seeds. + - Initialize the soft cluster-assignment vector :math:`S` from the labels. + 2. **Iterative Optimization:** + + - Compute the auxiliary variable :math:`a_p` from :math:`S`. + - Initialize the assignment probabilities :math:`s_p`. + - Update :math:`s_p` using the derived bound optimization. + - Repeat until the objective function converges. + 3. **Final Assignment:** + + - Assign each data point to the cluster with the highest probability. + +References +~~~~~~~~~~~~~~~~ +1. Ziko, Imtiaz Masud, et al. "Variational fair clustering." Proceedings of the AAAI Conference on Artificial Intelligence. Vol. 35. No. 12. 2021. \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/mc_fair_scoring_classifier_fairscoringsystems.rst b/docs/source/getting_started/bias/methods/inprocessing/mc_fair_scoring_classifier_fairscoringsystems.rst new file mode 100644 index 00000000..158800f9 --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/mc_fair_scoring_classifier_fairscoringsystems.rst @@ -0,0 +1,49 @@ +FAIRScoringSystems +------------------ + +.. note:: + **Learning tasks:** Multiclassification. + +Introduction +~~~~~~~~~~~~~~~~ +FAIRScoringSystems is a Mixed Integer Linear Programming (MILP) framework designed to generate optimal scoring systems for multi-class classification tasks. The method ensures that the resulting models are interpretable, fair, and sparse. It incorporates fairness constraints to mitigate biases against protected groups and sparsity constraints to enhance model interpretability. + +Description +~~~~~~~~~~~~~~~~ +FAIRScoringSystems extends the Supersparse Linear Integer Model (SLIM) framework to handle multi-class classification problems. The method generates one scoring system for each class in a one-vs-all manner. The primary goal is to maximize classification accuracy while adhering to user-defined fairness and sparsity constraints. + +- **Problem Definition**: The method aims to create scoring systems that are both accurate and fair, ensuring that the classification does not disproportionately disadvantage any protected group. +- **Main Characteristics**: + + - **Fairness Constraints**: Ensures that the model's predictions are fair with respect to a chosen fairness metric and a specified tolerance level. + - **Sparsity Constraints**: Limits the number of non-zero coefficients in the scoring system to enhance interpretability. + - **Multi-Class Classification**: Extends binary scoring systems to multi-class problems using a one-vs-all approach. + +- **Step-by-Step Description**: + + 1. **Define Variables**: + + - Integer variables representing the coefficients of the scoring systems. + - Binary loss variables indicating misclassification of training samples. + - Binary variables indicating non-zero coefficients. + + 2. **Set Up Objective Function**: + + - Maximize accuracy or balanced accuracy. + + 3. **Incorporate Fairness Constraints**: + + - Define fairness metrics for multi-class classification. + - Apply fairness constraints to sensitive labels. + + 4. **Apply Sparsity Constraints**: + + - Limit the number of non-zero coefficients in each scoring system. + + 5. **Solve MILP**: + + - Use an off-the-shelf MILP solver to find the optimal scoring systems. + +References +~~~~~~~~~~~~~~~~ +1. Julien Rouzot, Julien Ferry, Marie-José Huguet. Learning Optimal Fair Scoring Systems for MultiClass Classification. ICTAI 2022 - The 34th IEEE International Conference on Tools with Artificial Intelligence, Oct 2022, Virtual, United States. \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/rs_blind_spot_aware_blind_spot_aware_matrix_factorization.rst b/docs/source/getting_started/bias/methods/inprocessing/rs_blind_spot_aware_blind_spot_aware_matrix_factorization.rst new file mode 100644 index 00000000..12ddb78e --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/rs_blind_spot_aware_blind_spot_aware_matrix_factorization.rst @@ -0,0 +1,31 @@ +Blind Spot Aware Matrix Factorization +---------------------- + +.. note:: + **Learning tasks:** Recommendation systems. + +Introduction +~~~~~~~~~~~~~~~~ +Blind Spot Aware Matrix Factorization (BSAMF) is a novel approach designed to address the limitations of conventional matrix factorization methods in recommender systems. The primary goal of BSAMF is to reduce the "blind spot" for users, which refers to the set of items that are predicted to have low ratings and thus are less likely to be recommended. By minimizing the blind spot, BSAMF aims to enhance the diversity of recommendations and improve user satisfaction. + +Description +~~~~~~~~~~~~~~~~ +The Blind Spot Aware Matrix Factorization method modifies the conventional matrix factorization approach by incorporating a term that penalizes the size of the blind spot. The blind spot for a user is defined as the set of items with predicted ratings below a certain threshold. This threshold is user-specific and is set to a percentile cut-off of the predicted ratings. + +The method can be described as follows: + +1. **Problem Definition**: Given a user-item rating matrix, the goal is to predict the missing ratings while minimizing the blind spot for each user. +2. **Main Characteristics**: + + - Incorporates a blind spot penalty term in the cost function. + - Uses stochastic gradient descent for optimization. + - Adjusts the user and item latent factors to reduce the blind spot size. +3. **Step-by-Step Description**: + + - Define the blind spot for each user based on a threshold. + - Modify the cost function to include a term that penalizes the blind spot. + - Use stochastic gradient descent to update the user and item latent factors. + +References +~~~~~~~~~~~~~~~~ +1. Sun, Wenlong, et al. "Debiasing the human-recommender system feedback loop in collaborative filtering." Companion Proceedings of The 2019 World Wide Web Conference. 2019. \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/rs_popularity_propensity_matrix_factorization.rst b/docs/source/getting_started/bias/methods/inprocessing/rs_popularity_propensity_matrix_factorization.rst new file mode 100644 index 00000000..4108c11a --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/rs_popularity_propensity_matrix_factorization.rst @@ -0,0 +1,49 @@ +Matrix Factorization with Propensity Scoring +--------------------------------------------- + +.. note:: + **Learning tasks:** Recommendation systems. + +Introduction +~~~~~~~~~~~~ +Matrix Factorization with Propensity Scoring is a method designed to address selection biases in the evaluation and training of recommender systems. Selection biases often arise because users tend to rate items they like and ignore those they do not, leading to data that is Missing Not At Random (MNAR). This method adapts models and estimation techniques from causal inference to provide unbiased performance estimators and improve prediction performance. By viewing recommendations as interventions, similar to treatments in medical studies, this approach ensures accurate estimation of effects despite biased data. + +Description +~~~~~~~~~~~ + +- **Problem definition** + + The primary problem addressed by this method is the selection bias inherent in the data used to train and evaluate recommender systems. Traditional matrix factorization methods do not account for the fact that observed ratings are not a random sample of all possible ratings. Instead, they are biased towards items that users are more likely to rate, typically those they like. This bias can lead to inaccurate performance evaluation and suboptimal recommendation models. + +- **Main features** + + The main features of the Matrix Factorization with Propensity Scoring method include: + + 1. **Unbiased Performance Estimation**: The method uses propensity-weighting techniques to derive unbiased estimators for various performance measures such as Mean Squared Error (MSE), Mean Absolute Error (MAE), and Discounted Cumulative Gain (DCG). + + 2. **Empirical Risk Minimization (ERM) Framework**: The method incorporates an ERM framework for learning recommendation systems under selection bias, providing generalization error bounds. + + 3. **Propensity-Weighted Matrix Factorization**: The method extends traditional matrix factorization by incorporating propensity scores to account for selection bias, leading to improved prediction performance. + + 4. **Robustness to Mis-specified Propensities**: The method is designed to be robust against inaccuracies in the estimated propensities, ensuring reliable performance even when the propensity model is not perfectly specified. + +- **Step-by-step description of the approach** + + 1. **Estimating Propensities**: + Propensities are the probabilities that a particular rating is observed. These are estimated using models such as Naive Bayes or logistic regression, based on user and item covariates. For example, in a movie recommendation system, propensities might be estimated based on user demographics and movie genres. + + 2. **Unbiased Performance Estimation**: + Using the estimated propensities, the method applies propensity-weighting to derive unbiased estimators for performance measures. + + 3. **Empirical Risk Minimization (ERM)**: + The method formulates the learning problem as an ERM problem, where the objective is to minimize the expected loss over the observed data, weighted by the inverse of the propensity scores. This ensures that the learned model is unbiased with respect to the true distribution of ratings. + + 4. **Propensity-Weighted Matrix Factorization**: + The matrix factorization model is modified to incorporate propensity scores. + + 5. **Evaluation and Learning**: + The method evaluates the performance of the recommender system using the unbiased estimators and iteratively updates the model parameters to minimize the propensity-weighted loss. This process continues until convergence, resulting in a model that is robust to selection biases. + +References +~~~~~~~~~~~~~~~~ +1. Tobias Schnabel, Adith Swaminathan, Ashudeep Singh, Navin Chandak, and Thorsten Joachims. 2016. Recommendations as treatments: Debiasing learning and evaluation. arXiv preprint arXiv:1602.05352 (2016). \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/rs_popularity_propensity_propensity_scored_recommendations.rst b/docs/source/getting_started/bias/methods/inprocessing/rs_popularity_propensity_propensity_scored_recommendations.rst new file mode 100644 index 00000000..5a1ac67c --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/rs_popularity_propensity_propensity_scored_recommendations.rst @@ -0,0 +1,24 @@ +Propensity-Scored Recommendations +--------------------- + +.. note:: + **Learning tasks:** Recommendation systems. + +Introduction +~~~~~~~~~~~~~~~~ +Propensity-scored recommendations are a method designed to handle selection biases in the evaluation and training of recommender systems. This approach leverages techniques from causal inference to provide unbiased performance estimators and improve prediction accuracy, even when the data is Missing Not At Random (MNAR). + +Description +~~~~~~~~~~~~~~~~ +The propensity-scored recommendations method addresses the problem of biased data in recommender systems, where users typically rate items they like, leading to a non-random missing data pattern. The method involves estimating the probability (propensity) that a user will rate an item and using these propensities to adjust the training and evaluation processes. + +The main characteristics of the method include: + +- Estimating propensities for each user-item pair. +- Using these propensities to weight the observed data. +- Applying the Inverse-Propensity-Scoring (IPS) estimator to obtain unbiased performance measures. +- Integrating propensity scores into an Empirical Risk Minimization (ERM) framework for learning. + +References +~~~~~~~~~~~~~~~~ +1. Tobias Schnabel, Adith Swaminathan, Ashudeep Singh, Navin Chandak, and Thorsten Joachims. 2016. Recommendations as treatments: Debiasing learning and evaluation. arXiv preprint arXiv:1602.05352 (2016). \ No newline at end of file diff --git a/docs/source/getting_started/bias/methods/inprocessing/rs_two_sided_fairness_fairrec_two_sided_fairness.rst b/docs/source/getting_started/bias/methods/inprocessing/rs_two_sided_fairness_fairrec_two_sided_fairness.rst new file mode 100644 index 00000000..58ed9097 --- /dev/null +++ b/docs/source/getting_started/bias/methods/inprocessing/rs_two_sided_fairness_fairrec_two_sided_fairness.rst @@ -0,0 +1,25 @@ +FairRec +----------- + +.. note:: + **Learning tasks:** Recommendation systems. + +Introduction +~~~~~~~~~~~~~~~~ +FairRec is an algorithm designed to ensure two-sided fairness in personalized recommendation systems on two-sided platforms. It aims to balance the interests of both producers and customers by guaranteeing a minimum exposure for producers and ensuring that customers receive recommendations that are envy-free up to one item (EF1). + +Description +~~~~~~~~~~~~~~~~ +The FairRec algorithm addresses the problem of fair allocation in the context of recommendation systems. The goal is to allocate products to customers in a way that ensures fairness for both producers and customers. The main characteristics of FairRec include: + +- **Producer Fairness**: Ensuring that each producer receives a minimum level of exposure, which is at least their maximin share (MMS) of exposure. +- **Customer Fairness**: Ensuring that the recommendations are envy-free up to one item (EF1) for all customers. + +The algorithm operates in two phases: + +1. **First Phase**: Ensures EF1 among all customers and tries to provide a minimum guarantee on the exposure of the producers. +2. **Second Phase**: Ensures that exactly k products are allocated to each customer while maintaining EF1 for customers. + +References +~~~~~~~~~~~~~~~~ +1. Patro, Gourab K., et al. "Fairrec: Two-sided fairness for personalized recommendations in two-sided platforms." Proceedings of The Web Conference 2020. 2020. \ No newline at end of file diff --git a/docs/source/getting_started/bias/mitigation.rst b/docs/source/getting_started/bias/mitigation.rst index bcac69cf..f3cbfda4 100644 --- a/docs/source/getting_started/bias/mitigation.rst +++ b/docs/source/getting_started/bias/mitigation.rst @@ -1,3 +1,4 @@ +======= Mitigation ========== @@ -5,51 +6,49 @@ Mitigation This page is currently under construction. Please check back later for updates. -.. contents:: **Contents:** - :depth: 2 +.. note:: + Bias mitigation can be approached through **pre-processing**, **in-processing**, and **post-processing** methods. -Introduction ------------- +Bias in AI systems can lead to systematic disadvantages for certain individuals or groups. To address and reduce these biases, several mitigation methods can be employed throughout the development process, from data generation to model deployment. This document outlines various techniques and strategies for mitigating bias in AI systems. -Bias is defined as an unwanted prejudice in the decisions made by an AI system that systematically disadvantages a person or group. Various types of bias can exist and may be unintentionally introduced into algorithms at any stage of the development process, whether during data generation or model building. +**Pre-processing Methods** - In order to measure whether a system treats different groups of people equally, we can follow two approaches: **equality of outcome** and **equality of opportunity**. +Pre-processing techniques aim to mitigate bias by transforming the data before it is used to train a model. This can include: -When we select **equality of outcome**, we ask that all subgroups have equal outcomes. For example, in a recruitment context, we may require that the percentage of applicants hired is consistent across groups (e.g. we want to hire 5% of all female applicants and 5% of all male applicants). Mathematically, this means that the likelihood of a positive outcome is equal for members of each group (regardless of the ground-truth labels): +- **Reweighting**: Adjusting the weights of data points to ensure balanced representation across groups. +- **Resampling**: Over-sampling underrepresented groups or under-sampling overrepresented groups to achieve a balanced dataset. +- **Data Augmentation**: Generating synthetic data to bolster the representation of minority groups. +- **Fair Representation Learning**: Learning new representations of data that remove sensitive information while retaining useful information for prediction. -.. math:: - P(\hat{Y} = 1 | G = a) = P(\hat{Y} = 1 | G = b) \quad \forall a, b +**In-processing Methods** -that is, the probability of a positive outcome is the same for all groups. +In-processing techniques modify the learning algorithm itself to reduce bias during the model training phase. This can include: -When we select **equality of opportunity**, we ask that all subgroups are given the same opportunity of outcomes. For example, if we have a face recognition algorithm, we may want the classifier to perform equally well for all ethnicities and genders. Mathematically, the probability of a person in the positive class being correctly assigned a positive outcome and the probability of a person in a negative class being incorrectly assigned a positive outcome should both be the same for privileged and unprivileged group members. In this case, ground-truth labels are used to define the groups, and the following condition should hold: +- **Adversarial Debiasing**: Training the model in conjunction with an adversary that penalizes the model for producing biased predictions. +- **Fairness Constraints**: Incorporating constraints that enforce fairness criteria directly into the optimization objective of the learning algorithm. +- **Regularization Techniques**: Adding regularization terms to the loss function that penalize bias. -.. math:: - P(\hat{Y} = 1 | Y = y, G = a) = P(\hat{Y} = 1 | Y = y, G = b) \quad \forall a, b ~~and~~ y \in \{0, 1\} +**Post-processing Methods** -that is, the probability of a positive outcome is the same for all groups, given the ground-truth labels. +Post-processing techniques adjust the predictions of the trained model to mitigate bias. This can include: -Pre-processing --------------- +- **Calibrated Equalized Odds**: Adjusting the decision thresholds for different groups to achieve equalized odds across groups. +- **Reject Option Classification**: Allowing uncertain predictions to be reconsidered, particularly for disadvantaged groups, to improve fairness. +- **Output Adjustment**: Modifying the output probabilities to ensure fair treatment across groups. -... + .. toctree:: + :maxdepth: 1 -Inprocessing ------------- -... - - -Post-processing ---------------- - -... + methods/preprocessing + methods/inprocessing + methods/postprocessing Summary Table ------------- -The following table summarizes the metrics that can be used to measure bias in different types of tasks. +The following table summarizes the bias mitigation methods and their applicability at different Machine Learning (ML) tasks. -.. csv-table:: Bias Metrics - :header: "Class", "Task", "Metrics", "Ideal Value", "Fair Area", "Description" - :file: bias_metrics.csv +.. csv-table:: **Bias Mitigation Methods** + :header: "Type Strategy", "Method name", "Binary Classification", "Multi Classification", "Regression", "Clustering", "Recommender Systems" + :file: bias_mitigation.csv \ No newline at end of file diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst index 586f62cc..e48d7d0a 100644 --- a/docs/source/getting_started/index.rst +++ b/docs/source/getting_started/index.rst @@ -49,5 +49,17 @@ This section will guide you through the installation of the `holisticai` open-so install quickstart.ipynb datasets - bias/index - explainability/index + explainability + + bc_exp_grad_grid_search_exponentiated_gradient_reduction + bc_exp_grad_grid_search_grid_search + bc_meta_fair_classifier_rho_fair + bc_prejudice_remover_prejudice_remover_regularizer + c_fair_k_center_fair_k_center + c_fair_k_median_fair_k_median + c_fairlet_clustering_fairlet_decomposition + c_variational_fair_clustering_variational_fair_clustering + mc_fair_scoring_classifier_fairscoringsystems + rs_blind_spot_aware_blind_spot_aware_matrix_factorization + rs_popularity_propensity_propensity_scored_recommendations + rs_two_sided_fairness_fairrec_two_sided_fairness \ No newline at end of file