{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "## Welcome to Aequitas" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The Aequitas toolkit is a flexible bias-audit utility for algorithmic decision-making models, accessible via Python API, command line interface (CLI), and through our [web application](http://aequitas.dssg.io/). \n", "\n", "Use Aequitas to evaluate model performance across several bias and fairness metrics, and utilize the [most relevant metrics](https://dsapp.uchicago.edu/wp-content/uploads/2018/05/metrictree-1200x750.png) to your process in model selection.\n", "\n", "Aequitas will help you:\n", "\n", "- Understand where biases exist in your model(s)\n", "- Compare the level of bias between groups in your sample population (bias disparity)\n", "- Visualize absolute bias metrics and their related disparities for rapid comprehension and decision-making\n", "\n", "Our goal is to support informed and equitable action for both machine learnining practitioners and the decision-makers who rely on them.\n", "\n", "Aequitas is compatible with: **Python 3.6+**" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "\n", "# Getting started\n", "You can audit your risk assessment system for two types of biases:\n", "\n", " - Biased actions or interventions that are not allocated in a way that’s representative of the population.\n", " - Biased outcomes through actions or interventions that are a result of your system being wrong about certain groups of people.\n", "\n", "For both audits, you need the following data:\n", "\n", " - Data about the specific attributes (race, gender, age, income, etc.) you want to audit for the the overall population considered for interventions\n", "\n", " - The set of individuals in the above population that your risk assessment system recommended/ selected for intervention or action. _It’s important t this set come from the assessments made after the system has been built, and not from the data the machine learning system was “trained” on if you're using the audit as a factor in model selection._\n", "\n", "If you want to audit for biases due to model or system errors, you also need to include actual outcomes (label values) for all individuals in the overall population. \n", "\n", "Input data has slightly different requirements depending on whether you are using Aequitas via the webapp, CLI or Python package. In general, input data is a single table with the following columns:\n", "\n", "- `score`\n", "- `label_value` (for error-based metrics only)\n", "- at least one attribute e.g. `race`, `sex` and `age_cat` (attribute categories defined by user)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Bias measures tailored to your problem\n", "\n", "### Input machine learning predictions\n", "\n", "After [installing on your computer](./installation.html)\n", "\n", "Run `aequitas-report` on [COMPAS data](https://github.com/dssg/aequitas/tree/master/examples): \n", "\n", "`compas_for_aequitas.csv` excerpt:\n", "\n", "| score | label_value| race | sex | age_cat |\n", "| --------- |------------| -----| --- | ------- |\n", "| 0 | 1 | African-American | Male | 25 - 45 |\n", "| 1 | 1 | Native American | Female | Less than 25 |\n", "\n", "```\n", "aequitas-report --input compas_for_aequitas.csv\n", "```\n", "\n", "**Note:** Disparites are always defined in relation to a reference group. By default, Aequitas uses the majority group within each attribute as the reference group. [Defining a reference group](./config.html)\n", "\n", "### The Bias Report output\n", "\n", "The Bias Report produces a pdf that returns descriptive interpretation of the results along with three sets of tables. \n", "\n", "* Fairness Measures Results\n", "* Bias Metrics Results\n", "* Group Metrics Results\n", "\n", "Additionally, a csv is produced that contains the relevant data. More information about output [here](./output_data.html).\n", "\n", "### Command Line output\n", "\n", "In the command line you will see The Bias Report, which returns counts for each attribute by group and then computes various fairness metrics. This is the same information that is captured in the csv output. \n", "\n", "``` \n", " ___ _ __ \n", " / | ___ ____ ___ __(_) /_____ ______\n", " / /| |/ _ \\/ __ `/ / / / / __/ __ `/ ___/\n", " / ___ / __/ /_/ / /_/ / / /_/ /_/ (__ ) \n", " /_/ |_\\___/\\__, /\\__,_/_/\\__/\\__,_/____/ \n", " /_/ \n", "____________________________________________________________________________\n", "\n", " Bias and Fairness Audit Tool\n", "____________________________________________________________________________\n", "\n", "Welcome to Aequitas-Audit\n", "Fairness measures requested: Statistical Parity,Impact Parity,FDR Parity,FPR Parity,FNR Parity,FOR Parity\n", "model_id, score_thresholds 1 {'rank_abs': [3317]}\n", "COUNTS::: race\n", "African-American 3696\n", "Asian 32\n", "Caucasian 2454\n", "Hispanic 637\n", "Native American 18\n", "Other 377\n", "dtype: int64\n", "COUNTS::: sex\n", "Female 1395\n", "Male 5819\n", "dtype: int64\n", "COUNTS::: age_cat\n", "25 - 45 4109\n", "Greater than 45 1576\n", "Less than 25 1529\n", "dtype: int64\n", "audit: df shape from the crosstabs: (11, 26)\n", "get_disparity_major_group()\n", "number of rows after bias majority ref group: 11\n", "Any NaN?: False\n", "bias_df shape: (11, 38)\n", "Fairness Threshold: 0.8\n", "Fairness Measures: ['Statistical Parity', 'Impact Parity', 'FDR Parity', 'FPR Parity', 'FNR Parity', 'FOR Parity']\n", "\n", "... \n", "```" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.5" } }, "nbformat": 4, "nbformat_minor": 2 }