ChirpPy 0.1.3
A python library the implements aspects of the CHIRPS algorithm.
License: Apache 2.0

# ChirpPy

## Description

This code produces explanations for the classifications produced by random forests. The algorithm is largely an implementation of [CHIRPS](https://doi.org/10.1007/s10462-020-09833-6), though some alterations have been made. 

## Motivation

## Installation
To install dependencies:

- Python dependencies
  ```
  pip install -r requirements.txt
  ```

  or


  ```
  pip install .
  ```

The modules themselves can be also be installed as a python package:

  ```
  pip install ChirpPy
  ```


## Quick Start

To generate an explanation for a particular model and input, run:

```
python ChirpPy/genExp.py -m <model> -test <input-data> -td <training-dataset> -tl <training-labels>
```

These parameters are:
1. model - filepath to your model (in joblib or pickled format)
2. input data - filepath to input data (in json format)
3. training dataset - filepath to training dataset for the model (in json format)
4. training labels - filepath to labels for training dataset for the model (in json format)

Additional optional parameters are:

5. -s/sample size - size of samples to take of the training dataset for use in the algorithm (default is 100,000)

6. -f/feature name - List of feature names for output (in json format)

7. -t/target name - List of target values/classfication (in json format)

7. -o/output - the filename for the results(in quotes)


### Example

Using the provided Iris dataset, the following line generates a sample explanantion with all parameters specified:

```
python3 ChirpPy/htmlGeneration/genExp.py -m "ChirpPy/data/iris/iris5Model.joblib" -td "ChirpPy/data/iris/iris_train_features.json" -tl "ChirpPy/data/iris/iris_train_labels.json" -test "ChirpPy/data/iris/iris_single.json" -testLabel "ChirpPy/data/iris/iris_test_labels.json" -f "ChirpPy/data/iris/iris_feature_list.json" -t "ChirpPy/data/iris/iris_targets.json" -o "result.html"
```

## In depth

Generating an exlanation consists of six steps: four to create the explanation, one to generate statistics to help evaluate it, and one to produce the output file.

1. Extracting paths (in ```chirp_extract_path.py```)
2. Identifying common rule subsets (in ```chirp_fp.py```)
3. Ranking subsets (in ```chirp_ranking.py```)
4. Merging and pruning rules (in ```chirps_merge.py```)
5. Generating metrics (in ```contrast_and_confidence.py```)
6. Output production (in ```write_HTML.py``` with helper functions in ```visualizations.py```)

### 1. Extracting paths
```chirp_extract_path.py``` contains the function ```makePath(tree, single_sample)``` which takes in a tree from the forest and our sample to classify and explain. Iterating over trees in the forest will collect all of the paths involved in classifying the instance.

### 2. Identifying common rule subsets
```chirp_fp.py.py``` contains the function ```frequent_patterns(paths, min_support, max_subset_size)``` which takes the paths from step 1, along with a value for minimum support (we recommend 0.1) and a max_subset_size (we recommend 5), and returns frequently occuring rule subsets and their frequencies.

### 3. Ranking subsets
```chirp_ranking.py``` contains the function ```getFpRanking(fpList, supportList)``` which takes the list of frequently occuring rule subsets and the list of their frequencies, scores each rule subset, and then returns them in sorted order with their scores. 

### 4. Merging and pruning rules
```chirps_merge.py``` contains the function ```rule_merge_bootstrap(g,X,x,snippets)``` which takes in the forest, training data, sample data instance, and the sorted rule subsets, and returns a list of rules: our explanation. It also contains  ```prune_stage_two_bootstrap_alt(g,explanation, X, x)``` which takes in the forest, previous explanation, training data, and sample data instance, and returns a pruned explanation (one with superfluous rules removed).

### 5. Generating metrics
```contrast_and_confidence.py``` contains the functions ```get_confidence(single_sample, model, explanation, training_data)``` which takes in the input instance, the model, the explanation, and the training data and returns our confidence scores, as well as the function ```get_contrast(single_sample, model, explanation, training_data)``` which has the same inputs but returns the contrast values for each rule.

### 6. Output production
```write_HTML.py``` contains the function ```generateHTML(modelType, predictorText, rules, satis, plotPaths, outFile)``` that takes in the model type (as string), characteristics about the classification, the explanation rules, coverage and confidence, different charts, and the output filename and generates the HTML document. See the function call in ```genExp.py``` for a better understanding of ```generateHTML()``` and its arguments.

## Tests

Different tests are found in the testing folder. ```unitTests.py``` contains unit tests of the early steps of the algorithm, and ```testing_merge.py``` contains the framework to verify reasonable output over a dataset of test data.

## Contributors

Alfredo Gomez, Juan Diego Herrera, Lindsay Popowski, Ramya Ramalingam

## License

This program is free software licensed under the terms Apache 2.0 license. Distribution, modification, and usage must be in accord to the licensing terms.