adding documenation/examples and cleaning imports

app.py

@@ -1,15 +1,11 @@
-
-
-
-from typing import Optional
 import gradio as gr
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
 import torch
+from matplotlib.ticker import MaxNLocator
 from transformers import AutoModelForTokenClassification, AutoTokenizer
 from transformers import pipeline
-import pandas as pd
-import numpy as np
-import matplotlib.pyplot as plt
-from matplotlib.ticker import MaxNLocator
 
 
 # DATASETS
@@ -189,6 +185,7 @@ def get_gendered_token_ids(tokenizer):
     male_gendered_token_ids.append(subword_man_token_id)
     female_gendered_token_ids.append(subword_woman_token_id)
 
+    # Confirming all tokens are in vocab
     assert tokenizer.unk_token_id not in male_gendered_token_ids
     assert tokenizer.unk_token_id not in female_gendered_token_ids
 
@@ -460,6 +457,87 @@ def predict_gender_pronouns(
     )
 
 
+title = "Causing Gender Pronouns"
+description = """
+## Intro 
+This work investigates how we can cause LLMs to change their gender pronoun predictions.
+
+We do this by first considering plausible data generating processes for the type of datasets upon which the LLMs were pretrained. The data generating process is usually not revealed by the dataset alone, and instead requires (ideally well-informed) assumptions about what may have caused both the features and the labels to appear in the dataset. 
+
+An example of an assumed data generating process for the [wiki-bio dataset](https://huggingface.co/datasets/wiki_bio) is shown in the form of a causal DAG in  [causing_gender_pronouns](https://huggingface.co/spaces/emilylearning/causing_gender_pronouns), an earlier but better documented version of this Space.
+
+Once we have a causal DAG, we can identify likely confounding variables that have causal influences on both the features and the labels in a model. We can include those variables in our model train-time and/or at inference-time to produce spurious correlations, exposing potentially surprising learned relationships between the features and labels.
+
+## This demo 
+Here we can experiment with these spurious correlations in both BERT and BERT-like pre-trained models as well as two types of fine-tuned models. These fine-tuned models were trained with a specific gender-pronoun-predicting task, and with potentially confounding metadata either excluded (`none_metadata` variants) or included (`birth_date_metadata` and `subreddit_metadata` variants) in the text samples at train time.
+See [source code](https://github.com/2dot71mily/causing_gendering_pronouns_two) for more details.
+
+For the gender-pronoun-predicting task, the following non-gender-neutral terms are `[MASKED]` for gender-prediction.
+```
+gendered_lists = [
+    ['he', 'she'],
+    ['him', 'her'],
+    ['his', 'hers'],
+    ["himself", "herself"],
+    ['male', 'female'],
+    ['man', 'woman'],
+    ['men', 'women'],
+    ["husband", "wife"],
+    ['father', 'mother'],
+    ['boyfriend', 'girlfriend'],
+    ['brother', 'sister'],
+    ["actor", "actress"],
+    ["##man", "##woman"]]
+```
+
+What we are looking for in this demo is a dose-response relationship, where a larger intervention in the treatment (the text injected in the inference sample, displayed on the x-axis) produces a larger response in the output (the average softmax probability of a gendered pronoun, displayed on the y-axis).
+
+For the `wiki-bio` models the x-axis is simply the `date`, ranging from 1800 - 1999, which is injected into the text. For the `reddit` models, it is the `subreddit` name, which is prepended to the inference text samples, with subreddits that have a larger percentage of self-reported female commentors increasing to the right (following the methodology in http://bburky.com/subredditgenderratios/, we just copied over the entire list of subreddits that had a Minimum subreddit size of 400,000).
+
+
+## What you can do:
+
+- 	Pick a fine-tuned model type.
+- 	Pick optional BERT, and/or BERT-like model.
+- 	Decide if you want to see BERT-like model’s predictions normalized to only those predictions that are gendered (ignoring their gender-neutral predictions). 
+    -   Note, DistilBERT in particular does a great job at predicting gender-neutral terms, so this normalization can look pretty noisy.
+    -   This normalization is not required for our fine-tuned models, which are forced to make a binary prediction.
+- 	Decide if you want to see the baseline prediction (from neutral or no text injection into your text sample) in the plot.
+- 	Come up with a text sample!
+    - 	Any term included that is from the `gendered_lists` above will be masked out for prediction.
+    -	In the case of `wiki-bio`, any appearance of the word `DATE` will be replaced with the year shown on the x-axis. 
+       -	If no `DATE` is included, the phrase `Born in DATE…` will be prepended to your text sample.
+    -	In the case of `reddit`, the `subreddit` names shown on the x-axis (or shown more clearly in the associated dataframe) will be prepended to your text sample).
+"""
+
+article = "The source code to generate the fine-tuned models can be found/reproduced here: https://github.com/2dot71mily/causing_gendering_pronouns_two"
+
+scientist_example = [
+    REDDIT,
+    [BERT_LIKE_MODELS[0]],
+    "True",
+    "True",
+    'She was a very well regarded scientist and her work won many awards.',
+]
+
+death_date_example = [
+    WIKIBIO,
+    [BERT_LIKE_MODELS],
+    "False",
+    "True",
+    'Died in DATE, she was recognized for her great accomplishments to the field of teaching.'
+]
+
+
+neg_reddit_example = [
+    REDDIT,
+    [BERT_LIKE_MODELS[0]],
+    "False",
+    "True",
+    'She is not good at anything. The work she does is always subpar.'
+]
+
+
 gr.Interface(
     fn=predict_gender_pronouns,
     inputs=[
@@ -510,4 +588,8 @@ gr.Interface(
             label="Table of softmax probability pronouns predicted male",
         ),
     ],
+    title=title,
+    description=description,
+    article=article,
+    examples=[scientist_example, death_date_example, neg_reddit_example]
 ).launch(debug=True, share=True)