Wiggum Documentation

Contents:

  • this documentation site is under active development*

Wiggum

Simpson’s Paradox Inspired Fairness Forensics

Getting Started

Simpson’s Paradox Inspired Fairness Forensics

Prior version published in:

To use the Wiggum, download (or clone) from the GitHub Repo and:

cd wiggum/
pip install .

See the [documentation site](https://fairnessforensics.github.io/wiggum/) for examples and to reproduce the paper results.

To use the package in python, after installed:

import wiggum as wg

Installing makes the flask app for interactive visualization in browser available as a command line tool. To run the app:

wiggum-app

When developing it can be easier to use

python3 run.py

This will start the server on http://127.0.0.1:5000/ from the current working directory.

Development

We also provide a docker file.

FIXME

To run in the same environment as developed or to compile docs, sphinx and some extensions are required, all are included in requirements.txt and can be

installed with:

pip install -r requirements.txt

To generate JavaScript documentation, install JSDoc using npm

npm install -g jsdoc

then

cd docs/
make html

To reinstall after changes

pip install --upgrade .

When updating the package and working in a notebook, the notebook’s kernel will need to be restarted to get the updates, if they’re done outside of the notebook.

(only needed in development or after upgrade)

Documentation Overview

This page is under active development.

How to Fairness Forensics

How to conduct a fairness forensics investigation with Wiggum:

Example Investigations and Case Studies

Example code excerpts for small tasks * TBD

Case studies of fairness forensics investigations: * Iris data * SOPP data * Propbulica COMPAS Data

Reproducible Science

to reproduce our paper experimental results

Extending and Contributing to Wiggum

We provide the following detailed documentation if you want to contribute to Wiggum or extend it for your own use.

  • Basic dev setup:

  • How to add new trends

  • How to extend the app

  • Contributors Guide:

Indices and tables