How tolga-b/debiaswe works
This project is a Python-based tool for debiasing word embeddings—specifically, removing gender bias from pre-trained embeddings such as Google News’ Word2Vec. The main goal is to process a given embedding, utilize seed lists and predefined word pairs, and produce a debiased version of the embedding, following the techniques described in the related NIPS paper.
Main Components
• Input Embedding: Represent the original word embedding file (e.g., “GoogleNews-vectors-negative300.bin”) that serves as the system’s input.
• Data Files: Include the JSON files under the “data” folder: definitional_pairs.json, equalize_pairs.json, gender_specific_seed.json, and gender_specific_full.json. These files encapsulate the gender-specific words and pairing information used in the debiasing process.
• Processing Modules:
• Learn Gender Specific Module: (debiaswe/learn_gender_specific.py) which takes the embedding and the seed set (gender_specific_seed.json) to learn/extend a full list of gender-specific words (outputting gender_specific_full.json).
• Debiasing Module: (debiaswe/debias.py) that applies the debiasing algorithm. It uses the definitional pairs, the expanded gender-specific words set (gender_specific_full.json), and equalize pairs to produce the hard debiased embedding.
• Embedding I/O Module: (debiaswe/we.py) likely responsible for reading and writing the word2vec binary format.
• Data Utilities: (debiaswe/data.py) for common data handling, possibly abstracting JSON file interactions.
• Output Embedding: The final debiased embedding binary file produced by the debias.py script.
Relationships and Data Flow
• Parallel to that, represent the static data files (definitional_pairs.json and equalize_pairs.json) linking to the Debiasing Module.
• Optionally, include a branch for the notebook (tutorial_example1.ipynb) as an illustrative usage example, indicating how a user might interact with the components or run sample experiments.
Important Architectural Patterns and Design Principles
• Modularity: The processing is split into clear modules (one for learning gender-specific terms and one for applying debiasing). Each module is organized within the “debiaswe” package.
• Data-Driven Flow: The system uses external JSON files to parameterize processing, allowing adjustments without changing code.
• Separation of Concerns: Input/output handling (in debiaswe/we.py and the script wrappers) is kept separate from the algorithm’s core logic.
• Command-line Script Integration: The project is designed to be executed via Python scripts, which form the operational entry points.
Instructing the Principal Software Engineer
• Then, combine the outputs from the “Learn Gender-Specific Module” and the static data files into a module labeled “Debiasing Module (debias.py)”. This module also references the “Embedding I/O Module (we.py)” for reading/writing operations.
• Optionally, indicate a peripheral component for “Tutorial Example (tutorial_example1.ipynb)” that might interface with these modules for demonstration purposes.