Learning Optimal Predictive Checklists

A Python package to learn simple predictive checklists from data subject to customizable constraints. For more details please see our NeurIPS 2021 paper.

Contents

• Installation
  • 1. Installing the Package
  • 2. Installing a MIP Solver
    • 2.1. CPLEX (Recommended)
    • 2.2. Python-MIP (Not Recommended)
• Usage
• Reproducing the Paper
• Citation

Installation

1. Installing the Package

Our package is available on PyPI. Simply run the following with Python >= 3.7:

pip install predictive-checklists

2. Installing a MIP Solver

2.1. CPLEX (Recommended)

CPLEX is a proprietary optimization software package from IBM. All of the experiments in our paper were ran with CPLEX. To install CPLEX, download and install CPLEX Optimization Studio (we use version 20.1.0). If you are affiliated with an academic institution, you can obtain a free academic version.

After installing CPLEX Optimization Studio, install the cplex Python package by following the instructions here. Note that we create our MIP in this project using cplex, not docplex.

2.2. Python-MIP (Not Recommended)

If you are not able to obtain CPLEX, we provide the same formulation using Python-MIP, which allows for the use of CBC, a free and open source MIP solver. You will not have to install any additional packages if you choose to use Python-MIP with CBC.

However, note that all of the experiments in our paper were conducted using CPLEX. In limited tests, Python-MIP with CBC seems to perform markedly worse than CPLEX for the same solution time, and so we provide no guarantees on the performance of Python-MIP.

Usage

We provide the following examples as Jupyter Notebooks:

1. Getting Started
2. Creating Fair Checklists

Reproducing the Paper

See reproducing_paper.md.

Citation

If you use this code or package in your research, please cite the following publication:

@article{zhang2021learning,
  title={Learning Optimal Predictive Checklists},
  author={Zhang, Haoran and Morris, Quaid and Ustun, Berk and Ghassemi, Marzyeh},
  journal={Advances in Neural Information Processing Systems},
  volume={34},
  year={2021}
}