Heuristic Moral Machine Project
================================

**Heuristic-Based Weak Learning for Automated Decision-Making**

> Presented at [PAML @ ICML 2020](https://participatoryml.github.io/).

Training ML decision-making systems with heuristics to lower the barrier to stakeholder participation in algorithm design/governance.

Author: Ryan Steed

View the data & code on [Github](https://github.com/ryansteed/heuristic-moral-machine).

## Description

This repo contains a software package for training and evaluating a decision-making algorithm for two use cases with pairwise moral preference data: the autonomous vehicle trolley problem and the kidney exchange.

`hmm` is a Python package for automatically labeling moral scenarios in these two domains. `hmm/labeling`
contains custom heuristic labeling functions, along with unit tests. `hmm/labeling/models.py` contains a wrapper for the 
[Snorkel](https://www.snorkel.org/) generative label model. `hmm/classification.py` contains a discriminative model for
weakly supervised training on the generated labels.

`examples` contains example Jupyter scripts demonstrating data parsing, labeling, classification, and evaluation for both use cases.

`figures` contains scripts and data for generating the figures presented in the accompanying thesis (public link coming soon).

For the full API documentation, visit [rbsteed.com/heuristic-moral-machine](https://rbsteed.com/heuristic-moral-machine).

## Setup
After installing `git` and `conda`:
```bash
git clone https://github.com/ryansteed/heuristic-moral-machine  # clone this repo
cd heuristic-moral-machine
conda env update environment.yml  # create conda env
source activate hmm  # activate env
```

## Data

Data files should be stored in the `data` directory.

### Autonomous Vehicle Trolley Problem
Using [published data](https://osf.io/3hvt2/?view_only=4bb49492edee4a8eb1758552a362a2cf) from 
[Moral Machine](http://moralmachine.mit.edu/) experiment.

For easy querying, convert data into a SQLite `.db` locally:
```
sqlite> .mode csv
sqlite> .import path/to/db path/to/SharedResponses.csv sharedresponses
```

### Kidney Exchange

Using private data from Freedman et al. Please contact the authors for details.

## Making the Docs

This documentation is autogenerated from docstrings in the codebase. Follow these instructions to refresh the documentation.

From the root project folder, run:
```bash
cd docs
# Build documentation hierarchy (.rst files) in source folder from app package
sphinx-apidoc --implicit-namespaces --separate -o source ../hmm
# Make the html folder
make clean
make html
```

HTML documentation can be accessed from the project root `html` symlink.

---
© Ryan Steed 2020