biasx 0.1.2

A toolkit for detecting and explaining gender bias in face classification models

BiasX

BiasX is a comprehensive framework for quantifying and explaining gender bias in face classification models using a feature-based approach. Rather than just measuring bias with traditional metrics, BiasX reveals which facial features contribute to gender-specific misclassifications, providing explainable and actionable insights.

Features

Feature	Description
Feature-Level Bias Analysis	Identifies bias contributions from specific facial features (eyes, nose, lips, etc.)
Visual Explanation Generation	Creates activation maps to visualize model decision regions
Comprehensive Metrics	Calculates both traditional (equalized odds) and feature-based bias scores
Dataset Management	Handles facial image datasets with demographic attributes
Experiment Framework	Supports controlled experiments with manipulated gender distributions and masked facial features
Interactive Visualization	Includes a web application for exploring bias analysis results

Installation

From PyPI (Recommended)

BiasX is available on PyPI: https://pypi.org/project/biasx/

# Install directly from PyPI
pip install biasx

From Source (For Development)

# Clone the repository
git clone https://github.com/rixmape/biasx.git
cd biasx

# Install dependencies
pip install -r requirements.txt

# Install the package in development mode
pip install -e .

Quick Start

from biasx import BiasAnalyzer

# Configure the analyzer
config = {
    "model": {
        "path": "path/to/gender/classifier.keras",
    },
    "explainer": {
        "landmarker_source": "mediapipe",
        "cam_method": "gradcam++",
        "cutoff_percentile": 90,
        "threshold_method": "otsu",
        "overlap_threshold": 0.2,
        "distance_metric": "euclidean",
    },
    "dataset": {
        "source": "utkface",
        "image_width": 224,
        "image_height": 224,
        "color_mode": "L",
        "single_channel": False,
        "max_samples": 100,
        "shuffle": True,
        "seed": 69,
    },
}

# Run analysis
analyzer = BiasAnalyzer(config)
results = analyzer.analyze()

# Access results
print(f"Overall BiasX Score: {results.disparity_scores.biasx}")
print(f"Equalized Odds Score: {results.disparity_scores.equalized_odds}")

# View feature-specific bias
for feature, analysis in results.feature_analyses.items():
    print(f"{feature.value}: Bias Score = {analysis.bias_score}")

Web Application

The BiasX framework includes an interactive web application for visualizing and exploring bias analysis results.

Local Deployment

# Run locally
streamlit run app/app.py

# Or use the make command
make deploy

Public Deployment

The application is publicly available at: biasx-framework.streamlit.app

Development

Run tests with coverage reporting:

pytest --cov=biasx --cov-report=term --cov-report=html

# Or use the make command
make test

License

This project is licensed under the MIT License. See the LICENSE file for details.

Citation

If you use BiasX in your research, please cite our work:

@article{biasx2023,
  title={BiasX: A Feature-Based Framework for Explaining and Quantifying Gender Bias in Face Classification},
  author={Lucero, J. G. and Mape, R. N. and Sy, J. W.},
  year={2025}
}