Visual Bias Mitigator (VB-Mitigator)¶

The Visual Bias Mitigator is an open-source framework designed to empower researchers in the field of bias mitigation in computer vision. This codebase provides a comprehensive environment where users can easily implement, run, and evaluate existing visual bias mitigation methods.

With the increasing awareness of bias in AI systems, it is crucial for researchers to have access to robust tools that facilitate the exploration and development of mitigation approaches. The Visual Bias Mitigator (VB-Mitigator) serves this purpose by offering:

• 🚀 Implemented Methods: A collection of established visual bias mitigation methods that can be directly utilized, allowing researchers to replicate and understand their functionality.
• 🔧 Extensibility: Researchers can exploit this code-base to develop custom bias mitigation approaches tailored to their specific needs. The framework is designed with flexibility in mind, enabling easy integration of new approaches.
• 📊 Performance Comparison: The framework facilitates the performance comparison between custom methods and state-of-the-art.

The goal of this hands-on experience is to familiarize you with the core functionalities of the VB-Mitigator. You will learn how to set up an experiment using pre-defined configurations and run one or more of the implemented bias mitigation methods.

⏬ Clone the Git Repository¶

📦 Install the requirements¶

Once the installation finishes, Colab will prompt you to restart the session. Click the "RESTART SESSION" button to make the new libraries available. 🔄

📂 Set Up the Environment Path¶

Now that the project has been cloned, we need to navigate into the main vb-mitigator project directory.

The next step is crucial for the notebook to work correctly. We will add the project's root directory to Python's path. This tells Python to look for modules and scripts inside this folder, allowing us to import the custom components of the framework in the cells that follow.

🚀 Train a Baseline Model on Biased-MNIST¶

Now for the first experiment, we will train a standard, vanilla model (a regular classifier with no bias mitigation techniques) on a specially prepared dataset called Biased-MNIST. This will establish a baseline performance, showing us how a typical model behaves when confronted with biased data.

The Biased-MNIST Dataset¶

We've created a modified version of the classic MNIST dataset of handwritten digits. Here’s how the bias is introduced:

• Color-Label Correlation: In the training set, each digit label (0-9) is strongly correlated with a specific color. For example, most of '2s' are on red background, and most of '7s' are on blue background.
• Shortcut Learning: A standard model might learn to "cheat" by creating a simple shortcut: if it sees a blue color, it will guess '7' without actually learning to recognize the digit's shape.
• The Test Set: The test set is different; the colors are randomized. A model that has learned the color shortcut will perform very poorly on this test set, revealing its bias.

Running the Training¶

The command below executes the main training script, tools/train.py. We use the --cfg flag to point to configs/toy.yaml, a configuration file specifically set up for this demonstration. It is a "toy" configuration that runs the training for only a few epochs to ensure it completes quickly in this notebook environment.

📊 Analyze the Baseline Results¶

Now that the training is complete, let's examine the results. The training script saved all the key metrics into a CSV log file. We'll use the Pandas library to load this file into a DataFrame, which gives us a clean, table-like view of the experiment's outcome.

What to Look For¶

Pay close attention to the train_cls_loss, test_accuracy, and test_loss columns. We expect to see the following pattern, which is a classic sign of shortcut learning:

• Low train_cls_loss: The training loss should decrease to a very low value. This indicates the model has successfully "learned" the training data by memorizing the easy color-based shortcut.
• Low test_accuracy and High test_loss: The accuracy on the test set will be very low, while the corresponding test loss will be high. This proves the model didn't learn the actual shapes of the digits and fails when the color shortcut is removed.

🧪 Applying a Bias Mitigation Method¶

The baseline model clearly failed, learning the color "shortcut" instead of the digits' actual shapes. Now, let's see if we can improve the performance by using a specific bias mitigation technique.

We will modify our configuration file to switch from the standard training (erm) to one of the supported methods (eg., flac or badd).

Instructions¶

1. Open the configuration file located at configs/toy.yaml.
2. You will need to make two changes:
   • Under EXPERIMENT, change the NAME from "erm" to "<selected_method>". This is important so that our new results are saved to a different directory and don't overwrite our baseline run.
   • Under MITIGATOR, change the TYPE from "erm" to "<selected_method>". This is the key step that activates the bias mitigation method.

Modified toy.yaml¶

For example, if you want to use FLAC, the toy.yaml file should look like this:

EXPERIMENT:
  NAME: "flac"  # <-- CHANGE THIS
  TAG: "toy"
  PROJECT: "biased_mnist_baselines"
DATASET:
  TYPE: "biased_mnist"
  BIASES: ["color"]
MITIGATOR:
  TYPE: "flac" # <-- AND CHANGE THIS
SOLVER:
  BATCH_SIZE: 128
# ... (rest of the file remains the same)

🚀 Re-running Training with the Selected Mitigator¶

Now that you've updated configs/toy.yaml to use the desired method, it's time to run the experiment again.

We'll use the exact same command as before. However, because the configuration file has been changed, the training script will now apply the selected bias mitigation approach. The goal is to see if this method can overcome the color bias and achieve a much higher test_accuracy than our baseline model.

Let's kick off the training and see if it works.

🏁 Final Analysis: Analyzing the New Results¶

Now for the final step, let's analyze the performance of the selected mitigation method to see if it successfully overcame the bias.

In the cell below, make sure that you replace the name of the method (i.e., flac) with the bias mitigation method you selected in the previous steps.

Review the results in the table, paying close attention to the final epoch's values. Think back to the baseline vanilla model's performance.

• Is the final test_accuracy significantly higher than before?
• Is the final test_loss significantly lower?

A clear "yes" to these questions is the key indicator that the selected method worked, successfully ignoring the color shortcut and learning the true features of the digits.

🔧 Bonus: Implement a Missing Mitigator Function¶

In this task, you'll reimplement the _train_iter() function for the flac mitigator.

1. Navigate to the flac_aida mitigator and implement the _train_iter() function. This function is responsible for executing a single training iteration on a batch.
2. After completing the implementation, update the toy.yaml configuration file to use the new mitigator.
3. Finally, run the experiment using the updated setup.