dslighting 1.3.9__py3-none-any.whl → 1.7.6__py3-none-any.whl

dslighting/registry/jigsaw-toxic-comment-classification-challenge/prepare_val.py

@@ -0,0 +1,88 @@
+from pathlib import Path
+
+from sklearn.model_selection import train_test_split
+
+from mlebench.utils import extract, read_csv
+
+from .classes import CLASSES
+
+
+def prepare(raw: Path, public: Path, private: Path):
+    # extract only what is needed
+    extract(raw / "train.csv.zip", raw)
+    extract(raw / "test.csv.zip", raw)
+    extract(raw / "test_labels.csv.zip", raw)
+    extract(raw / "sample_submission.csv.zip", raw)
+
+    # the test set is provided, so we dont have to split the train set nor form the sample submission
+    train_with_labels = read_csv(raw / "train.csv")
+    test_without_labels = read_csv(raw / "test.csv")
+    answers = read_csv(raw / "test_labels.csv")
+    sample_submission = read_csv(raw / "sample_submission.csv")
+    sample_submission[CLASSES] = 0.5
+
+    # save to public
+    train_with_labels.to_csv(public / "train.csv", index=False)
+    test_without_labels.to_csv(public / "test.csv", index=False)
+    sample_submission.to_csv(public / "sample_submission.csv", index=False)
+
+    # save to private
+    answers.to_csv(private / "test.csv", index=False)
+
+    assert len(answers) == len(
+        sample_submission
+    ), "Private test set and sample submission should be of the same length"
+
+    assert sorted(answers["id"]) == sorted(
+        test_without_labels["id"]
+    ), "Private and Public test IDs should match"
+    assert sorted(sample_submission["id"]) == sorted(
+        test_without_labels["id"]
+    ), "Public test and sample submission IDs should match"
+    assert (
+        len(set(train_with_labels["id"]) & set(test_without_labels["id"])) == 0
+    ), "Train and test IDs should not overlap"
+
+    # ==================================================================
+    # === New code for creating the validation set starts here ===
+    # The code above this line is untouched to ensure original outputs
+    # remain identical.
+    # ==================================================================
+
+    # 1. Define new paths and create the directories for the validation set.
+    public_val = public.parent / "public_val"
+    private_val = private.parent / "private_val"
+    public_val.mkdir(exist_ok=True)
+    private_val.mkdir(exist_ok=True)
+
+    # 2. Split the original training data to create a new, smaller training set
+    # and a new validation set. The size of the validation set will be the same
+    # as the size of the original test set.
+    validation_set_size = len(test_without_labels)
+    train_val, test_val_with_labels = train_test_split(
+        train_with_labels,
+        test_size=validation_set_size,
+        random_state=42,  # Use a fixed random state for reproducibility
+    )
+
+    # 3. Prepare the validation set files, mirroring the original test set structure.
+    # The public part (input features, without labels)
+    test_val_without_labels = test_val_with_labels[["id", "comment_text"]].copy()
+
+    # The private part (ground truth labels for the validation set)
+    answers_val = test_val_with_labels[["id"] + CLASSES].copy()
+
+    # 4. Create a sample submission file for the new validation set,
+    # mirroring the original sample submission format.
+    sample_submission_val = test_val_without_labels[["id"]].copy()
+    sample_submission_val[CLASSES] = 0.5
+
+    # 5. Save the new sets to the 'public_val' and 'private_val' directories,
+    # using the same filenames as in the original 'public' and 'private' dirs.
+    # Save to public_val
+    train_val.to_csv(public_val / "train.csv", index=False)
+    test_val_without_labels.to_csv(public_val / "test.csv", index=False)
+    sample_submission_val.to_csv(public_val / "sample_submission.csv", index=False)
+
+    # Save to private_val
+    answers_val.to_csv(private_val / "test.csv", index=False)

dslighting/registry/jigsaw-unintended-bias-in-toxicity-classification/checksums.yaml

@@ -0,0 +1,7 @@
+private:
+  test.csv: 57d838e932f0d2a66785f7b719adfd91
+public:
+  sample_submission.csv: 6f6dce475d8d7d068e965f57dd491e03
+  test.csv: a887551e003361bad9e054d7501333cd
+  train.csv: 7a687c299462dd009e90db97ac053eef
+zip: e7ca6425042681da2a3d85c55880626e

dslighting/registry/jigsaw-unintended-bias-in-toxicity-classification/config.yaml

@@ -0,0 +1,36 @@
+id: jigsaw-unintended-bias-in-toxicity-classification
+name: Jigsaw Unintended Bias in Toxicity Classification
+competition_type: code
+awards_medals: true
+prizes:
+  - position: 1
+    value: 12000
+  - position: 2
+    value: 10000
+  - position: 3
+    value: 8000
+  - position: 4
+    value: 5000
+  - position: 5
+    value: 5000
+  - position: 6
+    value: 5000
+  - position: 7
+    value: 5000
+  - position: 8
+    value: 5000
+  - position: 9
+    value: 5000
+  - position: 10
+    value: 5000
+description: mlebench/competitions/jigsaw-unintended-bias-in-toxicity-classification/description.md
+
+dataset:
+  answers: jigsaw-unintended-bias-in-toxicity-classification/prepared/private/test.csv
+  sample_submission: jigsaw-unintended-bias-in-toxicity-classification/prepared/public/sample_submission.csv
+
+grader:
+  name: jigsaw-unintended-bias-in-toxicity-classification-score
+  grade_fn: mlebench.competitions.jigsaw-unintended-bias-in-toxicity-classification.grade:grade
+
+preparer: mlebench.competitions.jigsaw-unintended-bias-in-toxicity-classification.prepare:prepare

dslighting/registry/jigsaw-unintended-bias-in-toxicity-classification/description.md

@@ -0,0 +1,286 @@
+## Description
+
+Can you help detect toxic comments ― *and* minimize unintended model bias? That's your challenge in this competition.
+
+The Conversation AI team, a research initiative founded by [Jigsaw](https://jigsaw.google.com/) and Google (both part of Alphabet), builds technology to protect voices in conversation. A main area of focus is machine learning models that can identify toxicity in online conversations, where toxicity is defined as anything *rude, disrespectful or otherwise likely to make someone leave a discussion*.
+
+Last year, in the [Toxic Comment Classification Challenge](https://www.kaggle.com/c/jigsaw-toxic-comment-classification-challenge#description), you built multi-headed models to recognize toxicity and several subtypes of toxicity. This year's competition is a related challenge: building toxicity models that operate fairly across a diverse range of conversations.
+
+Here's the background: When the Conversation AI team first built toxicity models, they found that the models [incorrectly learned to associate](https://medium.com/the-false-positive/unintended-bias-and-names-of-frequently-targeted-groups-8e0b81f80a23) the names of frequently attacked identities with toxicity. Models predicted a high likelihood of toxicity for comments containing those identities (e.g. "gay"), even when those comments were not actually toxic (such as "I am a gay woman"). This happens because training data was pulled from available sources where unfortunately, certain identities are overwhelmingly referred to in offensive ways. Training a model from data with these imbalances risks simply mirroring those biases back to users.
+
+In this competition, you're challenged to build a model that recognizes toxicity and minimizes this type of unintended bias with respect to mentions of identities. You'll be using a dataset labeled for identity mentions and optimizing a metric designed to measure unintended bias. Develop strategies to reduce unintended bias in machine learning models, and you'll help the Conversation AI team, and the entire industry, build models that work well for a wide range of conversations.
+
+*Disclaimer: The dataset for this competition contains text that may be considered profane, vulgar, or offensive.*
+
+### Acknowledgments
+
+The Conversation AI team would like to thank Civil Comments for making this dataset available publicly and the [Online Hate Index Research Project](http://dh.berkeley.edu/projects/online-hate-index-ohi-research-project?utm_source=BCNM+Subscribers&utm_campaign=d5d78bba5e-natasha-schull-oct12_COPY_01&utm_medium=email&utm_term=0_eb59bfff9e-d5d78bba5e-281420185) at [D-Lab](https://dlab.berkeley.edu/), University of California, Berkeley, whose labeling survey/instrument informed the dataset labeling. We'd also like to thank everyone who has contributed to Conversation AI's research, especially those who took part in our last competition, the success of which led to the creation of this challenge.
+
+## Evaluation
+
+### Competition Evaluation
+
+This competition will use a newly developed metric that combines several submetrics to balance overall performance with various aspects of unintended bias.
+
+First, we'll define each submetric.
+
+### Overall AUC
+
+This is the ROC-AUC for the full evaluation set.
+
+### Bias AUCs
+
+To measure unintended bias, we again calculate the ROC-AUC, this time on three specific subsets of the test set for each identity, each capturing a different aspect of unintended bias. You can learn more about these metrics in Conversation AI's recent paper *[Nuanced Metrics for Measuring Unintended Bias with Real Data in Text Classification](https://arxiv.org/abs/1903.04561)*.
+
+**Subgroup AUC**: Here, we restrict the data set to only the examples that mention the specific identity subgroup. *A low value in this metric means the model does a poor job of distinguishing between toxic and non-toxic comments that mention the identity*.
+
+**BPSN (Background Positive, Subgroup Negative) AUC**: Here, we restrict the test set to the non-toxic examples that mention the identity and the toxic examples that do not. *A low value in this metric means that the model confuses non-toxic examples that mention the identity with toxic examples that do not*, likely meaning that the model predicts higher toxicity scores than it should for non-toxic examples mentioning the identity.
+
+**BNSP (Background Negative, Subgroup Positive) AUC**: Here, we restrict the test set to the toxic examples that mention the identity and the non-toxic examples that do not. *A low value here means that the model confuses toxic examples that mention the identity with non-toxic examples that do not*, likely meaning that the model predicts lower toxicity scores than it should for toxic examples mentioning the identity.
+
+### Generalized Mean of Bias AUCs
+
+To combine the per-identity Bias AUCs into one overall measure, we calculate their generalized mean as defined below:
+
+$$
+M_p\left(m_s\right)=\left(\frac{1}{N} \sum_{s=1}^N m_s^p\right)^{\frac{1}{p}}
+$$
+
+where:
+$M_p=$ the $p$ th power-mean function
+$m_s=$ the bias metric $m$ calulated for subgroup $S$
+$N=$ number of identity subgroups
+
+For this competition, we use a $p$ value of -5 to encourage competitors to improve the model for the identity subgroups with the lowest model performance.
+
+### Final Metric
+
+We combine the overall AUC with the generalized mean of the Bias AUCs to calculate the final model score:
+
+$$
+\text { score }=w_0 A U C_{\text {overall }}+\sum_{a=1}^A w_a M_p\left(m_{s, a}\right)
+$$
+where:
+$A=$ number of submetrics $(3)$
+$m_{s, a}=$ bias metric for identity subgroup $s$ using submetric $a$
+$w_a=$ a weighting for the relative importance of each submetric; all four $w$ values set to 0.25
+
+**While the leaderboard will be determined by this single number, we highly recommend looking at the individual submetric results, [as shown in this kernel](https://www.kaggle.com/dborkan/benchmark-kernel), to guide you as you develop your models.**
+
+### Submission File
+
+```
+id,prediction
+7000000,0.0
+7000001,0.0
+etc.
+
+```
+
+## Prizes
+
+We expect there to be a large variety of ways to mitigate bias and, like other Kaggle competitions, we expect tight competition. We also recognize that bias is a complex and nuanced idea that can only be measured imperfectly. Our goal is for competitors to develop, evaluate, and compare as many bias mitigation strategies as possible, and so we'll be rewarding as many of them as we can.
+
+- 1st Place - $12,000
+- 2nd Place - $10,000
+- 3rd Place - $8,000
+- 4th Place - $5,000
+- 5th Place - $5,000
+- 6th Place - $5,000
+- 7th Place - $5,000
+- 8th Place - $5,000
+- 9th Place - $5,000
+- 10th Place - $5,000
+
+## Timeline
+
+- **June 19, 2019** - Entry deadline. You must accept the competition rules before this date in order to compete.
+- **June 19, 2019** - Team Merger deadline. This is the last day participants may join or merge teams.
+- **June 26, 2019** - Final submission deadline. After this date, we will not be taking any more submissions. Remember to select your two best submissions to be rescored during the re-run period.
+- **June 27 to July 19, 2019** - Kernel Re-runs on Private Test Set.
+
+All deadlines are at 11:59 PM UTC on the corresponding day unless otherwise noted. The competition organizers reserve the right to update the contest timeline if they deem it necessary.
+
+## FAQ
+
+### How does this metric compare with other measures of bias and fairness?
+
+There are a wide range of fairness criteria and bias measurement metrics available in the literature. The metric used here is similar to the Equality of Odds criteria presented in *[Equality of Opportunity in Supervised Learning](https://arxiv.org/pdf/1610.02413.pdf)* and other related metrics, in that it relies on having labeled test data broken down across the different identity groups under consideration and in that it allows for there to be a relationship between the identity groups and the concept being modeled. We believe this is a good fit for toxicity classification because we do expect there to be differences in the amount and severity of toxicity directed at different groups. Our metrics differ from other similar metrics in that they are threshold-agnostic, meaning that we evaluate on the raw model scores themselves, rather than converting the model into a binary threshold before evaluation. Please see our paper *[Nuanced Metrics for Measuring Unintended Bias with Real Data in Text Classification](https://arxiv.org/abs/1903.04561)* for more details on the bias metrics.
+
+### How can I calculate the individual Bias AUCs for my models?
+
+Please see the example in our [Benchmark Kernel](https://www.kaggle.com/dborkan/benchmark-kernel) to calculate the individual Bias AUCs. We highly recommend looking at these values regularly as you develop your models.
+
+### What are the benchmarks for this competition?
+
+We provide three benchmarks for this competition:
+
+- **Benchmark Kernel:** A simple CNN model provided as an example submission in the [Benchmark Kernel](https://www.kaggle.com/dborkan/benchmark-kernel).
+- **TOXICITY@1 Benchmark:** Perspective API's earliest toxicity model, launched in February 2017.
+- **TOXICITY@6 Benchmark:** Perspective API's current toxicity model, launched in August 2018.
+
+The Perspective toxicity model has undergone several bias mitigation steps between TOXICITY@1 and TOXICITY@6, which you can learn about in Jigsaw's two blog posts on [unintended bias](https://medium.com/the-false-positive/unintended-bias-and-names-of-frequently-targeted-groups-8e0b81f80a23) and [transparency](https://medium.com/the-false-positive/increasing-transparency-in-machine-learning-models-311ee08ca58a). As shown in *[Nuanced Metrics for Measuring Unintended Bias with Real Data in Text Classification](https://arxiv.org/abs/1903.04561)*, these changes focused on reducing false positive bias on short comments (BPSN AUC), where unintended bias was strongest in TOXICITY@1. On the full Civil Comments set, which evaluates a range of comment lengths, we see less difference between these two models. We look forward to seeing competitors further improve the model and reduce unintended bias beyond these benchmarks.
+
+### How was the data collected for this challenge?
+
+The comments in this challenge come from an archive of the [Civil Comments](https://medium.com/@aja_15265/saying-goodbye-to-civil-comments-41859d3a2b1d) platform, a commenting plugin for independent news sites. These public comments were created from 2015 - 2017 and appeared on approximately 50 English-language news sites across the world. When Civil Comments shut down in 2017, they chose to make the public comments available in a lasting open archive to enable future research. The original data, published on [figshare](https://figshare.com/articles/data_json/7376747), includes the public comment text, some associated metadata such as article IDs, timestamps and commenter-generated "civility" labels, but does not include user ids. Jigsaw extended this dataset by adding additional labels for toxicity and identity mentions.
+
+### Who labeled the data? How were the labels verified?
+
+Toxicity and identity mentions were labeled via the crowd rating platform [Figure Eight](https://www.figure-eight.com/). Label quality was enforced using test questions, a system where approximately 10% of the comments raters see already have known correct labels. Raters who miss too many of these labels are disqualified from rating. We recognize that toxicity and identity can be subjective, so we collect labels from up to 10 people per comment, to capture a range of opinions.
+
+### Why were these particular identities selected?
+
+This set of identities was designed to balance the coverage of identities, crowd rater accuracy, and ensure that each labeled identity has enough examples in the final data set to provide meaningful results.
+
+### Why are only some of the comments labeled for identity references?
+
+When designing any human rating task, it's important that the concept raters are looking for (whether it's toxicity, identities, or anything else) appears with some level of frequency, to keep the raters engaged. With this data, we used a combination of model predictions and word matching to find approximately 250,000 comments that were likely to contain identity references. We combined that data with ~250,000 randomly selected comments to generate a set of ~500,000 to be labeled, where we could expect about 50% of comments to have identity references.
+
+### Will the data sets in this competition be released after the competition finishes?
+
+Yes! The full dataset, including the test set and all labels, will be released under a Creative Commons license after the competition ends. The comments from the training set and associated metadata from Civil Comments are already released on [figshare](https://figshare.com/articles/data_json/7376747).
+
+### Can I use external datasets?
+
+You may use any additional datasets, as long as they are appropriately licensed to be used for this purpose and shared publicly. Please post a link to your external dataset(s) on the [official external data forum thread](https://www.kaggle.com/c/jigsaw-unintended-bias-in-toxicity-classification/discussion/87235).
+
+### Can I add additional labels the training data?
+
+Feel free! Please post a link to your newly labeled dataset on the [official external data forum thread](https://www.kaggle.com/c/jigsaw-unintended-bias-in-toxicity-classification/discussion/87235).
+
+## Kernels Requirements
+
+### This is a Kernels-only competition
+
+Submissions to this competition must be made through Kernels. In order for the "Submit to Competition" button to be active after a commit, the following conditions must be met:
+
+- CPU Kernel <= 9 hours run-time
+- GPU Kernel <= 2 hours run-time
+- No internet access enabled
+- External data, freely & publicly available, is allowed, including pre-trained models
+- No use of other kernels as inputs into your submission kernel. This includes utility scripts.
+- No custom packages enabled in kernels
+- Submission file must be named "submission.csv"
+
+Please see the [Kernels-only FAQ](https://www.kaggle.com/docs/competitions#kernels-only-FAQ) for more information on how to submit.
+
+## Citation
+
+cjadams, Daniel Borkan, inversion, Jeffrey Sorensen, Lucas Dixon, Lucy Vasserman, nithum. (2019). Jigsaw Unintended Bias in Toxicity Classification. Kaggle. https://kaggle.com/competitions/jigsaw-unintended-bias-in-toxicity-classification
+
+# **Dataset Description**
+
+*Disclaimer: The dataset for this competition contains text that may be considered profane, vulgar, or offensive.*
+
+## Background
+
+At the end of 2017 the [Civil Comments](https://medium.com/@aja_15265/saying-goodbye-to-civil-comments-41859d3a2b1d) platform shut down and chose make their ~2m public comments from their platform available in a lasting open archive so that researchers could understand and improve civility in online conversations for years to come. Jigsaw sponsored this effort and extended annotation of this data by human raters for various toxic conversational attributes.
+
+In the data supplied for this competition, the text of the individual comment is found in the `comment_text` column. Each comment in Train has a toxicity label (`target`), and models should predict the `target` toxicity for the Test data. This attribute (and all others) are fractional values which represent the fraction of human raters who believed the attribute applied to the given comment. For evaluation, test set examples with `target >= 0.5` will be considered to be in the positive class (toxic).
+
+The data also has several additional toxicity subtype attributes. Models do not need to predict these attributes for the competition, they are included as an additional avenue for research. Subtype attributes are:
+
+- severe_toxicity
+- obscene
+- threat
+- insult
+- identity_attack
+- sexual_explicit
+
+Additionally, a subset of comments have been labelled with a variety of identity attributes, representing the identities that are *mentioned* in the comment. The columns corresponding to identity attributes are listed below. **Only identities with more than 500 examples in the test set (combined public and private) will be included in the evaluation calculation. These identities are shown in bold.**
+
+- **male**
+- **female**
+- transgender
+- other_gender
+- heterosexual
+- **homosexual_gay_or_lesbian**
+- bisexual
+- other_sexual_orientation
+- **christian**
+- **jewish**
+- **muslim**
+- hindu
+- buddhist
+- atheist
+- other_religion
+- **black**
+- **white**
+- asian
+- latino
+- other_race_or_ethnicity
+- physical_disability
+- intellectual_or_learning_disability
+- **psychiatric_or_mental_illness**
+- other_disability
+
+Note that the data contains different comments that can have the exact same text. Different comments that have the same text may have been labeled with different targets or subgroups.
+
+## Examples
+
+Here are a few examples of comments and their associated toxicity and identity labels. Label values range from 0.0 - 1.0 represented the fraction of raters who believed the label fit the comment.
+
+**Comment**: *i'm a white woman in my late 60's and believe me, they are not too crazy about me either!!*
+
+- **Toxicity Labels:** All 0.0
+- **Identity Mention Labels:** female: 1.0, white: 1.0 (all others 0.0)
+
+**Comment**: *Why would you assume that the nurses in this story were women?*
+
+- **Toxicity Labels:** All 0.0
+- **Identity Mention Labels:** female: 0.8 (all others 0.0)
+
+**Comment**: *Continue to stand strong LGBT community. Yes, indeed, you'll overcome and you have.*
+
+- **Toxicity Labels:** All 0.0
+- **Identity Mention Labels:** homosexual_gay_or_lesbian: 0.8, bisexual: 0.6, transgender: 0.3 (all others 0.0)
+
+In addition to the labels described above, the dataset also provides metadata from Jigsaw's annotation: `toxicity_annotator_count` and `identity_annotator_count`, and metadata from Civil Comments: `created_date`, `publication_id`, `parent_id`, `article_id`, `rating`, `funny`, `wow`, `sad`, `likes`, `disagree`. Civil Comments' label `rating` is the civility rating Civil Comments users gave the comment.
+
+## Labelling Schema
+
+To obtain the toxicity labels, each comment was shown to up to 10 annotators*. Annotators were asked to: "Rate the toxicity of this comment"
+
+- Very Toxic (a very hateful, aggressive, or disrespectful comment that is very likely to make you leave a discussion or give up on sharing your perspective)
+- Toxic (a rude, disrespectful, or unreasonable comment that is somewhat likely to make you leave a discussion or give up on sharing your perspective)
+- Hard to Say
+- Not Toxic
+
+These ratings were then aggregated with the `target` value representing the fraction of annotations that annotations fell within the former two categories.
+
+To collect the identity labels, annotators were asked to indicate all identities that were mentioned in the comment. An example question that was asked as part of this annotation effort was: "What genders are mentioned in the comment?"
+
+- Male
+- Female
+- Transgender
+- Other gender
+- No gender mentioned
+
+Again, these were aggregated into fractional values representing the fraction of raters who said the identity was mentioned in the comment.
+
+The distributions of labels and subgroup between Train and Test can be assumed to be similar, but not exact.
+
+- Note: Some comments were seen by many more than 10 annotators (up to thousands), due to sampling and strategies used to enforce rater accuracy.
+
+## Annotators
+
+Toxicity and identity labeling was done in 2018 on the Figure Eight crowd rating platform, which has since been purchased by Appen. Annotators came from all over the world, and all were proficient in English.
+
+Raters were compensated 1.5 cents per judgment, a rate that was set based on two factors: what rates were competitive on the platform and targeting an hourly wage appropriate for raters' locales.
+
+Figure Eight offers raters the option to select from multiple tasks with different pay, so rates need to be competitive to attract enough raters. At a rate of 1.5 cents per judgment, enough raters participated to complete this annotation in a few weeks. Following task completion, raters were given a satisfaction survey where the average score for "Pay" was 3.8 out of 5, which aligned with Figure Eight's recommendation to target pay to a satisfaction score greater than 3.5.
+
+Hourly rates for workers depend on how fast judgements were completed. Most raters will have earned between $0.90/hour (at one comment per minute) to $5.40/hour (at 6 comments per minute), which aligns with typical hourly pay in the geographic regions where most raters are located.
+
+Since this dataset was annotated in 2018, more [tools](https://success.appen.com/hc/en-us/articles/9557008940941-Guide-to-Fair-Pay) have become available to help set rates. Consequently, typical pay for data annotation is increasing globally.
+
+## File descriptions
+
+- **train.csv** - the training set, which includes toxicity labels and subgroups
+- **test.csv** - the test set, which does **not** include toxicity labels or subgroups
+- **sample_submission.csv** - a sample submission file in the correct format
+
+## Usage
+
+This dataset is released under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/), as is the [underlying comment text](https://figshare.com/articles/data_json/7376747).

dslighting/registry/jigsaw-unintended-bias-in-toxicity-classification/description_obfuscated.md

@@ -0,0 +1,85 @@
+# Task
+
+Build a model that recognizes toxicity and minimizes unintended bias with respect to mentions of identities.
+
+# Metric
+
+We combine several submetrics: An overall ROC-AUC for the full evaluation set, along with the ROC-AUCs on three specific subsets of the test set capturing different aspects of bias.
+
+The final model score looks like:
+
+$$
+\text { score }=w_0 A U C_{\text {overall }}+\sum_{a=1}^A w_a M_p\left(m_{s, a}\right)
+$$
+where:
+$A=$ number of submetrics $(3)$
+$m_{s, a}=$ bias metric for identity subgroup $s$ using submetric $a$
+$w_a=$ a weighting for the relative importance of each submetric; all four $w$ values set to 0.25
+
+Overall AUC: This is the ROC-AUC for the full evaluation set.
+
+## Bias AUCs
+
+To measure unintended bias, we again calculate the ROC-AUC, this time on three specific subsets of the test set for each identity, each capturing a different aspect of unintended bias. 
+
+**Subgroup AUC**: Here, we restrict the data set to only the examples that mention the specific identity subgroup. *A low value in this metric means the model does a poor job of distinguishing between toxic and non-toxic comments that mention the identity*.
+
+**BPSN (Background Positive, Subgroup Negative) AUC**: Here, we restrict the test set to the non-toxic examples that mention the identity and the toxic examples that do not. *A low value in this metric means that the model confuses non-toxic examples that mention the identity with toxic examples that do not*, likely meaning that the model predicts higher toxicity scores than it should for non-toxic examples mentioning the identity.
+
+**BNSP (Background Negative, Subgroup Positive) AUC**: Here, we restrict the test set to the toxic examples that mention the identity and the non-toxic examples that do not. *A low value here means that the model confuses toxic examples that mention the identity with non-toxic examples that do not*, likely meaning that the model predicts lower toxicity scores than it should for toxic examples mentioning the identity.
+
+### Generalized Mean of Bias AUCs
+
+To combine the per-identity Bias AUCs into one overall measure, we calculate their generalized mean as defined below:
+
+$$
+M_p\left(m_s\right)=\left(\frac{1}{N} \sum_{s=1}^N m_s^p\right)^{\frac{1}{p}}
+$$
+
+where:
+$M_p=$ the $p$ th power-mean function
+$m_s=$ the bias metric $m$ calulated for subgroup $S$
+$N=$ number of identity subgroups
+
+For this competition, we use a $p$ value of -5 to encourage competitors to improve the model for the identity subgroups with the lowest model performance.
+
+# Submission Format
+
+```
+id,prediction
+7000000,0.0
+7000001,0.0
+etc.
+
+```
+
+# Dataset
+
+The text of the individual comment is found in the `comment_text` column. Each comment in Train has a toxicity label (`target`), and models should predict the `target` toxicity for the Test data. This attribute (and all others) are fractional values which represent the fraction of human raters who believed the attribute applied to the given comment. For evaluation, test set examples with `target >= 0.5` will be considered to be in the positive class (toxic).
+
+The data also has several additional toxicity subtype attributes. Models do not need to predict these attributes for the competition, they are included as an additional avenue for research. Subtype attributes are:
+
+- severe_toxicity
+- obscene
+- threat
+- insult
+- identity_attack
+- sexual_explicit
+
+Additionally, a subset of comments have been labelled with a variety of identity attributes, representing the identities that are *mentioned* in the comment. The columns corresponding to identity attributes are listed below. Only identities shown below will be included in the evaluation calculation.
+
+- **male**
+- **female**
+- **homosexual_gay_or_lesbian**
+- **christian**
+- **jewish**
+- **muslim**
+- **black**
+- **white**
+- **psychiatric_or_mental_illness**
+
+## Files
+
+- **train.csv** - the training set, which includes toxicity labels and subgroups
+- **test.csv** - the test set, which does **not** include toxicity labels or subgroups
+- **sample_submission.csv** - a sample submission file in the correct format

dslighting/registry/jigsaw-unintended-bias-in-toxicity-classification/grade.py

@@ -0,0 +1,153 @@
+from typing import Tuple
+
+from pandas import DataFrame
+from sklearn.metrics import roc_auc_score
+
+from mlebench.grade_helpers import InvalidSubmissionError
+
+
+def _filter_for_subgroup(
+    answers: DataFrame, submission: DataFrame, identity_column: str, target_value: int = 1
+) -> Tuple[DataFrame, DataFrame]:
+    """
+    Restricts the data to only the examples that mention the specific identity subgroup.
+    A low value in this metric means the model does a poor job of distinguishing between toxic and non-toxic comments that mention the identity.
+    """
+
+    filtered_answers = answers[answers[identity_column] == target_value]
+    filtered_submission = submission[submission["id"].isin(filtered_answers["id"])]
+    return filtered_answers, filtered_submission
+
+
+def _filter_for_bpsn(
+    answers: DataFrame, submission: DataFrame, identity_column: str, target_value: int = 1
+) -> Tuple[DataFrame, DataFrame]:
+    """
+    Filter for BPSN (Background Positive, Subgroup Negative) AUC
+    Restricts the data to only the non-toxic examples that mention the identity and the toxic examples that do not.
+    A low value in this metric means that the model confuses non-toxic examples that mention the identity with toxic examples that do not, likely meaning that the model predicts higher toxicity scores than it should for non-toxic examples mentioning the identity.
+    """
+    filtered_answers = answers[
+        ((answers["toxicity"] == 0) & (answers[identity_column] == target_value))
+        | ((answers["toxicity"] == 1) & (answers[identity_column] != target_value))
+    ]
+    filtered_submission = submission[submission["id"].isin(filtered_answers["id"])]
+    return filtered_answers, filtered_submission
+
+
+def _filter_for_bnsp(
+    answers: DataFrame, submission: DataFrame, identity_column: str, target_value: int = 1
+) -> Tuple[DataFrame, DataFrame]:
+    """
+    Filter for BNSP (Background Negative, Subgroup Positive) AUC
+    Restricts the data to only the toxic examples that mention the identity and the non-toxic examples that do not.
+    A low value in this metric means that the model confuses toxic examples that mention the identity with non-toxic examples that do not, likely meaning that the model predicts lower toxicity scores than it should for toxic examples mentioning the identity.
+    """
+    filtered_answers = answers[
+        ((answers["toxicity"] == 1) & (answers[identity_column] == target_value))
+        | ((answers["toxicity"] == 0) & (answers[identity_column] != target_value))
+    ]
+    filtered_submission = submission[submission["id"].isin(filtered_answers["id"])]
+    return filtered_answers, filtered_submission
+
+
+def _generalized_mean(scores: list, p: int, identity_columns: list[str]) -> float:
+    return (sum([s**p for s in scores]) / len(identity_columns)) ** (1 / p)
+
+
+def prepare_for_metric(
+    submission: DataFrame, answers: DataFrame, identity_columns: list[str]
+) -> Tuple[DataFrame, DataFrame]:
+
+    # Ensure that the submission DataFrame contains the necessary columns
+    if "id" not in submission.columns:
+        raise InvalidSubmissionError("Submission DataFrame must have an 'id' column.")
+    if (
+        "prediction" not in submission.columns and "toxicity" not in submission.columns
+    ):  # Allow for the submission to be the CSV of answers, which has a "toxicity" column instead of a "prediction" column
+        raise InvalidSubmissionError("Submission DataFrame must have a 'prediction' column.")
+
+    # Ensure that the answers DataFrame contains the necessary columns
+    assert "id" in answers.columns, "Answers DataFrame must have an 'id' column."
+    assert "toxicity" in answers.columns, "Answers DataFrame must have a 'toxicity' column."
+
+    submission = submission.sort_values("id")
+    answers = answers.sort_values("id")
+
+    if (submission["id"].values != answers["id"].values).any():
+        raise InvalidSubmissionError("IDs in the submission and answers DataFrames do not match.")
+
+    # Ensure that all identity columns are present in the answers DataFrame
+    for identity_column in identity_columns:
+        assert (
+            identity_column in answers.columns
+        ), f"Answers DataFrame must have an '{identity_column}' column."
+
+    submission.rename(columns={"prediction": "toxicity"}, inplace=True)
+
+    # Convert continuous toxicity scores to binary toxicity labels
+    submission["toxicity"] = submission["toxicity"].apply(lambda x: 1 if x >= 0.5 else 0)
+    answers["toxicity"] = answers["toxicity"].apply(lambda x: 1 if x >= 0.5 else 0)
+
+    # Convert continuous identity columns to binary identity columns
+    for identity_column in identity_columns:
+        answers[identity_column] = answers[identity_column].apply(lambda x: 1 if x >= 0.5 else 0)
+
+    return submission, answers
+
+
+def grade(
+    submission: DataFrame,
+    answers: DataFrame,
+    identity_columns: list[str] = [
+        "male",
+        "female",
+        "homosexual_gay_or_lesbian",
+        "christian",
+        "jewish",
+        "muslim",
+        "black",
+        "white",
+        "psychiatric_or_mental_illness",
+    ],
+    p: int = -5,
+    w: float = 0.25,
+) -> float:
+    """
+    Computes the custom metric for Jigsaw Unintended Bias in Toxicity Classification.
+    See https://www.kaggle.com/competitions/jigsaw-unintended-bias-in-toxicity-classification/overview/evaluation for details on this metric.
+    """
+
+    submission, answers = prepare_for_metric(submission, answers, identity_columns)
+
+    overall_auc = roc_auc_score(answers["toxicity"], submission["toxicity"])
+
+    # To measure unintended bias, we again calculate the ROC-AUC, this time on three specific subsets of the test set for each identity, each capturing a different aspect of unintended bias.
+    bias_aucs = []
+    for identity_column in identity_columns:
+        subgroup_answers, subgroup_submission = _filter_for_subgroup(
+            answers, submission, identity_column
+        )
+        bpsn_answers, bpsn_submission = _filter_for_bpsn(answers, submission, identity_column)
+        bnsp_answers, bnsp_submission = _filter_for_bnsp(answers, submission, identity_column)
+
+        subgroup_aucs = roc_auc_score(subgroup_answers["toxicity"], subgroup_submission["toxicity"])
+        bpsn_aucs = roc_auc_score(bpsn_answers["toxicity"], bpsn_submission["toxicity"])
+        bnsp_aucs = roc_auc_score(bnsp_answers["toxicity"], bnsp_submission["toxicity"])
+
+        bias_aucs.append([subgroup_aucs, bpsn_aucs, bnsp_aucs])
+
+    # Calculate generalized mean for each identity column
+    generalized_means = [
+        _generalized_mean([bias_auc[i] for bias_auc in bias_aucs], p, identity_columns)
+        for i in range(3)  # there are 3 bias metrics
+    ]
+
+    # Combine the overall AUC with the generalized mean of the Bias AUCs
+    weighted_overall_auc = w * overall_auc
+    weighted_generalized_means = sum(
+        [w * generalized_means[i] for i in range(len(generalized_means))]
+    )
+    final_score = weighted_overall_auc + weighted_generalized_means
+
+    return final_score