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

---

Recourse | Installation | Development | Reference

---

Recourse?

Recourse is the ability to flip the prediction of a ML model by changing actionable input variables (e.g., income instead of age).

When should models provide recourse?

Recourse is an important element of human-facing applications of ML. In applications such as lending or allocation of public services, models should allow individuals with the ability to change their prediction. In other applications, models should let individuals flip their predictions based on specific types of changes. A recidivism prediction model that uses age and prior_arrests, for example, should a person that is predicted to recidivate with the ability to alter this prediction via age.

Package Highlights

The tools in this library allow you check recourse without interfering in the the model development process.

• What can a person do to obtain a favorable outcome from a model?
• How many people will be able to alter their predictions?
• How hard is it for people to change their prediction?

Specifically:

• Specify a custom set of feasible actions for each input variables to a ML model.
• Generate a list of actionable changes to flip the prediction of a linear classifier.
• Evaluate the feasibility of recourse of a linear classifier on a population of interest.
• Measure the difficulty of recourse for a linear classifier on a population of interest.

---

Installation

Please install from source by running

$ git clone git@github.com:ustunb/actionable-recourse.git
$ python setup.py

Requirements

• Python 3
• MIP solver: either CPLEX or Pyomo + CBC

CPLEX

CPLEX is fast optimization solver with a Python API. It is commercial software, but worth downloading since it is free to students and faculty 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, please check the CPLEX user manual or the CPLEX forums.

CBC + Pyomo

If you are unable to obtain CPLEX, you can also work with an open-source solver. This requires the following steps (which you can do before you)

1. Download and install CBC from Bintray
2. Download and install pyomo and pyomo-extras (instructions)

---

Development

We're actively working to improve this package and make it more useful. If you come across bugs, have comments or suggestions, or want to help out, let us know!

Roadmap

• pip installation
• Contributing.md
• support for categorical variables in ActionSet
• support for rule-based models such as decision lists and rule lists
• scikit-learn compatability
• integration into AI360 Fairness toolkit

---

Reference

For more about recourse and our 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},
}