{"id":19611919,"url":"https://github.com/princeton-nlp/mabel","last_synced_at":"2025-04-27T22:33:47.197Z","repository":{"id":103452241,"uuid":"555773210","full_name":"princeton-nlp/MABEL","owner":"princeton-nlp","description":"EMNLP 2022: \"MABEL: Attenuating Gender Bias using Textual Entailment Data\" https://arxiv.org/abs/2210.14975","archived":false,"fork":false,"pushed_at":"2023-12-14T08:04:53.000Z","size":6209,"stargazers_count":37,"open_issues_count":2,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-05T04:31:50.201Z","etag":null,"topics":["contrastive-learning","fairness","gender-bias","natural-language-processing"],"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/princeton-nlp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-22T09:44:41.000Z","updated_at":"2024-07-24T14:08:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"d3416995-fc09-48b5-bda6-8b3210f9d0ae","html_url":"https://github.com/princeton-nlp/MABEL","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeton-nlp%2FMABEL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeton-nlp%2FMABEL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeton-nlp%2FMABEL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeton-nlp%2FMABEL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/princeton-nlp","download_url":"https://codeload.github.com/princeton-nlp/MABEL/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251219600,"owners_count":21554444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["contrastive-learning","fairness","gender-bias","natural-language-processing"],"created_at":"2024-11-11T10:44:59.833Z","updated_at":"2025-04-27T22:33:42.131Z","avatar_url":"https://github.com/princeton-nlp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## MABEL: Attenuating Gender Bias using Textual Entailment Data\n\nAuthors: [Jacqueline He](https://jacqueline-he.github.io/), [Mengzhou Xia](https://xiamengzhou.github.io/), [Christiane Fellbaum](https://www.cs.princeton.edu/~fellbaum/), [Danqi Chen](https://www.cs.princeton.edu/~danqic/)\n\nThis repository contains the code for our EMNLP 2022 paper, [\"MABEL: Attenuating Gender Bias using Textual Entailment Data\"](https://arxiv.org/pdf/2210.14975.pdf). \n\n**MABEL** (a **M**ethod for **A**ttenuating **B**ias using **E**ntailment **L**abels) is a task-agnostic intermediate pre-training technique that leverages entailment pairs from NLI data to produce \nrepresentations which are both semantically capable and fair. \nThis approach exhibits a good fairness-performance tradeoff across intrinsic and extrinsic gender bias diagnostics, with minimal damage on natural language understanding tasks. \n\n![Training Schema](figure/teaser.png)\n\n\n## Table of Contents\n  * [Quick Start](#quick-start)\n  * [Model List](#model-list)\n  * [Training](#training)\n  * [Evaluation](#evaluation)\n    + [Intrinsic Metrics](#intrinsic-metrics)\n    + [Extrinsic Metrics](#extrinsic-metrics)\n    + [Language Understanding](#language-understanding)\n  * [Code Acknowledgements](#code-acknowledgements)\n  * [Citation](#citation)\n\n## Quick Start\n\nWith the `transformers` package installed, you can import the off-the-shelf model like so: \n\n```python\nfrom transformers import AutoTokenizer, AutoModelForMaskedLM\n\ntokenizer = AutoTokenizer.from_pretrained(\"princeton-nlp/mabel-bert-base-uncased\")\n\nmodel = AutoModelForMaskedLM.from_pretrained(\"princeton-nlp/mabel-bert-base-uncased\")\n```\n\n## Model List\n\n|              MABEL Models       | ICAT ↑ |\n|:-------------------------------|:------|\n|  [princeton-nlp/mabel-bert-base-uncased](https://huggingface.co/princeton-nlp/mabel-bert-base-uncased) | 73.98 | \n| [princeton-nlp/mabel-bert-large-uncased](https://huggingface.co/princeton-nlp/mabel-bert-large-uncased) |  73.45 |\n| [princeton-nlp/mabel-roberta-base](https://huggingface.co/princeton-nlp/mabel-roberta-base) |  69.68 |\n| [princeton-nlp/mabel-roberta-large](https://huggingface.co/princeton-nlp/mabel-roberta-large) |  69.49 |\n\nNote: The ICAT score is a bias metric that consolidates a model's capacity for language modeling and stereotypical association into a single numerical indicator. More information can be found in the [StereoSet](https://aclanthology.org/2021.acl-long.416.pdf) (Nadeem et al., 2021) paper.\n\n## Training\n\nBefore training, make sure that the [counterfactually-augmented NLI data](https://drive.google.com/file/d/16KPp0rZv2DqAumccaRgvpLW4NwRCfdl6/view?usp=sharing), processed from SNLI and MNLI, is downloaded and stored under the `training` directory as `entailment_data.csv`. \n\n**1. Install package dependencies**\n\n```bash\npip install -r requirements.txt\n```\n\n**2. Run training script**\n\n```bash\ncd training\nchmod +x run.sh \n./run.sh\n```\nYou can configure the hyper-parameters in `run.sh` accordingly. Models are saved to `out/`. The optimal set of hyper-parameters varies depending on the choice of backbone encoder, and the full training details can be found in the paper.   \n\n## Evaluation\n\n### Intrinsic Metrics \n\nIf you use your own trained model instead of our provided HF checkpoint, you must first run `python -m training.convert_to_hf --path /path/to/your/checkpoint --base-model bert` (which converts the checkpoint to a standard BertForMaskedLM model - use `--base_model roberta` for RobertaForMaskedLM) prior to intrinsic evaluation.\n\nAlso, please note that we use [Meade et al.'s](https://arxiv.org/abs/2110.08527) method of computation and datasets for both StereoSet and CrowS-Pairs; this is why the metrics for the pre-trained models are not directly comparable to those reported in the original benchmark papers. \n\n\n**1. StereoSet ([Nadeem et al., 2021](https://aclanthology.org/2021.acl-long.416/))**\n\nCommand:\n\n```bash\npython -m benchmark.intrinsic.stereoset.predict --model_name_or_path princeton-nlp/mabel-bert-base-uncased \u0026\u0026 \npython -m benchmark.intrinsic.stereoset.eval\n```\n\n\nOutput:\n```\nintrasentence\ngender\nCount: 2313.0\nLM Score: 84.5453251710623\nSS Score: 56.248299466465376\nICAT Score: 73.98003496789251\n```\n\nCollective Results:\n|              Models       | LM ↑ | SS ◇| ICAT ↑ |\n|:-------------------------------|:------|:------|:------|\n| bert-base-uncased | 84.17 | 60.28 | 66.86 | \n|  princeton-nlp/mabel-bert-base-uncased | 84.54 | 56.25 | 73.98 | \n| bert-large-uncased | 86.54 | 63.24 | 63.62 | \n|  princeton-nlp/mabel-bert-large-uncased | 84.93 | 56.76 |  73.45 |\n| roberta-base | 88.93 | 66.32 | 59.90 | \n|  princeton-nlp/mabel-roberta-base | 87.44 | 60.14 |  69.68 |\n| roberta-large | 88.81 | 66.82 | 58.92 | \n|  princeton-nlp/mabel-roberta-large | 89.72 | 61.28 |  69.49 |\n\n\n◇: The closer to 50, the better.\n\n**2. CrowS-Pairs ([Nangia et al., 2021](https://aclanthology.org/2020.emnlp-main.154/))** \n\nCommand: \n\n```bash\npython -m benchmark.intrinsic.crows.eval --model_name_or_path princeton-nlp/mabel-bert-base-uncased\n```\n\n\nOutput: \n``` \n====================================================================================================\nTotal examples: 262\nMetric score: 50.76\nStereotype score: 51.57\nAnti-stereotype score: 49.51\nNum. neutral: 0.0\n====================================================================================================\n```\n\nCollective Results:\n|              Models       | Metric Score ◇ |\n|:-------------------------------|:------|\n| bert-base-uncased | 57.25 |\n|  princeton-nlp/mabel-bert-base-uncased |50.76 | \n| bert-large-uncased | 55.73 |\n|  princeton-nlp/mabel-bert-large-uncased | 51.15 |\n| roberta-base | 60.15 | \n|  princeton-nlp/mabel-roberta-base | 49.04 | \n| roberta-large | 60.15 | \n|  princeton-nlp/mabel-roberta-large | 54.41 | \n\n◇: The closer to 50, the better.\n\n### Extrinsic Metrics\n\n1. Occupation Classification \n\nSee `benchmark/extrinsic/occ_cls/README.md` for full training instructions and results.\n\n2. Natural Language Inference\n\nSee `benchmark/extrinsic/nli/README.md` for full training instructions and results.\n\n3. Coreference Resolution\n\nSee `benchmark/extrinsic/coref/README.md` for full training instructions and results.\n\n\n### Language Understanding \n**1. GLUE ([Wang et al., 2018](https://aclanthology.org/W18-5446/))** \n\nWe fine-tune on GLUE through the [transformers](https://github.com/huggingface/transformers/tree/main/examples/pytorch/text-classification) library, following the default hyper-parameters. \n\nA straightforward way is to download the current transformers repository:\n\n```bash\ngit clone https://github.com/huggingface/transformers\ncd transformers\npip install .\n```\n\nThen set up the environment dependencies:\n\n```bash\ncd ./examples/pytorch/text-classification\npip install -r requirements.txt\n```\n\n\nHere is a sample script for one of the GLUE tasks, MRPC:\n\n```bash\n# task options: cola, sst2, mrpc, stsb, qqp, mnli, qnli, rte \nexport TASK_NAME=mrpc\nexport OUTPUT_DIR=out/\n\nCUDA_VISIBLE_DEVICES=0 python run_glue.py \\\n  --model_name_or_path princeton-nlp/mabel-bert-base-uncased \\\n  --task_name $TASK_NAME \\\n  --do_train \\\n  --do_eval \\\n  --max_seq_length 128 \\\n  --per_device_train_batch_size 32 \\\n  --learning_rate 2e-5 \\\n  --num_train_epochs 3 \\\n  --output_dir $OUTPUT_DIR\n```\n\n\n**2. SentEval Transfer Tasks ([Conneau et al., 2018](https://arxiv.org/abs/1803.05449))**\n\nPreprocess:\n\nMake sure you have cloned the [SentEval](https://github.com/facebookresearch/SentEval) repo and added its contents into this repository's `transfer` folder, and run `./get_transfer_data.bash` in `data/downstream` to download the evaluation data.\n\nCommand:\n\n```bash\npython -m benchmark.transfer.eval --model_name_or_path princeton-nlp/mabel-bert-base-uncased --task_set transfer\n```\n\nOutput:\n\n```\n+-------+-------+-------+-------+-------+-------+-------+-------+\n|   MR  |   CR  |  SUBJ |  MPQA |  SST2 |  TREC |  MRPC |  Avg. |\n+-------+-------+-------+-------+-------+-------+-------+-------+\n| 78.33 | 85.83 | 93.78 | 89.13 | 85.50 | 85.20 | 68.87 | 83.81 |\n+-------+-------+-------+-------+-------+-------+-------+-------+\n```\n\nCollective Results:\n|              Models       | Transfer Avg. ↑ |\n|:-------------------------------|:------|\n| bert-base-uncased | 83.73 |\n|  princeton-nlp/mabel-bert-base-uncased |83.81 | \n| bert-large-uncased | 86.54 |\n|  princeton-nlp/mabel-bert-large-uncased | 86.09 |\n\n\n## Code Acknowledgements\n- Evaluation code for StereoSet and CrowS-Pairs is adapted from [\"An Empirical Survey of the Effectiveness of Debiasing Techniques for Pre-trained Language Models\"](https://aclanthology.org/2022.acl-long.132/) (Meade et al., 2022). \n- Model implementation code is adapted from [SimCSE](https://github.com/princeton-nlp/SimCSE/blob/main/evaluation.py) (Gao et al., 2021). \n- Evaluation code for the transfer tasks relies on the SentEval package [here](https://github.com/facebookresearch/SentEval), and adapts from a script prepared by [SimCSE](https://github.com/princeton-nlp/SimCSE/blob/main/evaluation.py) (Gao et al., 2021). \n- Evaluation code for GLUE relies on the Huggingface implementation of the [transformers](https://arxiv.org/abs/1910.03771) (Wolf et al., 2019) package.\n- Training and evaluation for e2e span-based coreference resolution follows from [this Pytorch implementation](https://aclanthology.org/2020.emnlp-main.686/) (Xu and Choi, 2020).\n- Repository is formatted with [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black).\n\n## Citation\n```bibtex\n@inproceedings{he2022mabel,\n   title={{MABEL}: Attenuating Gender Bias using Textual Entailment Data},\n   author={He, Jacqueline and Xia, Mengzhou and Fellbaum, Christiane and Chen, Danqi},\n   booktitle={Empirical Methods in Natural Language Processing (EMNLP)},\n   year={2022}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprinceton-nlp%2Fmabel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprinceton-nlp%2Fmabel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprinceton-nlp%2Fmabel/lists"}