# Bias Lens
**Bias Lens** is a Python library designed for bias detection and explainable AI (XAI) methods for NLP models. It provides a unified interface to perform token-level bias analysis using multiple state-of-the-art explanation techniques including Integrated Gradients, DeepLIFT, LIME, SHAP, attention-based methods, counterfactual explanations, LRP, and occlusion methods.
## Features
- **Bias NER Classification:**
Leverage a token classification model (e.g., BERT) to identify bias-related tokens with customizable label mappings.
- **Explainability Methods:**
Integrated support for various XAI techniques:
- **LIME:** Local, interpretable model-agnostic explanations.
- **SHAP:** Shapley values for fair attribution of input tokens.
- **Integrated Gradients:** Gradient-based attributions for deep models.
- **DeepLIFT:** Explains predictions by comparing against a baseline.
- **Attention Explanations:** Visualize attention scores.
- **Counterfactual Explanations:** Generate alternative input versions to understand model decisions.
- **Layer-wise Relevance Propagation (LRP):** Propagate relevance scores back to input features.
- **Occlusion:** Identify important tokens by systematically masking parts of the input.
- **Modular Design:**
Easily extendable code structure to add new explanation methods or integrate with custom models.
- **Factory Pattern:**
Use a unified factory to access various explanation methods effortlessly.
## Installation
You can install **Bias Lens** from PyPI (after publishing) with:
```bash
pip install bias-lens
```
Or install directly from the repository:
```bash
pip install git+https://github.com/bhavaniit24/bias-lens.git
```
## Quick Start
Below is a simple example demonstrating how to use Bias Lens with your own model, tokenizer, and label mapping.
```python
from transformers import BertForTokenClassification, BertTokenizerFast
from bias_lens import BiasNERClassifier, BiasModelExplainerFactory
# User-defined model, tokenizer, and id2label mapping
model = BertForTokenClassification.from_pretrained("your_model_path")
tokenizer = BertTokenizerFast.from_pretrained("your_model_path")
id2label = {
0: "O",
1: "B-STEREO",
2: "I-STEREO",
3: "B-GEN",
4: "I-GEN",
5: "B-UNFAIR",
6: "I-UNFAIR",
7: "B-EXCL",
8: "I-EXCL",
9: "B-FRAME",
10: "I-FRAME",
11: "B-ASSUMP",
12: "I-ASSUMP",
}
# Create a bias NER classifier instance
ner_classifier = BiasNERClassifier(model, tokenizer, id2label)
result = ner_classifier.predict("Women are bad drivers")
print("NER Prediction:", result)
# Create an explainer factory
explainer_factory = BiasModelExplainerFactory(model, tokenizer, id2label)
# Example: Get LIME explainer and generate explanation
lime_explainer = explainer_factory.get_explainer("lime")
lime_explanation = lime_explainer.explain("Women are bad drivers")
print("LIME Explanation:", lime_explanation)
```
## Documentation
### Modules and Classes
- **BiasNERClassifier:**
Provides a method to perform token-level bias prediction using a pre-trained token classification model.
- **BaseExplainer & ProbabilityExplainerMixin:**
Base classes that offer common functionality such as input preparation and probability prediction.
- **Explainer Implementations:**
Classes like `LimeExplainer`, `ShapExplainer`, `IntegratedGradientsExplainer`, `DeepLiftExplainer`, `AttentionExplainer`, `CounterfactualExplainer`, `LRPExplainer`, and `OcclusionExplainer` each encapsulate a different XAI method.
- **BiasModelExplainerFactory:**
A factory class to easily retrieve the desired explainer based on a string key.
### Contributing
Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/bhavaniit24/bias-lens) with your ideas and improvements.
### License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
### Contact
For any questions or feedback, please contact [bhavaniit24](mailto:loganthan.20201212@iit.ac.lk).
---
_Bias Lens_ is designed to make bias detection and model interpretability more accessible and flexible. Whether you are researching fairness in NLP or developing production models, this library aims to provide robust tools to explain and mitigate biases.
Raw data
{
"_id": null,
"home_page": null,
"name": "bias-lens",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "bias, explainable-ai, XAI, NLP, transformers, fairness",
"author": "bhavaniit24",
"author_email": "loganthan.20201212@iit.ac.lk",
"download_url": "https://files.pythonhosted.org/packages/10/f2/e8bbcf032152d61b29d325a50f447787e723b68cfddfc5994f5425d56579/bias_lens-0.0.2.tar.gz",
"platform": null,
"description": "# Bias Lens\n\n**Bias Lens** is a Python library designed for bias detection and explainable AI (XAI) methods for NLP models. It provides a unified interface to perform token-level bias analysis using multiple state-of-the-art explanation techniques including Integrated Gradients, DeepLIFT, LIME, SHAP, attention-based methods, counterfactual explanations, LRP, and occlusion methods.\n\n## Features\n\n- **Bias NER Classification:** \n Leverage a token classification model (e.g., BERT) to identify bias-related tokens with customizable label mappings.\n\n- **Explainability Methods:** \n Integrated support for various XAI techniques:\n\n - **LIME:** Local, interpretable model-agnostic explanations.\n - **SHAP:** Shapley values for fair attribution of input tokens.\n - **Integrated Gradients:** Gradient-based attributions for deep models.\n - **DeepLIFT:** Explains predictions by comparing against a baseline.\n - **Attention Explanations:** Visualize attention scores.\n - **Counterfactual Explanations:** Generate alternative input versions to understand model decisions.\n - **Layer-wise Relevance Propagation (LRP):** Propagate relevance scores back to input features.\n - **Occlusion:** Identify important tokens by systematically masking parts of the input.\n\n- **Modular Design:** \n Easily extendable code structure to add new explanation methods or integrate with custom models.\n\n- **Factory Pattern:** \n Use a unified factory to access various explanation methods effortlessly.\n\n## Installation\n\nYou can install **Bias Lens** from PyPI (after publishing) with:\n\n```bash\npip install bias-lens\n```\n\nOr install directly from the repository:\n\n```bash\npip install git+https://github.com/bhavaniit24/bias-lens.git\n```\n\n## Quick Start\n\nBelow is a simple example demonstrating how to use Bias Lens with your own model, tokenizer, and label mapping.\n\n```python\nfrom transformers import BertForTokenClassification, BertTokenizerFast\nfrom bias_lens import BiasNERClassifier, BiasModelExplainerFactory\n\n# User-defined model, tokenizer, and id2label mapping\nmodel = BertForTokenClassification.from_pretrained(\"your_model_path\")\ntokenizer = BertTokenizerFast.from_pretrained(\"your_model_path\")\nid2label = {\n 0: \"O\",\n 1: \"B-STEREO\",\n 2: \"I-STEREO\",\n 3: \"B-GEN\",\n 4: \"I-GEN\",\n 5: \"B-UNFAIR\",\n 6: \"I-UNFAIR\",\n 7: \"B-EXCL\",\n 8: \"I-EXCL\",\n 9: \"B-FRAME\",\n 10: \"I-FRAME\",\n 11: \"B-ASSUMP\",\n 12: \"I-ASSUMP\",\n}\n\n# Create a bias NER classifier instance\nner_classifier = BiasNERClassifier(model, tokenizer, id2label)\nresult = ner_classifier.predict(\"Women are bad drivers\")\nprint(\"NER Prediction:\", result)\n\n# Create an explainer factory\nexplainer_factory = BiasModelExplainerFactory(model, tokenizer, id2label)\n\n# Example: Get LIME explainer and generate explanation\nlime_explainer = explainer_factory.get_explainer(\"lime\")\nlime_explanation = lime_explainer.explain(\"Women are bad drivers\")\nprint(\"LIME Explanation:\", lime_explanation)\n```\n\n## Documentation\n\n### Modules and Classes\n\n- **BiasNERClassifier:**\n Provides a method to perform token-level bias prediction using a pre-trained token classification model.\n\n- **BaseExplainer & ProbabilityExplainerMixin:**\n Base classes that offer common functionality such as input preparation and probability prediction.\n\n- **Explainer Implementations:**\n Classes like `LimeExplainer`, `ShapExplainer`, `IntegratedGradientsExplainer`, `DeepLiftExplainer`, `AttentionExplainer`, `CounterfactualExplainer`, `LRPExplainer`, and `OcclusionExplainer` each encapsulate a different XAI method.\n\n- **BiasModelExplainerFactory:**\n A factory class to easily retrieve the desired explainer based on a string key.\n\n### Contributing\n\nContributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/bhavaniit24/bias-lens) with your ideas and improvements.\n\n### License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n### Contact\n\nFor any questions or feedback, please contact [bhavaniit24](mailto:loganthan.20201212@iit.ac.lk).\n\n---\n\n_Bias Lens_ is designed to make bias detection and model interpretability more accessible and flexible. Whether you are researching fairness in NLP or developing production models, this library aims to provide robust tools to explain and mitigate biases.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A library for bias detection and explainable AI methods in NLP models.",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://bias-lens.web.app",
"Repository": "https://github.com/bhavaniit24/bias-lens"
},
"split_keywords": [
"bias",
" explainable-ai",
" xai",
" nlp",
" transformers",
" fairness"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "80f00c946e0b1f74c57bff30d015d2a9fcb7b2035797c0ffb44c7e309497b332",
"md5": "00f256ad50166d5fd1fecd72e2fb6859",
"sha256": "d84ffbaea2bee17689621da6a521f4765fb5a187dad9cd623e00072f56bb52f1"
},
"downloads": -1,
"filename": "bias_lens-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "00f256ad50166d5fd1fecd72e2fb6859",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 16748,
"upload_time": "2025-02-23T08:16:05",
"upload_time_iso_8601": "2025-02-23T08:16:05.541739Z",
"url": "https://files.pythonhosted.org/packages/80/f0/0c946e0b1f74c57bff30d015d2a9fcb7b2035797c0ffb44c7e309497b332/bias_lens-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "10f2e8bbcf032152d61b29d325a50f447787e723b68cfddfc5994f5425d56579",
"md5": "5e7357d4300628718a8a9a7b6ca7ae9f",
"sha256": "1f30111ff8fba24dd7c8d0f934aa33411b578f97646d6d3db8fe3082c0f5f745"
},
"downloads": -1,
"filename": "bias_lens-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "5e7357d4300628718a8a9a7b6ca7ae9f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 11932,
"upload_time": "2025-02-23T08:16:06",
"upload_time_iso_8601": "2025-02-23T08:16:06.741688Z",
"url": "https://files.pythonhosted.org/packages/10/f2/e8bbcf032152d61b29d325a50f447787e723b68cfddfc5994f5425d56579/bias_lens-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-23 08:16:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bhavaniit24",
"github_project": "bias-lens",
"github_not_found": true,
"lcname": "bias-lens"
}
JSON
