{"id":48612765,"url":"https://github.com/g8a9/ear","last_synced_at":"2026-04-09T00:35:19.934Z","repository":{"id":42486960,"uuid":"467028108","full_name":"g8a9/ear","owner":"g8a9","description":"Code associated with the paper \"Entropy-based Attention Regularization Frees Unintended Bias Mitigation from Lists\"","archived":false,"fork":false,"pushed_at":"2022-05-31T17:03:42.000Z","size":243,"stargazers_count":49,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-15T10:56:45.982Z","etag":null,"topics":["attention","attention-mechanism","bert-model","nlp","regularization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/g8a9.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-03-07T09:33:09.000Z","updated_at":"2025-06-18T03:05:41.000Z","dependencies_parsed_at":"2022-09-13T15:23:03.756Z","dependency_job_id":null,"html_url":"https://github.com/g8a9/ear","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/g8a9/ear","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g8a9%2Fear","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g8a9%2Fear/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g8a9%2Fear/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g8a9%2Fear/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/g8a9","download_url":"https://codeload.github.com/g8a9/ear/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g8a9%2Fear/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31580226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["attention","attention-mechanism","bert-model","nlp","regularization"],"created_at":"2026-04-09T00:35:19.835Z","updated_at":"2026-04-09T00:35:19.919Z","avatar_url":"https://github.com/g8a9.png","language":"Python","readme":"# Entropy-based Attention Regularization 👂\n\nEAR is a regularization technique to mitigate uninteded bias while reducing lexical overfitting. It is based on attention entropy maximization. In practice, EAR adds a regularization term at training time to learn tokens with maximal self-attention entropy.\n\nSee the paper for additional details:\n\n*Attanasio, G., Nozza, D., Hovy, D., \u0026 Baralis, E. \"Entropy-based Attention Regularization Frees Unintended Bias Mitigation from Lists\". In Findings of the Association for Computational Linguistics: ACL2022. Association for Computational Linguistics, 2022.*\n\n### Quick links\n\n- ACL Anthology bibkey: `attanasio-etal-2022-entropy`\n- ACL Anthology: https://aclanthology.org/2022.findings-acl.88/\n- Preprint: https://arxiv.org/abs/2203.09192\n\n## Project structure\n\nThe data used in this study is in `data`. Please note that we are not allowed to distribute all the data sets. For some of those, you will need to download it yourselves (instructions below).\nThe code is organized in python scripts (training and evaluation of models), bash scripts to run experiments, and jupyter notebooks.\n\nThe main files are the following:\n- `train_bert.py`: use this script to train any bert-based model starting from HuggingFace checkpoints.\n- `evaluate_model.py`: use this script to evaluate a model either on a test set or a synthetic evaluation set.\n\nPlease find all the accepted parameters running `python \u003cscript_name\u003e --help`.\n\n## Getting started\n\nThe following are the basic steps to setup our environment and replicate our results.\n\n## Getting the data sets\n\nPlease follow these instructions to retrive the presented dataset:\n\n- Misogyny (EN): the dataset is not publicly available. Please fill [this form](https://docs.google.com/forms/d/e/1FAIpQLSevs4Ji3dNmK5CxyulYG-PxX3U10-RgDrPpMKPRjtI81f0yaQ/viewform) to submit a request to the authors.\n- Misogyny (IT): the dataset is not publicly available. Please fill [this form](https://forms.gle/uFF3sAtMMqayiDiz9) to submit a request to the authors.\n- Multilingual and Multi-Aspect (MlMA): the dataset is available online. In `data`, we provide our splitfiles with the additional binary \"hate\" column used in our experiments.\n\nFor the sake of simplicty, we have assigned short names to each data set. Please find them and how to use them in [dataset.py](./dataset.py).\n\n## Dependencies\n\nYou'll need a working Python environment to run the code. \nThe required dependencies are specified in the file `environment.yml`.\nWe use `conda` virtual environments to manage the project dependencies in\nisolation.\n\nRun the following command in the repository folder to create a separate environment \nand install all required dependencies in it:\n\n    conda create -n ear python==3.8\n    conda activate ear\n    pip install -r requirements.txt\n\n## Example\n\nEAR can be plugged very easily to HuggingFace models.\n\n```python\nfrom transformers import AutoTokenizer, AutoModel\nimport ear\n\ntokenizer = AutoTokenizer.from_pretrained(\"bert-base-uncased\")\nmodel = AutoModel.from_pretrained(\"bert-base-uncased\")\n\nitem = tokenizer(\"Today it's a good day!\")\noutputs = model(**item, output_attentions=True)\n\nreg_strength = 0.01\nneg_entropy = ear.compute_negative_entropy(\n    inputs=outputs.attentions,\n    attention_mask=item[\"attention_mask\"]\n)\nreg_loss = reg_strength * neg_entropy\nloss = reg_loss + output.loss\n\n```\n\n## Reproducing Hate Speech Detection results\n\nThe [`bash`](bash) folder contains some utility bash scripts useful to run multiple experiments sequentially. They cover the training and evaluation pipeline of all the models tested in the paper. To let everything work as expected, please run them from the parent directory.\n\n### Training\n\nPlease check out your disk size, these scripts will save two model checkpoints (best and the last one) for every seed.\n\nTrain **BERT** on the Misogyny (EN) dataset:\n\n```bash\n./bash/train_model_10_seeds.sh bert-base-uncased \u003coutput_dir\u003e \u003ctraining_dataset\u003e\n```\n\ne.g., `./bash/train_model_10_seeds.sh bert-base-uncased . miso`\n\n\nTrain **BERT+EAR** on the Multilingual and Multi-Aspect dataset:\n\n```bash\n./bash/train_model_EAR_10_seeds.sh bert-base-uncased \u003coutput_dir\u003e \u003ctraining_dataset\u003e\n```\n\ne.g., `./bash/train_model_EAR_10_seeds.sh bert-base-uncased . mlma`\n\n\nNote that:\n- if you want to take into account class imbalance, you should add the `--balanced_loss` to the parameters passed as command line arguments to python;\n- for [BERT+SOC](https://github.com/BrendanKennedy/contextualizing-hate-speech-models-with-explanations) (Kennedy et al. 2020), we re-use the authors's implementation. Therefore, no\ntraining scripts are provided here.\n\n## Testing\n\nTo evaluate a model, or a folder with several models (different seeds), you have to:\n1. run the evaluation on synthetic data.\n2. run the evaluation on test data \n\n### Evaluation of bias metrics on synthetic data\n\nHere we provide an example to run the evaluation on Madlibs77K synthetic data using a specific checkpoint name (`last.ckpt` in this case).\n\n```bash\n./bash/evaluate_folder_madlibs_pattern.sh \u003cin_dir\u003e \u003cout_dir\u003e last.ckpt\n```\n\nAnalogous script for the other synthetic sets are stored in the folder `./bash`. Namely:\n- `evaluate_folder_miso_synt.sh` Run the evaluation of all the models within a specified parent directory on Misogyny (EN), synthetic set.\n- `evaluate_folder_miso-ita_synt.sh` Run the evaluation of all the models within a specified parent directory on Misogyny (IT), synthetic set.\n\n### Evaluation on test data\n\nHere we provide an example to run the evaluation on the test set of MlMA.\n\n```bash\n./bash/test_folder.sh \u003cin_dir\u003e \u003cout_dir\u003e mlma \u003csrc_tokenizer\u003e \u003cckpt_pattern\u003e\n```\nNote that evaluation on Misogyny (IT) requires the parameter `--src_tokenizer dbmdz/bert-base-italian-uncased`\n\n## EAR for Biased Term Extraction\n\nWe provide a Jupyter Notebook where we show how to extract terms with the lowest contextualization, which\nmay induce most of the bias in the model.\n\nAfter having trained at least one model (i.e., you have a model checkpoint), the notebook [`term_extraction.ipynb`](term_extraction.ipynb) will guide you through the discovery of biased terms.\n\n## References\n\nPlease use the following bibtex entry if you use this model in your project:\n \n```bib\n@inproceedings{attanasio-etal-2022-entropy,\n    title = \"Entropy-based Attention Regularization Frees Unintended Bias Mitigation from Lists\",\n    author = \"Attanasio, Giuseppe  and\n      Nozza, Debora  and\n      Hovy, Dirk  and\n      Baralis, Elena\",\n    booktitle = \"Findings of the Association for Computational Linguistics: ACL 2022\",\n    month = may,\n    year = \"2022\",\n    address = \"Dublin, Ireland\",\n    publisher = \"Association for Computational Linguistics\",\n    url = \"https://aclanthology.org/2022.findings-acl.88\",\n    pages = \"1105--1119\",\n    abstract = \"Natural Language Processing (NLP) models risk overfitting to specific terms in the training data, thereby reducing their performance, fairness, and generalizability. E.g., neural hate speech detection models are strongly influenced by identity terms like gay, or women, resulting in false positives, severe unintended bias, and lower performance.Most mitigation techniques use lists of identity terms or samples from the target domain during training. However, this approach requires a-priori knowledge and introduces further bias if important terms are neglected.Instead, we propose a knowledge-free Entropy-based Attention Regularization (EAR) to discourage overfitting to training-specific terms. An additional objective function penalizes tokens with low self-attention entropy.We fine-tune BERT via EAR: the resulting model matches or exceeds state-of-the-art performance for hate speech classification and bias metrics on three benchmark corpora in English and Italian.EAR also reveals overfitting terms, i.e., terms most likely to induce bias, to help identify their effect on the model, task, and predictions.\",\n}\n\n```\n\n### 🚨 Ethical considerations\n\nThe process of building the list remains a data-driven approach, which is strongly dependent on the task, collected corpus, term frequencies, and the chosen model.\nTherefore, the list might either lack specific terms that instead need to be attentioned, or include some that do not strictly perpetrate harm.\nBecause of these twin issues, the resulting lists should not be read as complete or absolute. We would therefore discourage users from simply building and developing models based solely on the extracted terms. We want, instead, the terms to stand as a starting point for debugging and searching for potential bias issues in the task at hand. \n\n## License\n\nAll source code is made available under a MIT license. See `LICENSE.md` for the full license text.\n\nThe manuscript text is not open source. The authors reserve the rights to the article content, which is currently submitted for publication.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fg8a9%2Fear","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fg8a9%2Fear","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fg8a9%2Fear/lists"}