MendesSP / actionable-recourse

evaluate recourse in linear classification models

actionable-recourse is a python library to evaluate recourse in linear classification models.

Overview

Recourse is the ability to change the decision of a predictive model through actionable input variables (e.g., income vs. age or marital status).

This package includes tools to:

1. List changes that a person can make to obtain a desired outcome from a given model
2. Measure the feasibility and difficulty of recourse over a population of interest

Installation

Please install from source as the package is still in development.

$ git clone [e-mail]:ustunb/actionable-recourse.git
$ python setup.py

Requirements:

• Python 3.5+
• CPLEX 12.6+
• CBC

CBC + Pyomo

• Download COIN-OR and CBC from: https://www.coin-or.org/
• Install Pyomo using pip or conda and then run the Pyomo installer in the command line: pyomo install-extras
• If you're on Windows, conda install -c conda-forge pyomo.extras is a safer way to go

CPLEX

CPLEX is cross-platform commercial optimization tool with a Python API. It is free for students and faculty members at accredited institutions. To get CPLEX:

1. Register for IBM OnTheHub
2. Download the IBM ILOG CPLEX Optimization Studio from the software catalog
3. Install the CPLEX Optimization Studio.
4. Setup the CPLEX Python API as described here.

If you have problems installing CPLEX, check the CPLEX user manual or the CPLEX forums.

Development Roadmap

• Support for categorical variables in ActionSet
• Support for Boolean models such as decision lists and rule lists
• scikit-learn compatability
• Integration into AI360 Fairness Toolkit

Reference

For more about recourse or how to use these tools, check out our paper:

Actionable Recourse in Linear Classification

inproceedings{ustun2019recourse,
     title = {Actionable Recourse in Linear Classification},
     author = {Ustun, Berk and Spangher, Alexander and Liu, Yang},
     booktitle = {Proceedings of the Conference on Fairness, Accountability, and Transparency},
     series = {FAT* '19},
     year = {2019},
     isbn = {978-1-4503-6125-5},
     location = {Atlanta, GA, USA},
     pages = {10--19},
     numpages = {10},
     url = {http://doi.acm.org/10.1145/3287560.3287566},
     doi = {10.1145/3287560.3287566},
     publisher = {ACM},
     keywords = {accountability, audit, classification, credit scoring, integer programming, recourse},
}