Skip to content

Introducing the Alien Zoo approach: An experimental framework for evaluating counterfactual explanations for ML

License

Notifications You must be signed in to change notification settings

HammerLabML/IntroAlienZoo

 
 

Repository files navigation

README

This repository provides code, data, and analysis scripts for the Alien Zoo framework as used in the study: "Let's Go to the Alien Zoo: Introducing an Experimental Framework to Study Usability of Counterfactual Explanations for Machine Learning"

Detailed motivation and rationale are explained in the paper. In short, we provide this framework as a utility to run user studies to perform human level evaluations of counterfactual explanations (CFEs) for machine learning (ML).

Rough overview of implementation logic

Implementation of the experimental framework follows a clear separation into python-based BackEnd, and a javascript based FronEnd.

I want to replicate the experiments as described in the paper!

Very well! Let's go:

Requirements and prerequisites

There is a list of steps that first need to be done on the BackEnd side before we can go to the Alien Zoo.

  1. Whatever you do, use Python3.
  2. cd BackEnd
  3. Install all requirements as listed in REQUIREMENTS.txt.
  4. Install CEML (Note: required Python 3.6 or higher!): pip install ceml
  5. Setup an MySQL database (databse name, user name and password of your choice). Then, make sure the credentials and database in dbmgr.py (lines 6-10) fit your set up.
  6. Run python crypt.py (generates key pair; relevant for encrypting userId information).
  7. Decide which experiment from our study you want to recreate. The default is Experiment 1, but you can change that via the variable expNo in line 17 in file BackEnd/models.py.

Start up the server

Finally, we can start the server: python server.py The server is listening on port 8888, so pull up a browser and go to the Alien Zoo under localhost:8888/.

Wrapping up, export data, clear database

When you're done, stop the running server with Ctrl+C.

Run BackEnd/db_export.py to export data from the database. This command generates 6 files from the content of the database. For details on these files and coding of respective data, see here.

Finally, when you are done with the code, run python BackEnd/reset_database.py user_name user_pw to reset the database again.

FAQ

How was synthetic data used for model training generated?

We included the code on how we generated the data as R Markdown documents under BackEnd/modelData:

How were models trained?

We trained decision tree regression model for each experiment. Lines 44-80 in BackEnd/models.py show the code used for model training. Note that pre-trained models are already available, both model_IAZ_EXP1.joblib and model_IAZ_EXP1.joblib.

I want a different port!

Fair enough: The port can be changed in line 15 in file BackEnd/server.py.

It takes ages until the buttons appear. How can I change that?

The delays are chosen as used in the reported Experiments. If you want to change them, check lines 84-86 in file FrontEnd/gameUI.js. Via this file, you can also control other details of the procedure (trials per block, number of blocks, number and placement of attention trials, etc.) Note that long delays are an effective measure to ensure that participants will really engage with the materials (instead of quickly brushing over everything).

I want to re-create the statistical analysis

We provide R Markdown documents of the entire statistical evaluation, together with the original user data acquired in both experiments:

License

This work is licensed under a Creative Commons Attribution 4.0 International License.

CC BY 4.0

About

Introducing the Alien Zoo approach: An experimental framework for evaluating counterfactual explanations for ML

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 66.8%
  • Python 21.6%
  • R 7.2%
  • TeX 4.1%
  • HTML 0.3%