Metadata-Version: 2.4
Name: biasx
Version: 0.1.2
Summary: A toolkit for detecting and explaining gender bias in face classification models
Author-email: Rixdon Niño Mape <rixdonninorecario.mape@bicol-u.edu.ph>, Jerwin Glen Lucero <jerwinglenalejandre.lucero@bicol-u.edu.ph>, Jan Wilhelm Sy <janwilhelmtan.sy@bicol-u.edu.ph>
License: MIT License
        
        Copyright (c) 2025 Rixdon Niño Mape, Jerwin Glen Lucero, Jan Wilhelm Sy
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/rixmape/biasx
Project-URL: Bug Tracker, https://github.com/rixmape/biasx/issues
Project-URL: Documentation, https://github.com/rixmape/biasx/blob/main/README.md
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: huggingface_hub
Requires-Dist: mediapipe
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pillow
Requires-Dist: pyarrow
Requires-Dist: scikit-image
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: tensorflow
Requires-Dist: tf_keras_vis
Dynamic: license-file

# 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/>

```bash
# Install directly from PyPI
pip install biasx
```

### From Source (For Development)

```bash
# 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

```python
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

```bash
# 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](https://biasx-framework.streamlit.app)

## Development

Run tests with coverage reporting:

```bash
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:

```plaintext
@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}
}
```
