The purpose of this toolkit is to facilitate the adoption of Veritas Methodology on Fairness and Transparency Assessment and spur industry development. It will also benefit customers by improving the fairness and transparency of financial services delivered by AIDA systems.

ModelContainer()

veritastool.model.model_container.ModelContainer(y_true=None, p_grp=None, model_type='classification', y_pred=None, y_prob=None, x_train=None, protected_features_cols=None, y_train=None, x_test=None, model_object=None, train_op_name='fit', predict_op_name='predict', sample_weight=None, model_name='auto', pos_label=[1], neg_label=None, up_grp=None, predict_proba_name='predict_proba')

Helper class that holds the model parameters and datasets required for computations in all use cases.

Attributes	Description
y_true: array of shape (n_samples,), default=None	Testing data labels.
p_grp: dictionary of lists, default=None	Assignment of privileged group for protected variables. There are two ways to perform the assignment: (1) Manual assignment, e.g., p_grp = {'gender': [1, 2]} (2) Auto assignment with policy, e.g., p_grp = {'gender': 'max_bias'}. There are three supported polices 'maj_min', 'maj_rest' and 'max_bias'. maj_min and maj_rest assigns the majority group, while max_bias assigns the best performing group based on primary fairness metric as the privileged group. Automatically assigned group selected must have both positive labels and negative labels more than a configurable value min_samples_threshold. If such a group is not found, a warning message will be displayed that the results may not be robust. For uplift model, same policy is applied for a protected variable to both models. For multi-class classification fairness diagnosis, auto assignment with policy is not supported.
model_type: string, default='classification'	The type of model to be evaluated. Supported model types are 'classification', 'regression', and 'uplift'.
model_name: string, default='auto'	Used for naming the model artifact JSON file in compile function.
y_pred: array of shape (n_samples,), default=None	Predicted targets as returned by classifier.
y_prob: array or pandas Series of shape (n_samples, 1) or pandas DataFrame of shape (n_samples, L), default=None	Predicted probabilities as returned by classifier. For binary classification fairness diagnosis, L < 2. For uplift model fairness diagnosis, L = 4. For multi-class classification fairness diagnosis, L > 2 If L > 1, y_prob must be passed as pandas DataFrame and column order of class probabilities in y_prob should be same as classes_ attribute of model object.
y_train: array of shape (m_samples,)	Training data labels.
protected_features_cols: pandas Dataframe of shape (n_samples, k), default=None	Subset of testing data features (x_test) containing only the protected variable columns. K = number of protected features This parameter is used for creating group and intersectional masks. If not provided, x_test will be used which must be a pandas dataframe.
train_op_name: string, default='fit'	The method used by the model_object to train the model. This training function should be memoryless which means that when called a second time the model parameters are reset first before the run. For e.g., scikit-learn's fit function.
predict_op_name: string, default='predict'	The method used by the model_object to predict the class labels.
sample_weight: array of shape (n_samples,), default=None	Used to assign different weight to each sample of testing data for performance and fairness metric computation. Sample weight is only applied to confusion matrix-based metrics (precision, equal opportunity etc) and regression metrics (wape, mape, rmse etc)
pos_label: array, default=[1]	For binary classification fairness diagnosis, these are lable values which are considered favorable in classification models. For all classification model types except uplift, the specified labels in pos_label are converted to 1 and rest to 0 if neg_label is not specified. For uplift, user is to provide 2 label names e.g. ['a', 'b'] in favourable label. The first will be mapped to treatment responded (TR) & second to control responded (CR). For multi-class classification fairness diagnosis, user must specify pos_label = None.
neg_label: array, default=None	For binary classification fairness diagnosis, these are label values which are considered unfavorable in classification models. For all classification model types except uplift, the specified labels in pos_label are converted to 0. For uplift, user is to provide 2 label names e.g. ['c', 'd'] in unfavourable label. The first will be mapped to treatment others (TN) & second to control others (CN). For multi-class classification fairness diagnosis (pos_label = None), specifying neg_label is not needed. If specified, value is not used.
x_train: pandas Dataframe of shape (m_samples, n_features) or string	Training dataset. m_samples refers to number of rows in the training dataset. String value refers to the dataset path where the dataset resides (e.g., HDFS URI). The loading of the dataset using the path string is to be handled using the Model Wrapper. The user can also pass their own processed data along with the processed label in case that x_train is a string (not available on local storage for the user).
x_test: pandas Dataframe or array of shape (n_samples, n_features) or string	Testing dataset features. String value refers to the dataset path where the dataset resides (e.g., HDFS URI). The loading of the dataset using the path string is to be handled using the Model Wrapper. If string, protected_feature parameter must be set. x_test is a required if protected_features_cols is not provided and p_grp is not None.
model_object: ML model object from libraries such as scikit-learn or ModelWrapper object	A fitted model object with three functions: 1. fit: required for training 2. predict: required for predicting class labels 3. predict_proba: required for prediction class probabilities
up_grp: dictionary of lists, default = None	Assignment of unprivileged group for protected variables. There are two ways to perform the assignment: (1) Manual assignment, e.g., up_grp = {'gender': [2,3]} (2) Auto assignment with policy: If a policy has been specified for p_grp of a protected variable, then specifying up_grp is not needed. If specified, value is not used.
predict_proba_op_name: string, default='predict_proba'	The method used by the model_object to predict the class probabilities.

Methods in ModelContainer class

check_protected_columns()	Check p_var, x_test and protected_feature_columns consistency.
check_data_consistency()	Check rows and columns are of consistent size across the various datasets and the number & match of the unique values.
Check_label_consistency()	Check if the labels and values in y_pred, y_train and y_true are consistent.
check_label_length()	Checks if the length of labels is correct according to the model_type.
clone(y_true, model_object, y_pred=None, y_prob=None, y_train=None, train_op_name='fit', predict_op_name ='predict', feature_imp=None, sample_weight=None, pos_label=[1], neg_label=None, predict_proba_op_name='predict_proba')	Clone ModelContainer object.

clone(y_true, model_object, y_pred=None, y_prob=None, y_train=None, train_op_name='fit', predict_op_name ='predict', feature_imp=None, sample_weight=None, pos_label=[1], neg_label=None, predict_proba_op_name='predict_proba')

Parameters	Description
y_true: array of shape (n_samples,)	Ground truth target values.
Model_object: Object	A blank model object used in the feature importance section for training and prediction.
y_pred: array of shape (n_samples,), default=None	Predicted targets as returned by classifier.
y_prob: array of shape (n_samples, L), default=None	Predicted probabilities as returned by classifier. For uplift models, L = 4. Else, L = 1. y_prob column orders should be ['TR', 'TN', 'CR', 'CN'] for uplift models.
y_train: array of shape (m_samples,), default=None	Ground truth for training data.
train_op_name: string, default='fit'	The method used by the model_object to train the model. By default, a sklearn model is assumed.
Predict_op_name: string, default='predict'	The method used by the model_object to predict the labels or probabilities. By default, a sklearn model is assumed. For uplift models, this method should predict the probabilities and for non-uplift models it should predict the labels.
sample_weight: array of shape (n_samples,), default=None	Used to normalize y_true & y_pred.
pos_label: array, default=[1]	Label values which are considered favorable. For all model types except uplift, converts the favourable labels to 1 and others to 0. For uplift, user is to provide 2 label names e.g. ['a', 'b'] in fav label. The first will be mapped to treatment responded (TR) & second to control responded (CR).
neg_label: array, default=None	Label values which are considered unfavorable. neg_label will only be used in uplift models. For uplift, user is to provide 2 label names e.g. ['c', 'd'] in unfavourable label. The first will be mapped to treatment rejected (TR) & second to control rejected (CR).
predict_proba_op_name: string, default='predict_proba'	The method used by the model_object to predict the probabilities. By default, a sklearn model is assumed.

Returns	Description
clone_obj: object	ModelContainer object

CreditScoring()

veritastool.usecases.credit_scoring.CreditScoring(model_params, fair_threshold, perf_metric_name='balanced_acc', fair_metric_name='auto', fair_concern='eligible', fair_priority='benefit', fair_impact='normal', fair_metric_type='difference', num _applicants=None, base_default_rate=None, fairness_metric_value_input={}, tran_row_num=[1], tran_max_sample=1, tran_pdp_feature=[], tran_pdp_target=None, tran_max_display=10, tran_features=[], tran_processed_data=None, tran_processed_label=None )

Class to diagnose fairness and transparency in a credit scoring application.

Attributes	Description
model_params: list containing 1 ModelContainer object	List containing model containers to be assessed in fairness and transparency diagnosis. Compulsory input for initialization.
fair_threshold: float or int, default = 80	Value between 0 and 100. If a float between 0 and 1 (not inclusive) is provided, it is used to benchmark against the primary fairness metric value to determine the fairness_conclusion. If an integer between 1 and 100 is provided, it is converted to a percentage and the p % rule is used to calculate the fairness threshold value.
perf_metric_name: string, default = 'balanced_acc'	Name of the primary performance metric to be used for computations in the evaluate() and/or compile() functions.
fair_metric_name: string, default = 'auto'	Name of the primary fairness metric to be used for computations in the evaluate() and/or compile() functions


fair_concern: string, default = 'eligible'	Used to specify a single fairness concern applied to all protected variables. Could be 'eligible' or 'inclusive' or 'both'.
Fair_priority: string, default = 'benefit'	Used to pick the fairness metric according to the Fairness Tree methodology. Could be 'benefit' or 'harm'.
Fair_impact: string, default = 'normal'	Used to pick the fairness metric according to the Fairness Tree methodology. Could be 'normal' or 'significant' or 'selective'.
Fair_metric_type, default = 'difference'	Used to specify if fairness metrics are 'difference' based or 'ratio' based.
num_applicants: dictionary of lists, default = None	Contains the number of rejected applicants for the privileged and unprivileged groups for each protected feature. E.g., {'gender': [10, 20], 'race': [12, 18]}
base_default_rate: dictionary of lists, default = None	Contains the base default rates for the privileged and unprivileged groups for each protected feature. E.g., {'gender': [10, 20], 'race': [12, 18]}
fairness_metric_value_input : dictionary	Contains the p_var and respective fairness_metric and value e.g., {'gender': {'fnr_parity': 0.2}}
tran_row_num: list/np.array/pd.series of integers, default = [1]	Contains the row numbers for which the user wants to see the local interpretability. (tran_row_num refers to row number mapping from the x_train data set and the input starts from 1.)
tran_max_sample: int/float, default = 1	Contains the count of rows user wants in the sample dataset as the shap computation is time and resource intensive process. If None is given, the entire dataset will be considered. A float value between 0 and 1 is considered as percentage. A value greater than 1 is considered as number of rows.
tran_pdp_features : list, default = []	Contains the list of features for which user wants to see the partial dependence plot. Can pass up-to 2 features. If none is passed, plot for top 2 features from global interpretability will be shown by default.
tran_pdp_target : string, default = None	Contains the target class to be used for partial dependence in the case of a multi-class model. (In all other cases, this input value is ignored.) If none is given, the first positive label value will be taken by default.
tran_max_display: int, default = 10	Contains the number of features user wants to see in output. A value of 0 is used for consideration of all features. If none is passed, 10 is considered as default.
tran_features: list of string, default = None	Contains the list of features user wants to see in the output.
tran_processed_data: Dataframe, default = None	The tran_processed_data is computed from x_train if x_train is a dataframe. In case x_train is a string (data is not available on local storage); user can use this parameter to pass the sample dataframe. This will be further used to create the shap values.
tran_processed_label: list, default = None	In case tran_processed_data is given, tran_processed_label is also required and is the respective y_train data. y_train is a list of np.array or list or pd.series with length equal to number of models in the container.

CustomerMarketing()

veritastool.usecases.customer_marketing.CustomerMarketing(model_params, fair_threshold, fair_is_pos_label_fav=None, perf_metric_name='emp_lift', fair_metric_name='auto', fair_concern='eligible', fair_priority='benefit', fair_impact='normal', fair_metric_type='difference', treatment_cost=None, revenue=None, fairness_metric_value_input={}, proportion_of_interpolation_fitting=1.0, tran_row_num=[1], tran_max_sample=1, tran_pdp_feature=[], tran_pdp_target=None, tran_max_display=10, tran_features=[], tran_processed_data=None, tran_processed_label=None)

Class to diagnose fairness and transparency in customer marketing applications.

Attributes	Description
model_params: list containing ModelContainer object(s)	List containing model containers to be assessed in fairness and transparency diagnosis. Compulsory input for initialization. If a single container is provided with model_type as 'classification', based on the value of parameter fair_is_pos_label_favourable either 'rejection' or 'propensity' modelling will be selected. Propensity: pos label is favourable Rejection: pos label us unfavourable. If 2 objects are provided, with the model_type flag as 'uplift', the first one corresponds to rejection model while the second one corresponds to propensity model. The same training and testing data is used for both the models.
fair_threshold: float or int, default = 80	Value between 0 and 100. If a float between 0 and 1 (not inclusive) is provided, it is used to benchmark against the primary fairness metric value to determine the fairness_conclusion. If an integer between 1 and 100 is provided, it is converted to a percentage and the p % rule is used to calculate the fairness threshold value.
fair_is_pos_label_favourable, default = None	Used to specify if the pos_label is favourable, which is used in the fairness metric tree for primary fairness metric suggestion.
perf_metric_name: string, default = 'emp_lift'	Name of the primary performance metric to be used for computations in the evaluate() and/or compile() functions.
fair_metric_name: string, default ='auto'	Name of the primary fairness metric to be used for computations in the evaluate() and/or compile() functions
fair_concern: string, default='eligible'	Used to specify a single fairness concern applied to all protected variables. Could be 'eligible' or 'inclusive' or 'both'.
fair_priority: string, default='benefit'	Used to pick the fairness metric according to the Fairness Tree methodology. Could be 'benefit' or 'harm'
fair_impact: string, default='normal'	Used to pick the fairness metric according to the Fairness Tree methodology. Could be 'normal' or 'significant' or 'selective'
fair_metric_type, default = 'difference'	Used to specify if fairness metrics are 'difference' based or 'ratio' based.
treatment_cost: int or float, default=None	Cost of the marketing treatment per customer
revenue: int or float, default=None	Revenue gained per customer
fairness_metric_value_input : dictionary	Contains the p_var and respective fairness_metric and value e.g. {'gender': {'emp_lift': 0.158}}
proportion_of_interpolation_fitting: float between 0.8 and 1.0	Used to specify the resolution of interpolating the approximate functions for performance and fairness metrics in Trade-off Analysis. Resolution is the number of threshold bins to be used and is specified as proportion of the number of samples
tran_row_num: list/np.array/pd.series of integers, default = [1]	Contains the row numbers for which the user wants to see the local interpretability. (tran_row_num refers to row number mapping from the x_train data set and the input starts from 1.)
tran_max_sample: int/float, default = 1	Contains the count of rows user wants in the sample dataset as the shap computation is time and resource intensive process. If none is given, the entire dataset will be considered. A float value between 0 and 1 is considered as percentage. A value greater than 1 is considered as number of rows.
tran_pdp_features : list, default = []	Contains the list of features for which user wants to see the partial dependence plot. Can pass up-to 2 features. If none is passed, plot for top 2 features from global interpretability will be shown by default.
tran_pdp_target : string, default = None	Contains the target class to be used for partial dependence in the case of a multi-class model. (In all other cases, this input value is ignored.) If none is given, the first positive label value will be taken by default.
tran_max_display: int, default = 10	Contains the number of features user wants to see in output. A value of 0 is used for consideration of all features. If none is passed, 10 is considered as default.
tran_features: list of string, default = None	Contains the list of features user wants to see in the output.
tran_processed_data: Dataframe, default = None	The tran_processed_data is computed from x_train if x_train is a dataframe. In case x_train is a string (data is not available on local storage); user can use this parameter to pass the sample dataframe. This will be further used to create the shap values.
tran_processed_label: list, default = None	In case tran_processed_data is given, tran_processed_label is also required and is the respective y_train data. y_train is a list of np.array or list or pd.series with length equal to number of models in the container.

PredictiveUnderwriting()

veritastool.usecases.predictive_underwriting.PredictiveUnderwriting(model_params, fair_threshold, perf_metric_name = 'balanced_acc', fair_metric_name='auto', fair_concern='eligible', fair_priority='benefit', fair_impact='normal', fair_metric_type = 'difference', fairness_metric_value_input={}, tran_row_num=[1], tran_max_sample=1, tran_pdp_feature=[], tran_pdp_target=None, tran_max_display=10, tran_features=[], tran_processed_data=None, tran_processed_label=None)

Class to diagnose fairness and transparency in a predictive underwriting application.

Attributes	Description
model_params: list containing 1 ModelContainer object	List containing model containers to be assessed in fairness and transparency diagnosis. Compulsory input for initialization.
fair_threshold: float or int, default = 80	Value between 0 and 100. If a float between 0 and 1 (not inclusive) is provided, it is used to benchmark against the primary fairness metric value to determine the fairness_conclusion. If an integer between 1 and 100 is provided, it is converted to a percentage and the p % rule is used to calculate the fairness threshold value.
perf_metric_name: string, default = 'balanced_acc'	Name of the primary performance metric to be used for computations in the evaluate() and/or compile() functions.
fair_metric_name: string, default = auto'	Name of the primary fairness metric to be used for computations in the evaluate() and/or compile() functions


fair_concern: string, default = 'eligible'	Used to specify a single fairness concern applied to all protected variables. Could be 'eligible' or 'inclusive' or 'both'.
fair_priority: string, default = 'benefit'	Used to pick the fairness metric according to the Fairness Tree methodology. Could be 'benefit' or 'harm'.
fair_impact: string, default = 'normal'	Used to pick the fairness metric according to the Fairness Tree methodology. Could be 'normal' or 'significant' or 'selective'.
fair_metric_type, default = 'difference'	Used to specify if fairness metrics are 'difference' based or 'ratio' based.
fairness_metric_value_input : dictionary	Contains the p_var and respective fairness_metric and value e.g. {'gender': {'fnr_parity': 0.2}}
tran_row_num: list/np.array/pd.series of integers, default = [1]	Contains the row numbers for which the user wants to see the local interpretability. (tran_row_num refers to row number mapping from the x_train data set and the input starts from 1.)
tran_max_sample: int/float, default = 1	Contains the count of rows user wants in the sample dataset as the shap computation is time and resource intensive process. If none is given, the entire dataset will be considered. A float value between 0 and 1 is considered as percentage. A value greater than 1 is considered as number of rows.
tran_pdp_features : list, default = []	Contains the list of features for which user wants to see the partial dependence plot. Can pass up-to 2 features. If none is passed, plot for top 2 features from global interpretability will be shown by default.
tran_pdp_target : string, default = None	Contains the target class to be used for partial dependence in the case of a multi-class model. (In all other cases, this input value is ignored.) If none is given, the first positive label value will be taken by default.
tran_max_display: int, default = 10	Contains the number of features user wants to see in output. A value of 0 is used for consideration of all features. If none is passed, 10 is considered as default.
tran_features: list of string, default = None	Contains the list of features user wants to see in the output.
tran_processed_data: Dataframe, default = None	The tran_processed_data is computed from x_train if x_train is a dataframe. In case x_train is a string (data is not available on local storage); user can use this parameter to pass the sample dataframe. This will be further used to create the shap values.
tran_processed_label: list, default = None	In case tran_processed_data is given, tran_processed_label is also required and is the respective y_train data. y_train is a list of np.array or list or pd.series with length equal to number of models in the container.

BaseClassification()

veritastool.usecases.base_classification.BaseClassification(model_params, fair_threshold, fair_is_pos_label_fav = True, perf_metric_name = 'balanced_acc', fair_metric_name='auto', fair_concern='eligible', fair_priority='benefit', fair_impact='normal', fair_metric_type = 'difference', fairness_metric_value_input={}, tran_row_num=[1], tran_max_sample=1, tran_pdp_feature=[], tran_pdp_target=None, tran_max_display=10, tran_features=[], tran_processed_data=None, tran_processed_label=None )

Class to diagnose fairness and transparency in a generic classification type application. Supports both binary fairness assessment and multi-class fairness assessment.

Attributes	Description
model_params: list containing 1 ModelContainer object	List containing model containers to be assessed in fairness and transparency diagnosis. Compulsory input for initialization.
fair_threshold: float or int, default = 80	Value between 0 and 100. If a float between 0 and 1 (not inclusive) is provided, it is used to benchmark against the primary fairness metric value to determine the fairness_conclusion. If an integer between 1 and 100 is provided, it is converted to a percentage and the p % rule is used to calculate the fairness threshold value.
fair_is_pos_label_fav: boolean, default = True	Used to indicate if positive label specified is favourable for the classification use case. If True, 1 is specified to be favourable and 0 as unfavourable.
perf_metric_name: string, default = 'balanced_acc'	Name of the primary performance metric to be used for computations in the evaluate() and/or compile() functions.
fair_metric_name: string, default = 'auto'	Name of the primary fairness metric to be used for computations in the evaluate() and/or compile() functions
fair_concern: string, default = 'eligible'	Used to specify a single fairness concern applied to all protected variables. Could be 'eligible' or 'inclusive' or 'both'.


fair_priority: string, default = 'benefit'	Used to pick the fairness metric according to the Fairness Tree methodology. Could be 'benefit' or 'harm'.
fair_impact: string, default = 'normal'	Used to pick the fairness metric according to the Fairness Tree methodology. Could be 'normal' or 'significant' or 'selective'.
fair_metric_type, default = 'difference'	Used to specify if fairness metrics are 'difference' based or 'ratio' based.
fairness_metric_value_input : dictionary	Contains the p_var and respective fairness_metric and value e.g. {'gender': {'fnr_parity': 0.2}}
tran_row_num: list/np.array/pd.series of integers, default = [1]	Contains the row numbers for which the user wants to see the local interpretability. (tran_row_num refers to row number mapping from the x_train data set and the input starts from 1.)
tran_max_sample: int/float, default = 1	Contains the count of rows user wants in the sample dataset as the shap computation is time and resource intensive process. If none is given, the entire dataset will be considered. A float value between 0 and 1 is considered as percentage. A value greater than 1 is considered as number of rows.
tran_pdp_features : list, default = []	Contains the list of features for which user wants to see the partial dependence plot. Can pass up-to 2 features. If none is passed, plot for top 2 features from global interpretability will be shown by default.
tran_pdp_target : string, default = None	Contains the target class to be used for partial dependence in the case of a multi-class model. (In all other cases, this input value is ignored.) If none is given, the first positive label value will be taken by default.
tran_max_display: int, default = 10	Contains the number of features user wants to see in output. A value of 0 is used for consideration of all features. If none is passed, 10 is considered as default.
tran_features: list of string, default = None	Contains the list of features user wants to see in the output.
tran_processed_data: Dataframe, default = None	The tran_processed_data is computed from x_train if x_train is a dataframe. In case x_train is a string (data is not available on local storage); user can use this parameter to pass the sample dataframe. This will be further used to create the shap values.
tran_processed_label: list, default = None	In case tran_processed_data is given, tran_processed_label is also required and is the respective y_train data. y_train is a list of np.array or list or pd.series with length equal to number of models in the container.

BaseRegression()

veritastool.usecases.credit_scoring.BaseRegression(model_params, fair_threshold, perf_metric_name = 'balanced_acc', fair_metric_name='auto', fair_concern='eligible', fair_priority='benefit', fair_impact='normal', fair_metric_type = 'difference', fairness_metric_value_input={}, tran_row_num=[1], tran_max_sample=1, tran_pdp_feature=[], tran_pdp_target=None, tran_max_display=10, tran_features=[], tran_processed_data=None, tran_processed_label=None )

Class to diagnose fairness and transparency in a generic regression type application.

Attributes	Description
model_params: list containing 1 ModelContainer object	List containing model containers to be assessed in fairness and transparency diagnosis. Compulsory input for initialization.
fair_threshold: float or int, default = 80	Value between 0 and 100. If a float between 0 and 1 (not inclusive) is provided, it is used to benchmark against the primary fairness metric value to determine the fairness_conclusion. If an integer between 1 and 100 is provided, it is converted to a percentage and the p % rule is used to calculate the fairness threshold value.
perf_metric_name: string, default = 'balanced_acc'	Name of the primary performance metric to be used for computations in the evaluate() and/or compile() functions.
fair_metric_name: string, default = 'auto'	Name of the primary fairness metric to be used for computations in the evaluate() and/or compile() functions


fair_concern: string, default = 'eligible'	Used to specify a single fairness concern applied to all protected variables. Could be 'eligible' or 'inclusive' or 'both'.
fair_priority: string, default = 'benefit'	Used to pick the fairness metric according to the Fairness Tree methodology. Could be 'benefit' or 'harm'.
fair_impact: string, default = 'normal'	Used to pick the fairness metric according to the Fairness Tree methodology. Could be 'normal' or 'significant' or 'selective'.
fair_metric_type, default = 'difference'	Used to specify if fairness metrics are 'difference' based or 'ratio' based.
fairness_metric_value_input : dictionary	Contains the p_var and respective fairness_metric and value e.g., {'gender': {'fnr_parity': 0.2}}
tran_row_num: list/np.array/pd.series of integers, default = [1]	Contains the row numbers for which the user wants to see the local interpretability. (tran_row_num refers to row number mapping from the x_train data set and the input starts from 1.)
tran_max_sample: int/float, default = 1	Contains the count of rows user wants in the sample dataset as the shap computation is time and resource intensive process. If none is given, the entire dataset will be considered. A float value between 0 and 1 is considered as percentage. A value greater than 1 is considered as number of rows.
tran_pdp_features : list, default = []	Contains the list of features for which user wants to see the partial dependence plot. Can pass up-to 2 features. If none is passed, plot for top 2 features from global interpretability will be shown by default.
tran_pdp_target : string, default = None	Contains the target class to be used for partial dependence in the case of a multi-class model. (In all other cases, this input value is ignored.) If none is given, the first positive label value will be taken by default.
tran_max_display: int, default = 10	Contains the number of features user wants to see in output. A value of 0 is used for consideration of all features. If none is passed, 10 is considered as default.
tran_features: list of string, default = None	Contains the list of features user wants to see in the output.
tran_processed_data: Dataframe, default = None	The tran_processed_data is computed from x_train if x_train is a dataframe. In case x_train is a string (data is not available on local storage); user can use this parameter to pass the sample dataframe. This will be further used to create the shap values.
tran_processed_label: list, default = None	In case tran_processed_data is given, tran_processed_label is also required and is the respective y_train data. y_train is a list of np.array or list or pd.series with length equal to number of models in the container.

ModelWrapper()

veritastool.model.ModelWrapper(model_obj=None, model_file=None, output_file=None)

Serves as a template for users to define the model_object to comply with the requirements of the toolkit. If a model_object already satisfies the requirements of having a classes_ attribute and methods for training, predicting label, and predicting probabilities a model wrapper may not be required.

Abstract Base class to provide an interface to support non-python and python models. Also used to include any required data preprocessing and postprocessing.

Attributes	Description
model_obj: object, default=None	Model object to be diagnosed for fairness and transparency.
model_file: string, default=None	Path to the model file. e.g., '/home/model.pkl'
output_file: string, default=None	Path to which the prediction results will be written to in the form of a csv file. e.g., '/home/results.csv"
classes_: list, default=[]	Classes to be predicted by the model_obj. Note: The column order of y_prob from predict_proba method output and that input to ModelContainer should be aligned with the order of classes specified here.

Methods in ModelWrapper class

Method	Description
fit	This method is a template for user to specify a custom fit() method that trains the model and saves it to self.model_file. This training function should be memoryless which means that when called a second time the model parameters are reset first before the run. For e.g., Scikit-learn's fit function. An example is as follows: def fit(x_train, y_train): train_cmd = 'train_func --train {x_train} {y_train} {self.model_file}' import subprocess process = subprocess.Popen(train_cmd.split(), stdout=subprocess.PIPE) output, error = process.communicate()
predict	This method is a template for user to specify a custom predict() method that uses the model saved in self.model_file to make label predictions on the test dataset. An example is as follows: def predict(x_test): pred_cmd = 'pred_func --predict {self.model_file} {x_test} {self.output_file}' import subprocess process = subprocess.Popen(pred_cmd.split(), stdout=subprocess.PIPE) output, error = process.communicate() return pd.read_csv(output_file) Note: Any preprocessing needed after reading output_file required has to be done too
predict_proba	This method is a template for user to specify a custom predict_proba() method that uses the model saved in self.model_file to make probability predictions on the test dataset. An example is as follows: def predict_proba(x_test): proba_cmd = 'pred_func --predict {self.model_file} {x_test} {self.output_file}' import subprocess process = subprocess.Popen(proba_cmd.split(), stdout=subprocess.PIPE) output, error = process.communicate() return pd.read_csv(output_file) Note: The column order of class probabilities from predict_proba output has to be aligned with the order of classes in classes_. This processing can be done in the predict_proba function after reading output_file.
_sampling	This method performs sampling of the x_train, y_train, x_test. The sampling mode can be specified by 'mode' parameter. Mode values supported are 'first' and 'per_label'. First mode selects the first n rows based on the value of parameter 'size' (default = 100) 'per_label' model groups by labels and chooses 'size' number of rows from each label.
check_fit_predict	This method performs a check on the correct working of ModelWrapper object as required by the diagnosis toolkit. It internally calls _sampling and executes fit, predict, and predict_proba methods to check for errors. If all pass 1 is returned else 0 is returned.

fit(x_train, y_train)

Parameters	Description
x_train: pandas Dataframe of shape (m_samples, n_features) or string	Training dataset features. m_samples refers to number of rows in the training dataset. The string refers to the dataset path acceptable by the model (e.g., HDFS URI).
y_train: array of shape (m_samples,)	Training dataset labels.

predict(x_test)

Parameters	Description
x_test: pandas Dataframe or array of shape (n_samples, n_features) or string	Testing dataset. The string refers to the dataset path acceptable by the model (e.g., HDFS URI).

predict_proba(x_test)

Parameters	Description
x_test : pandas Dataframe or array of shape (n_samples, n_features) or string	Testing dataset. The string refers to the dataset path acceptable by the model (e.g., HDFS URI).

check_fit_predict(x_train, y_train, x_test, y_test, mode='per_label', size=100)

Parameters	Description
x_train: pandas Dataframe of shape (m_samples, n_features) or string	Training dataset features. m_samples refers to number of rows in the training dataset. The string refers to the dataset path acceptable by the model (e.g., HDFS URI).
y_train: array of shape (m_samples,)	Training dataset labels.
x_test: pandas Dataframe or array of shape (n_samples, n_features) or string	Testing dataset features. The string refers to the dataset path acceptable by the model (e.g., HDFS URI).
y_test: array of shape (n_samples,)	Testing dataset labels.
mode: str, default = 'per_label'	'first' or 'per_group'
size: int, default = 100	Row count to sample

**Note: If there is a new ModelWrapper class defined by user, user will need to update the init.py file to import the new class in the custom subfolder of the toolkit.

NewMetric()

veritastool.metrics.newmetric.NewMetric(metric_type, metric_group, metric_name, metric_definition, metric_parity_ratio, enable_flag)

Base class to add new metrics to the library. It allows to create custom fairness and performance metrics.

Attributes	Description
metric_type: string	'fair' or 'perf'.
metric_group: string	'classification', 'regression' or 'uplift'.
metric_name: string	Internal name of metric to be used for computation and saving results.
metric_definition: string	Full name of the metric to be shown on printed outputs.
metric_short_name: string	Name to shown in the fairness widget.
metric_difference_ratio: string	'difference' or 'ratio' based metric. If metric_type = 'perf', this value is not used.
metric_equiv_perf_metric: string	The fairness to performance metric mapping. If metric_type = 'perf', this value is not used.
metric_direction: string	Whether favorable outcome is achieved by higher value or lower values of the metric, i.e., "higher" or "lower".
metric_reqt: string	Metric requirement/dependency, i.e., "y_pred" or "y_prob".
enable_flag: boolean	Whether the metric can be a primary metric.

Methods in NewMetric class

Method	Description
compute()	Returns tuple of metric value and privileged group value

compute()

Returns	Description
metric_value: float	Metric value
pr_p: float	Privileged group value, applicable if the custom metric is fairness metric

**Note: Custom new metric needs to be created by inheriting NewMetric class. Definition of new metric should be done before creating use case object. Please note that NewMetrics class should be imported to the working directory as well.

Fairness.evaluate()

veritastool.principles.fairness.Fairness.evaluate(visualize=False, output=True, n_threads=1, seed=None, disable=[])

Computes the percentage count of subgroups. Computes performance metrics and with confidence intervals, calibration score, individual fairness. Computes group fairness metrics with confidence intervals and a fairness conclusion for each normal & intersectional fairness protected variables.

Parameters	Description
visualize: boolean, default=False	Flag to display a widget for visualizing the results from evaluate()
output: boolean, default=True	Flag to print out the results of evaluate() in the console. This flag will be False if visualize=True.
n_threads: int, default=1	Number of threads to use for multithreading.
seed: int, default=None	Used to initialize the random number generator.
disable: list, default=[]	Used to specify which sections to skip. Available options are 'perf_dynamic', 'calibration_curve' and 'individual_fair'. E.g., disable = ['perf_dynamic', 'calibration_curve', 'individual_fair']

CustomerMarketing and BaseRegression classes do not support individual fairness.

**Note: The outcome is calculated based on your inputs and is provided for informational purposes only. Should you decide to act upon the information herein, you do so at your own risk and Veritas Toolkit will not be liable or responsible in any way.

Fairness.compile()

veritastool.principles.fairness.Fairness.compile(disable=[], n_threads=1)

Compile saves the results from fairness and transparency diagnosis in a json file. It checks the run status of API function and triggers them if not run yet.

Parameters

Description

disable: list, default=[]

Used to specify which API functions and/or their sections to skip. Can include 'evaluate', 'tradeoff', 'feature_importance', 'explain'.

E.g., disable = ['tradeoff', 'feature_importance', 'explain']

If entire Fairness diagnosis to be skipped, user may specify disable = ['evaluate']

Transparency diagnosis can also be skipped entirely or partially, i.e., disable = ['explain'] OR disable = ['explain>interpret']

(Note: Transparency results once calculated will be stored in the JSON output.)

If individual sections are to be skipped, the syntax has to be specified in the following way:

disable = ['evaluate>perf_dynamic|calibration_curve|individual_fair', 'feature_importance>correlation']

n_threads: int, default=1

Number of threads to use for multithreading.

**Note: Default model artifact name written to file will be model_artifact_{model_name}_yyyymmdd_hhmm.json

If there is more than 2 model. Model name comes from the model_name of first ModelContainer object.

Fairness.tradeoff()

veritastool.principles.fairness.Fairness.tradeoff(output=True, n_threads=1, sigma=0)

Computes the trade-off between performance and fairness over a range of threshold values.

This is used to suggest the thresholds to use for maximum model performance in 3 scenarios. Single threshold for privileged and unprivileged groups, Separate thresholds and Separate thresholds under neutral fairness constraint (0.001) . Although only the max performance case is printed out, all the other cases are computed and saved too.

Parameters	Description
output: boolean, default=True	Flag to print out the results of tradeoff() in the console.
n_threads: int, default=1	Number of currently active threads of a job.
sigma: float or int , default=0	Standard deviation for Gaussian kernel for smoothing the contour lines of primary fairness metric. When sigma <= 0, smoothing is turn off. Suggested to try sigma = 3 or above if noisy contours are observed.

Fairness.feature_importance()

veritastool.principles.fairness.Fairness.feature_importance(output=True, n_threads=1)

Trains models using the leave-one-variable-out method for each protected variable and computes the performance and fairness metrics each time to assess the impact of those variables.

The function runs a correlation analysis and displays any surrogates detected. If no surrogates are found, the output will show a correlation matrix of the top 3 variables that are most highly correlated with each protected variable.

Parameters	Description
output: boolean, default=True	Flag to print out the results of feature_importance() in the console.
n_threads: int, default=1	Number of currently active threads of a job.
correlation_threshold: float, default = 0.7	To set the- correlation threshold used to detect surrogates. Surrogates are detected based on the first 20 features from the tran_top_features from transparency SHAP analysis.
disable: list, default=[]	Used to specify which sections to skip. Available option is 'correlation' only. E.g., disable=['correlation']

**Note: Treatment of variables in Phi_K correlation analysis depends on dtype. If numerical, the values will be binned. If ordinal type, user will have to change the dtype to 'object' to be considered as a categorical variable.

Fairness.mitigate()

veritastool.principles.fairness.Fairness.mitigate(p_var=[], method=['reweigh'], cr_alpha=1, cr_beta=None, rw_weights=None, transform_x=None, transform_y=None, model_num=0)

Performs bias mitigation by the following preprocessing and postprocessing methods.

Reweigh: A preprocessing method which suggest sample weights for training data which is used retrain a model to improve fairness.
Source: https://aif360.readthedocs.io/en/latest/modules/generated/aif360.algorithms.preprocessing.Reweighing.html

The reweighting methods will be effective only if the loss function, primary and fairness metric of the model are aligned.

Correlate: A preprocessing method which transforms the training and testing data by removing correlation between sensitive features and non-sensitive features through linear transformations. These are used to retrain a model to improve fairness.
Source: https://fairlearn.org/v0.8/api_reference/fairlearn.preprocessing.html#fairlearn.preprocessing.CorrelationRemover

Threshold: A postprocessing method which suggests separate classification thresholds for privileged and unprivileged groups to improve fairness.

**Note: While these methods can help reduce unfairness, please note that they do not guarantee a change in the fairness conclusion from unfair to fair

In addition to the base mitigation, which applies bias mitigation on the training and test data, the Correlate and Reweigh methods also support input transformation (transform mitigation). This enables the same mitigation technique to be applied to a new dataset that was used during the base mitigation.

**Note: Please note that while the Correlate method only requires input features and not labels in the new dataset for input transformation, the Reweigh method requires both input features and labels.

In the case of transform mitigation, if some input values are missing, the mitigation will default to using the base mitigation that was applied to the training and testing data.

Parameters	Description
p_var: list of strings, default = []	Optional parameter. Protected variables to be considered for mitigation. Value for p_var must be a subset of p_var specified in ModelContainer() When set to None or not specified, all protected variables are considered.
method: list of strings, default = ['reweigh']	Optional parameter. Mitigation methods to be considered for mitigation. Allowed values are 'reweigh', 'threshold', 'correlate'. To consider all mitigation methods, user to specify method = ['reweigh', 'threshold', 'correlate'].
cr_alpha	Input for Correlate transform case. Correlate alpha parameter returned during the original mitigation.
cr_beta	Input for Correlate transform case. Correlate beta parameter returned during the base mitigation.
rw_weights	Input for Reweigh transform case. Reweigh parameters returned during the base mitigation.
transform_x	Input for Correlate and Reweigh transform case. New dataset features. For Reweigh, only the protected variable columns are required although all columns can be passed. For Correlate all columns are needed.
transform_y	Input for Reweigh transform case. New dataset labels.
model_num: int, default = 0	Used to specify the which model in model_params to be mitigated.

Base Mitigation can be applied as follows:

mitigated = pred_underwriting_obj.mitigate(p_var=['gender'], method=['threshold', 'reweigh', 'correlate'])

Note that for the Correlate method, all columns in the x_train dataset must be numerical. If any column is not numerical, the Correlate method will be skipped.

The Threshold method applies suggested thresholds and returns new predictions, which can be accessed using the following syntax:

y_pred_mitigated = mitigated['threshold'][0]

Reweigh method returns an array of sample weights for the training dataset which can accessed using the following syntax:

sample_weights_mitigated = mitigated['reweigh'][0]

Correlate method returns transformed x_train and x_test and cr_beta which can accessed using the following syntax:

x_train_mitigated = mitigated['correlate'][0]

x_test_mitigated = mitigated['correlate'][1]

beta = mitigated['correlate'][2]

Correlate method input transformation of a new dataset based on a base mitigation can be performed using the following syntax:

transform_mitigated = mitigate(p_var=['gender'], method=['correlate'], cr_alpha=0.9, cr_beta=beta, transform_x=new_dataset_df)

Reweigh method input transformation of a new dataset based on a base mitigation can be performed using the following syntax:

transform_mitigated = cre_sco_obj.mitigate(method=['reweigh'], rw_weights=group_weights, transform_x=x_test_sample, transform_y=y_true_sample)

**Notes:

1. Mitigate is not supported for BaseRegression.

2. The Threshold method for CustomerMarketing does not return new predictions.

3. Mitigate is not supported for intersectional protected variables.

Fairness.rootcause()

veritastool.principles.fairness.Fairness.rootcause(p_var=[], multi_class_target=None, model_num=0)

Computes relative importance of top 10 feature contributions towards unfairness measured between privileged and unprivileged groups by SHAP based demographic parity.

Parameters	Description
p_var: list of strings, default = []	Optional parameter. Protected variables to be considered for root cause analysis. Value for p_var must be a subset of p_var specified in ModelContainer(). When set to None or not specified, all protected variables are considered.
multi_class_target int, default = None	Label to use for comparison between privileged and unprivileged groups in root cause analysis. Only applicable for multi-class classification models. If not specified, the last label will be used.
model_num: int, default = 0	Used to specify the which model in model_params to be used for root cause analysis.

Fairness.get_prob_calibration_results()

veritastool.fairness.fairness.Fairness.get_prob_calibration_results()

Gets the probability calibration results

Returns	Description
dictionary	A dictionary with below keys and values: 'prob_true': the ground truth values split into 10 bins from 0 to 1 'prob_pred': the mean predicted probability in each bin 'score': the brier loss score

Fairness.get_perf_metrics_results()

veritastool.fairness.fairness.Fairness.get_perf_metrics_results()

Gets the performance metrics results

Returns	Description
dictionary	A dictionary with keys as the performance metric name and values as the metric value together with confidence interval

Fairness.get_fair_metrics_results()

veritastool.fairness.fairness.Fairness.get_fair_metrics_results()

Gets the fairness metrics results

Returns	Description
dictionary	A dictionary with keys as the fairness metric name and values as the metric value together with confidence interval

Fairness.get_tradeoff_results()

veritastool.fairness.fairness.Fairness.get_tradeoff_results()

Gets the tradeoff results

Returns

Description

dictionary

A dictionary with below keys and values:
    protected variable name as key to split result values for each protected variable
    'fair_metric_name': fairness metric name
    'perf_metric_name': performance metric name
    'fair': array of shape (n, n*) of fairness metric values
    'perf': array of shape (n, n*) of performance metric values
    'th_x': array of shape (n*, ) of thresholds on x axis
    'th_y': array of shape (n*, ) of thresholds on y axis
    'max_perf_point': maxiumn performance point on the grid
    'max_perf_single_th': maxiumn performance point on the grid with single threshold
    'max_perf_neutral_fair': maxiumn performance point on the grid with neutral fairness
    *n is defined by tradeoff_threshold_bins in config

Fairness.get_loo_results()

veritastool.fairness.fairness.Fairness.get_loo_results()

Gets the leave one out analysis results

Returns	Description
dictionary	A dictionary with below keys and values: protected variable name as key to split fairness result on each protected variable protected variable name as key to denote the removed protected variable array values denote the performance metric value, fairness metric value, fairness conclusion and suggestion

Fairness.get_correlation_results()

veritastool.fairness.fairness.Fairness.get_correlation_analysis_results()

Gets the correlation analysis results

Returns	Description
dictionary	A dictionary with below keys and values: 'feature_names': feature names for correlation analysis 'corr_values': correlation values according to feature names

Transparency.explain()

veritastool.principles.transparency.Transparency.explain(disable = [], local_row_num=None, output=True, model_num=None)

The Transparency explain function has four types of analysis: global interpretability, local interpretability, partial dependence analysis, and permutation importance analysis.

If the user provides tran_features, the global and local interpretability will be displayed as a pandas dataframe instead of a plot.

If the x_train input is a string, the user can pass their own processed data and processed labels in the use case object. In this case, no data sampling will be performed, and the user provided data will be used as-is.

Transparency analysis will be skipped in the following conditions:

1. Model_object is not provided

2. x_train/y_train is not provided

3. In case of x_train being a string, processed_data/processed_label is not provided

Permutation analysis will be skipped in the following conditions:

1. y_true is not provided

2. x_test is not provided

There are two primary ways to use the explain function:

1. Without local_row_num parameter:

1. When local_row_num parameter is not passed, all 4 transparency analysis will be executed for the latest model, unless the user has disabled this option.

2. If there are two or more models, the user can use the model_num parameter to view the appropriate plots.

3. The local interpretability will be performed for all rows from tran_row_num. However, the plot will be shown for the latest row number in the tran_row_num list. (tran_row_num refers to row number mapping from the x_train data set and the input starts from 1.)

4. If 'tran_row_num' is not provided, the default value for the local plot will be the first row.

2. With local_row_num parameter:

1. In this case, only the local plot or dataframe for the given row number and model number will be shown. (The disable argument is ignored in this case.)

2. With this option, the user can view multiple local plots as required, by appropriately using the local_row_num parameter.

3. Please note that since the explain function is optimized to generate the SHAP values only once per model, in certain cases, the local row number may not be available. In such cases, an appropriate warning message will be displayed.

Parameters	Description
disable: list, default = None	It gives a list of analysis that the user can skip. Accepted values: ['interpret', 'partial_dep', 'perm_imp'] Interpret disables both the local and global interpretability.
local_row_num: integer, default = None	It stores the value of the row number required to calculate local interpretability. (tran_row_num refers to row number mapping from the x_train data set and the input starts from 1.)
output: boolean, default = True	If output = True, the required plots will be shown to the user.
model_num: int, default = None	It holds the model number for which analysis has to be done.

This function does not return anything. This function outputs charts and generates a results dictionary as specified by user inputs.

Parameter Configurations

Inside the config.ini folder (../veritastool/config/config.ini), following parameter values have been set up. User can update these parameter values inside this file.

Parameters Name	Value	Description
fair_threshold_low	0	Minimum allowed value for 'fair_threshold' in CreditScoring & CustomerMarketing classes
fair_threshold_high	100	Minimum allowed value for 'fair_threshold' in CreditScoring & CustomerMarketing classes
fair_neutral_tolerance	0.001	The maximum value of tolerable deviation from fair condition of a given fairness metric
fair_neutral_tolerance_low	0	Minimum allowed value for 'fair_neutral_tolerance'
fair_neutral_tolerance_high	0.01	Maximum allowed value for 'fair_neutral_tolerance'
proportion_of_interpolation_fitting_low	0.8	Minimum allowed value for 'proportion_of_interpolation_fitting' of CustomerMarketing class 'proportion_of_interpolation_fitting' defines the resolution of interpolating the approximate functions for performance and fairness metrics in Trade-off Analysis (Uplift Model only). Resolution is the number of threshold bins to be used and is specified as proportion of the number of samples
proportion_of_interpolation_fitting_high	1.0	Maximum allowed value for 'proportion_of_interpolation_fitting' of CustomerMarketing class 'proportion_of_interpolation_fitting' defines the resolution of interpolating the approximate functions for performance and fairness metrics in Trade-off Analysis (Uplift Model only). Resolution is the number of threshold bins to be used and is specified as proportion of the number of samples
selection_threshold	0	threshold value applied to 'e-lift' scores for selecting the customers with higher scores than the value (Uplift Model only)
tradeoff_threshold_bins	500	Size of mesh grid in Trade-off analysis
uplift_threshold_proportion	0.7	Proportion of Min and max values of 'e-lift' scores for computing the range of mesh grid in Trade-off analysis (Uplift Model only)
perf_dynamics_array_size	100	Sample size to plot the Performance Dynamics chart
uplift_min_threshold	-0.3	Minimum value to plot the Performance Dynamics chart (Uplift Model only)
uplift_max_threshold	0.3	Maximum value to plot the Performance Dynamics chart (Uplift Model only)
classify_min_threshold	0.3	Minimum probability threshold for mesh grid in Trade-off Analysis & Performance Dynamics chart (Classification Model only)
classify_max_threshold	0.7	Maximum probability threshold for mesh grid in Trade-off Analysis & Performance Dynamics chart (Classification Model only)
correlation_threshold_low	0	Correlation threshold minimum value
correlation_threshold_high	1	Correlation threshold maximum value
k	50	Bootstrapping size for calculating the confidence intervals of metric values
decimals	3	Number of decimal places for values to be rounded off in the text output of API functions
permutation_additional	0.2	Additional percentage of features to be taken into consideration above the maximum display for computing permutation importance
min_samples_per_label	50	Minimum number of samples from each label for a group to be auto assigned as a privileged or unprivileged group for fairness diagnosis. If not met a warning is displayed.
correlation_bins	10	Number of bins for interval variables used for Phi_K correlation

Fairness Tree Visualization

Q1: Is positive label favorable?

This question helps to analyze the harms and benefits of the model based on the confusion matrix cohorts. The favorable labels are usually related to benefits and the misclassification of the labels could lead to harm. For example, TP and FP cohort of confusion matrix may include benefit if the positive label is favorable. Benefit is given to these cohorts due to the positive predictions. Misclassification should be considered in benefit and harm context also. Misclassified positive predictions may lead to some consequences. FP can include these consequences aka. harm where positive label is favorable. Therefore, understanding whether the positive target label of ground truth data is favorable or unfavorable helps to analyze the benefits and harms of the model. Harm and benefit analysis should be done by considering the own dynamics of each individual use case. Sometimes, the impact of harm or benefit could be minor. The impact of them should be examined carefully and be determined if they are negligible or not. The details of harm and benefit analysis for selected use cases is to be explained in Application to Business Use Cases.

Q2: Which is the priority in fairness measurement: harm or benefit as a result of the model?

This step helps the user to define fairness metrics under the harm or benefit priority. In Q1, the harm and benefit of the model are analyzed already. The user needs to decide which is the priority in the fairness context: harm or benefit. The user may want to assess fairness by harm or benefit. This choice shapes the numerator of the fairness metric to be suggested. If the harm is selected as a priority, the harm related cohorts of the confusion matrix are to be included in the numerator of the metric. Similarly, if the benefit is selected as a priority, the benefit related cohorts of the confusion matrix are to be included in the numerator of the metric. At the end of selection, there can be more than one numerator candidates for fairness metric, and they will be filtered based on the answers to next questions.

Q3: Which group do you concern more?

Similar to Q2, this step helps to choose the numerator of the fairness metrics. This step assesses the concern of the decision maker, which can be eligible, inclusive and both. It can be thought one more filter for the numerator of the fairness metrics. Until this step, Q2 already reduces the numerator of the fairness metric based on harm or benefit priority. On top of this selection, this step reduced the numerator to one based on fairness concern. Let's assume that favorable class has positive value in Q1, and benefit is selected as priority in Q2. Since the favorable class is positive, the positive predictions carry benefits, TP or FP. Please note that these benefits carried in TP and FP could be minor and negligible. Decision maker needs to analyze the harm and benefit of the particular use case carefully. If the concern is to focus on people who are eligible for the action due to the model, the favorable class prediction will be regarded; if the concern is to focus on including the people who are intervened for favorable action but not eligible, the unfavorable class will be regarded; if the concern is 'both', then the numerator which are suggested for both eligible and inclusive concern to be included. For both concern, derived metrics are introduced in the tree, which includes the suggested eligible and inclusive fairness metrics under the same node.

Q4: Is the impact of benefit/harm significant, selective, or neither?

This question helps to define whether the fairness metric selection will focus on the actual values of target or predicted values. The denominator of the fairness metric will include either actual values or predicted values. If the decision according to the model may result significant consequences, the focus will be the predicted values. We suggest that the significant impact is bound to the legal, regulatory, compliance, or governance processes. If the resulting decision of the model is applicable to only a fraction not to the whole population, the focus again will be the predicted values. Actual values are to be focused if the model is applicable to all population and does not have any resulting significant impact. Predicted values could be either positive predictions (TP + FP) or negative predictions (TN + FN). Actual values could be either actual positives (TP + FN) or actual negatives (TN + FP). For example, the fraud detection model predicting the transaction is fraudulent (as 'positive') has significant impact on the positive predictions, therefore, the denominator is suggested to be (TP + FP). For example, for marketing propensity model predicting the customers who will buy a product (as 'positive'), the marketing campaign might not be applied to every customer predicted as positive, but instead, it is commonly applied to top tier customers ranked by propensity score (e.g., top 10% of customers). As only a fraction of positive predictions is relevant, the focus of the model is not to recall all 'willing-to-buy' customers but to improve the precision of 'predicted-to-buy' customers. Therefore, predicted positives should be picked as the denominator of the suggested fairness metric.

Q5: Is difference or ratio-based metrics are preferred?

This question helps to set the preference for the type of fairness metric to be selected. They can either be difference based or ratio based.

Mutual Information Metrics

Mutual information measures the dependence between two random variables by quantifying the amount of information in bits obtained from observing one variable through observing the other (Source: https://arxiv.org/abs/2105.11069). In the context of fairness, mutual information can be used as a measure of independence, separation, and sufficiency (Source: https://arxiv.org/abs/2002.06200).