Add swap_gendered_words augmentation (#110)

Summary:
Pull Request resolved: #110

Fairness augmentation which uses predefined aligned lists of male- and female-gendered words to swap the gender of words in the input text.

Reviewed By: jbitton

Differential Revision: D30341486

fbshipit-source-id: 9ba832d078a730728a2e6643b87e60cfa0f64389

Author: Zoe Papakipos

.github/workflows/lint_python.yml

@@ -13,7 +13,7 @@ jobs:
       - run: pip install bandit black codespell flake8 isort pyre-check pytest pyupgrade safety
       - run: bandit --recursive --skip B101,B301,B303,B311,B403 .
       - run: black --check . || true
-      - run: codespell --ignore-words-list="tha" --skip="*/text_tests,*/misspelling.json"
+      - run: codespell --ignore-words-list="tha" --skip="*/text_tests,*assets/text/*"
       - run: flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
       - run: flake8 . --count --exit-zero --max-complexity=15 --max-line-length=90 --show-source --statistics
       - run: isort --check-only --profile black . || true

augly/assets/text/gendered_words_mapping.json

@@ -0,0 +1,272 @@
+{
+    "abbot":"abbess",
+    "abbess": "abbot",
+    "abbots": "abesses",
+    "abesses": "abbots",
+    "uncle": "auntie",
+    "aunt": "uncle",
+    "uncles": "aunts",
+    "aunts": "uncles",
+    "bachelor": "spinster",
+    "bachelorette": "bachelor",
+    "bachelors": "spinsters",
+    "bachelorettes": "bachelors",
+    "baron": "baroness",
+    "baroness": "baron",
+    "barons": "baronesses",
+    "baronesses": "barons",
+    "groom": "bride",
+    "bride": "groom",
+    "grooms": "brides",
+    "brides": "grooms",
+    "chairman": "chairwoman",
+    "chairwoman": "chairman",
+    "chairmen": "chairwomen",
+    "chairwomen": "chairmen",
+    "congressman": "congresswoman",
+    "congresswoman": "congressman",
+    "congressmen": "congresswomen",
+    "congresswomen": "congressmen",
+    "monastary": "nunnery",
+    "convent": "monastary",
+    "monastaries": "nunneries",
+    "convents": "monastaries",
+    "cowboy": "cowgirl",
+    "cowgirl": "cowboy",
+    "cowboys": "cowgirls",
+    "cowgirls": "cowboys",
+    "geezer": "hag",
+    "crone": "geezer",
+    "geezers": "hags",
+    "crones": "geezers",
+    "czar": "czarina",
+    "czarina": "czar",
+    "sir": "mademoiselle",
+    "dame": "sir",
+    "son": "daughter",
+    "daughter": "son",
+    "sons": "daughters",
+    "daughters": "sons",
+    "duke": "dutchess",
+    "dutchess": "duke",
+    "dukes": "dutchesses",
+    "dutchesses": "dukes",
+    "emperor": "empress",
+    "empress": "emperor",
+    "emperors": "empresses",
+    "empresses": "emperors",
+    "enchantor": "enchantress",
+    "enchantress": "enchantor",
+    "enchantors": "enchantresses",
+    "enchantresses": "enchantors",
+    "male": "female",
+    "female": "male",
+    "male's": "female's",
+    "female's": "male's",
+    "males": "females",
+    "females": "males",
+    "masculine": "feminine",
+    "feminine": "masculine",
+    "masculinity": "femininity",
+    "femininity": "masculinity",
+    "bro": "sis",
+    "gal": "guy",
+    "bros": "gals",
+    "gals": "guys",
+    "boy": "girl",
+    "girl": "boy",
+    "boy's": "girl's",
+    "girl's": "boy's",
+    "boyfriend": "girlfriend",
+    "girlfriend": "boyfriend",
+    "boyfriends": "girlfriends",
+    "girlfriends": "boyfriends",
+    "boyhood": "girlhood",
+    "girlhood": "boyhood",
+    "boyish": "girly",
+    "girlish": "boyish",
+    "boys": "girls",
+    "girls": "boys",
+    "girly": "boyish",
+    "godfather": "godmother",
+    "godmother": "godfather",
+    "godfathers": "godmothers",
+    "godmothers": "godfathers",
+    "gramps": "grams",
+    "grams": "gramps",
+    "grandpa": "grandma",
+    "grandma": "grandpa",
+    "grandpas": "grandmas",
+    "grandmas": "grandpas",
+    "grandfather": "grandmother",
+    "grandmother": "grandfather",
+    "grandfathers": "grandmothers",
+    "grandmothers": "grandfathers",
+    "grandnephew": "grandniece",
+    "grandniece": "grandnephew",
+    "grandnephews": "grandnieces",
+    "grandnieces": "grandnephews",
+    "hag": "geezer",
+    "hags": "geezers",
+    "his": "her",
+    "her": "him",
+    "himself": "herself",
+    "herself": "himself",
+    "househusband": "housewife",
+    "housewife": "househusband",
+    "househusbands": "housewives",
+    "housewives": "househusbands",
+    "gentlemen": "ladies",
+    "ladies": "gentlemen",
+    "gentleman": "lady",
+    "lady": "gentleman",
+    "gentleman's": "lady's",
+    "lady's": "gentleman's",
+    "landlords": "landladies",
+    "landladies": "landlords",
+    "landlord": "landlady",
+    "landlady": "landlord",
+    "lad": "lass",
+    "lass": "lad",
+    "laddie": "lassie",
+    "lassie": "laddie",
+    "pa": "ma",
+    "ma": "pa",
+    "ma'am": "sir",
+    "maam": "sir",
+    "madam": "sir",
+    "maiden": "bachelor",
+    "maidens": "bachelors",
+    "manservant": "maidservant",
+    "maidservant": "manservant",
+    "manservants": "maidservants",
+    "maidservants": "manservants",
+    "paternal": "maternal",
+    "maternal": "paternal",
+    "paternity": "maternity",
+    "maternity": "paternity",
+    "patriarch": "matriach",
+    "matriach": "patriarch",
+    "patriarchs": "matriachs",
+    "matriachs": "patriarchs",
+    "mister": "missus",
+    "missus": "mister",
+    "dad": "mom",
+    "mom": "dad",
+    "daddies": "mommies",
+    "mommies": "daddies",
+    "daddy": "mommy",
+    "mommy": "daddy",
+    "dads": "moms",
+    "moms": "dads",
+    "father": "mother",
+    "mother": "father",
+    "fathered": "mothered",
+    "mothered": "fathered",
+    "fatherhood": "motherhood",
+    "motherhood": "fatherhood",
+    "fatherly": "motherly",
+    "motherly": "fatherly",
+    "fathers": "mothers",
+    "mothers": "fathers",
+    "mr": "ms",
+    "mrs": "mr",
+    "ms": "mr",
+    "nephew": "niece",
+    "niece": "nephew",
+    "nephews": "nieces",
+    "nieces": "nephews",
+    "monk": "nun",
+    "nun": "friar",
+    "friar": "nun",
+    "nunneries": "monastaries",
+    "nunnery": "monastary",
+    "monks": "nuns",
+    "nuns": "friars",
+    "friars": "nuns",
+    "priest": "priestess",
+    "priestess": "priest",
+    "priests": "priestesses",
+    "priestesses": "priests",
+    "prince": "princess",
+    "princess": "prince",
+    "princes": "princesses",
+    "princesses": "princes",
+    "king": "queen",
+    "queen": "king",
+    "kings": "queens",
+    "queens": "kings",
+    "schoolboy": "schoolgirl",
+    "schoolgirl": "schoolboy",
+    "schoolboys": "schoolgirls",
+    "schoolgirls": "schoolboys",
+    "he": "she",
+    "she": "he",
+    "he'd": "she'd",
+    "she'd": "he'd",
+    "he'll": "she'll",
+    "she'll": "he'll",
+    "he's": "she's",
+    "she's": "he's",
+    "hes": "shes",
+    "shes": "hes",
+    "sis": "bro",
+    "brother": "sister",
+    "sister": "brother",
+    "brotherhood": "sisterhood",
+    "sisterhood": "brotherhood",
+    "fraternal": "sisterly",
+    "sisterly": "brotherly",
+    "brotherly": "sisterly",
+    "brothers": "sisters",
+    "sisters": "brothers",
+    "sorceror": "sorceress",
+    "sorceress": "sorceror",
+    "sorcerors": "sorceresses",
+    "sorceresses": "sorcerors",
+    "fraternity": "sorority",
+    "sorority": "fraternity",
+    "spinster": "bachelor",
+    "spinsters": "bachelors",
+    "stepson": "stepdaughter",
+    "stepdaughter": "stepson",
+    "stepsons": "stepdaughters",
+    "stepdaughters": "stepsons",
+    "stepfather": "stepmother",
+    "stepmother": "stepfather",
+    "stepfathers": "stepmothers",
+    "stepmothers": "stepfathers",
+    "widower": "widow",
+    "widow": "widower",
+    "widowers": "widows",
+    "widows": "widowers",
+    "husband": "wife",
+    "wife": "husband",
+    "wizard": "witch",
+    "witch": "warlock",
+    "warlock": "witch",
+    "warlocks": "witches",
+    "witches": "wizards",
+    "wizards": "witches",
+    "husbands": "wives",
+    "wives": "husbands",
+    "man": "woman",
+    "woman": "man",
+    "man's": "woman's",
+    "woman's": "man's",
+    "manhood": "womanhood",
+    "womanhood": "manhood",
+    "manly": "womanly",
+    "womanly": "manly",
+    "men": "women",
+    "women": "men",
+    "mens": "womens",
+    "womens": "mens",
+    "him": "her",
+    "auntie": "uncle",
+    "mademoiselle": "sir",
+    "macho": "femme",
+    "femme": "macho",
+    "guy": "gal",
+    "guys": "gals"
+}

augly/tests/text_tests/functional_unit_test.py

@@ -19,10 +19,14 @@ def test_import(self) -> None:
     def setUp(self):
         random.seed(123)
         self.texts = [
-            "The quick brown 'fox' couldn't jump over the green, grassy hill."
+            "The quick brown 'fox' couldn't jump over the green, grassy hill.",
         ]
         self.priority_words = ["green", "grassy", "hill"]
 
+        self.fairness_texts = [
+            "The king and queen have a son named Raj and a daughter named Amanda.",
+        ]
+
     def test_apply_lambda(self) -> None:
         augmented_apply_lambda = txtaugs.apply_lambda(self.texts)
         self.assertTrue(augmented_apply_lambda[0] == self.texts[0])
@@ -407,6 +411,15 @@ def test_split_words(self) -> None:
             == "The quick brown 'fox' couldn't jump ov er the g reen, g rassy hi ll."
         )
 
+    def test_swap_gendered_words(self) -> None:
+        augmented_gender_swap_words = txtaugs.swap_gendered_words(
+            self.fairness_texts[0], aug_word_p=0.3
+        )
+        self.assertTrue(
+            augmented_gender_swap_words
+            == "The queen and king have a daughter named Raj and a son named Amanda.",
+        )
+
 
 if __name__ == "__main__":
     unittest.main()

augly/tests/text_tests/transforms_unit_test.py

@@ -66,6 +66,10 @@ def setUpClass(cls):
         ]
         cls.priority_words = ["green", "grassy", "hill"]
 
+        cls.fairness_texts = [
+            "The king and queen have a son named Raj and a daughter named Amanda.",
+        ]
+
     def test_ApplyLambda(self) -> None:
         augmented_apply_lambda = txtaugs.ApplyLambda()(
             self.texts, metadata=self.metadata
@@ -286,6 +290,19 @@ def test_SplitWords(self) -> None:
             are_equal_metadata(self.metadata, self.expected_metadata["split_words"]),
         )
 
+    def test_SwapGenderedWords(self) -> None:
+        augmented_words = txtaugs.SwapGenderedWords()(
+            self.fairness_texts, metadata=self.metadata
+        )
+
+        self.assertTrue(
+            augmented_words[0]
+            == "The queen and king have a daughter named Raj and a son named Amanda.",
+        )
+        self.assertTrue(
+            are_equal_metadata(self.metadata, self.expected_metadata["swap_gendered_words"]),
+        )
+
 
 if __name__ == "__main__":
     unittest.main()

augly/text/__init__.py

@@ -17,6 +17,7 @@
     replace_words,
     simulate_typos,
     split_words,
+    swap_gendered_words,
 )
 
 from augly.text.intensity import (
@@ -33,6 +34,7 @@
     replace_words_intensity,
     simulate_typos_intensity,
     split_words_intensity,
+    swap_gendered_words_intensity,
 )
 
 from augly.text.transforms import (
@@ -49,6 +51,7 @@
     ReplaceWords,
     SimulateTypos,
     SplitWords,
+    SwapGenderedWords,
 )
 
 __all__ = [
@@ -67,6 +70,7 @@
     "ReplaceWords",
     "SimulateTypos",
     "SplitWords",
+    "SwapGenderedWords",
     "apply_lambda",
     "get_baseline",
     "insert_punctuation_chars",
@@ -80,6 +84,7 @@
     "replace_words",
     "simulate_typos",
     "split_words",
+    "swap_gendered_words",
     "apply_lambda_intensity",
     "get_baseline_intensity",
     "insert_punctuation_chars_intensity",
@@ -93,4 +98,5 @@
     "replace_words_intensity",
     "simulate_typos_intensity",
     "split_words_intensity",
+    "swap_gendered_words_intensity",
 ]