callmefair.search.fair_search

Fair Search Module

This module provides high-level bias search functionality for the CallMeFair framework. It implements comprehensive bias evaluation across individual attributes and their combinations, with support for different set operations and result visualization.

The module extends BaseSearch to provide: - Individual attribute bias evaluation - Attribute combination analysis (2-way and 3-way) - Set operation comparison (union, intersection, differences) - Pretty table output for results - Comprehensive bias summarization

Classes:

BiasSearch: Main class for bias search and evaluation

Functions:

pretty_print: Format results into pretty tables

Example

>>> from callmefair.search.fair_search import BiasSearch
>>> searcher = BiasSearch(df, 'target', ['gender', 'race'])
>>> table, printable = searcher.evaluate_average()

Classes

BiasSearch

Main class for bias search and evaluation in the CallMeFair framework.

Functions

pretty_print(table[, order_key])

Format a list of results into a pretty table for display.

Module Contents

class callmefair.search.fair_search.BiasSearch(df, label_name, attribute_names)

Bases: callmefair.search._search_base.BaseSearch

Main class for bias search and evaluation in the CallMeFair framework.

This class extends BaseSearch to provide comprehensive bias evaluation across individual attributes and their combinations. It supports both individual attribute analysis and complex attribute combination evaluation using different set operations.

The class provides methods for: - Individual attribute bias evaluation - 2-way and 3-way attribute combinations - Set operation comparison (union, intersection, differences) - Pretty table output for results - Comprehensive bias summarization

Variables:

• df (pd.DataFrame) – Input dataset with features and target

• label_name (str) – Name of the target variable

• attribute_names (list[str]) – List of sensitive attributes to evaluate

Parameters:

• df (pandas.DataFrame)

• label_name (str)

• attribute_names (list[str])

Example

>>> searcher = BiasSearch(df, 'target', ['gender', 'race', 'age'])
>>> table, printable = searcher.evaluate_average()
>>> print(printable)

Initialize the BiasSearch object.

Parameters:

• df (pd.DataFrame) – Input dataset containing features and target variable

• label_name (str) – Name of the target variable column

• attribute_names (list[str]) – List of sensitive attributes to evaluate

evaluate_average(treat_umbalance=False, iterate=10, model_name='lr')

Evaluate bias for all individual attributes and return averaged results.

This method evaluates bias for each individual sensitive attribute and returns both raw and normalized fairness scores. The results are formatted into a pretty table for easy visualization.

Parameters:

• treat_umbalance (bool) – Whether to apply NearMiss undersampling

• iterate (int) – Number of iterations for robust evaluation

• model_name (str) – Type of model to use (‘lr’, ‘cat’, ‘xgb’, ‘mlp’)

Returns:

(table_data, pretty_table) - Raw data and formatted table

Return type:

tuple

Example

>>> table, printable = searcher.evaluate_average(iterate=5)
>>> print(printable)

evaluate_combination_average(col_1, col_2, treat_umbalance=False, iterate=10, model_name='lr')

Evaluate bias for all set operations between two attributes.

This method compares all possible set operations (union, intersection, differences, symmetric difference) between two attributes and evaluates bias for each combination. This helps understand how different ways of combining attributes affect bias.

Parameters:

• col_1 (str) – Name of the first attribute

• col_2 (str) – Name of the second attribute

• treat_umbalance (bool) – Whether to apply NearMiss undersampling

• iterate (int) – Number of iterations for robust evaluation

• model_name (str) – Type of model to use (‘lr’, ‘cat’, ‘xgb’, ‘mlp’)

Returns:

(table_data, pretty_table) - Raw data and formatted table

Return type:

tuple

Example

>>> table, printable = searcher.evaluate_combination_average('gender', 'race')
>>> print(printable)

evaluate_combinations(treat_umbalance=False, iterate=10, model_name='lr')

Evaluate bias for all 2-way and 3-way attribute combinations.

This method creates combinations of sensitive attributes using intersection operations and evaluates bias for each combination. It generates both 2-way combinations (e.g., gender_race) and 3-way combinations (e.g., gender_race_age).

Parameters:

• treat_umbalance (bool) – Whether to apply NearMiss undersampling

• iterate (int) – Number of iterations for robust evaluation

• model_name (str) – Type of model to use (‘lr’, ‘cat’, ‘xgb’, ‘mlp’)

Returns:

(table_data, pretty_table) - Raw data and formatted table

Return type:

tuple

Example

>>> table, printable = searcher.evaluate_combinations()
>>> print(printable)

attribute_names

callmefair.search.fair_search.pretty_print(table, order_key=1)

Format a list of results into a pretty table for display.

This function takes a list of results and formats them into a PrettyTable object for better visualization. The results are sorted by the specified column in descending order.

Parameters:

• table (list) – List of results where first element is header row

• order_key (int) – Column index to sort by (default: 1 for fairness score)

Returns:

Formatted table ready for display

Return type:

PrettyTable

Example

>>> results = [['Attribute', 'Score'], ['gender', 0.85], ['race', 0.72]]
>>> table = pretty_print(results)
>>> print(table)