# Burn-Rules
Calibrated risk predictions for prescribed burn simulations

### Directories

```
├── bp3d/                     <- bp3d API 
├     
├── data/                     <- folder for data
├    ├── piedmont/            <- Piedmont data (JSON & labels)
├    ├── processed/           <- folder for data after preprocessing & feature engineering
├    ├── raw/                 <- folder from data extracted from the JSON data
├    ├── studhorse/           <- Studhorse data (JSON & labels)    
├       
├── Model_Reports/            <- All model run log files as saved by papermill
├                   
├── Reporting/                <- source R and python code to generate model reports
├    ├── make_report.R        <- R script to render an R Markdown template from the command line
├    ├── reporting_utils.R    <- R reporting helper functions
├    ├── utils.py             <- python functions to call R scripts and generate R Markdown reports
├       
├── reports/                  <- All saved model reports 
├           
├── saved_models/             <- All the trained models and fold results
├       
├── src/                      <- Python source code
├    ├── AccessEnsemble/      <- QUIC-Fire Ensemble Class
├    ├── FeatureEngineering/  <- Useful feature engineering functions
├    ├── cross_validation.py  <- Code for cross validation techniques
├    ├── paths.py             <- Setting paths
├    ├── utils.py             <- helper functions
├ 
├── templates/               <- Rmarkdown template for the model report

0_MODELING_PIPELINE.ipynb    <- Papermill orchestration
1_accessing_data.ipynb       <- API call to grab raw data and save to `data/raw` folder
2_feature_engineering.ipynb  <- Preprocessing / feature engineering notebook
3_process_datasets.ipynb     <- Converts data into a BinaryClassificationDataset with cv indices
4_train_model.ipynb          <- Trains the logistic regression to predict calibrated risk scores
5_create_model_report.ipynb  <- Generates a model report for the run (AUC, CAL, LOSS, ROC Curve, Reliability diagram, and model coefs)

build_docker.sh              <- shell script to build docker image to use all the code in this repository
dockerfile                   <- dockerfile with docker build requirements
extract_docker.sh            <- shell script to extract models from docker container to local machine
README.md                    <- The document you are reading now
Risk-Predictions.Rmd         <- A proof-of-concept shiny application
run_docker.sh                <- shell script to spin up a docker container from the image build with the build_docker.sh
```

### How to use this repository
1. Setup Docker
   1. Install [docker desktop](https://www.docker.com/products/docker-desktop/) 
   2. Pull this repository
   3. If using Windows see [Windows Instructions](#windows-instructions)
   5. Execute in your command line `./build_docker.sh`
3. Spinning up the docker container
   1. Execute in your command line `./run_docker.sh`
   2. Navigate to the jupyter lab link shown in your command line (starting with `https://127.0.0.1`)
4. Run a modeling experiment by opening `0_MODELING_PIPELINE.ipynb` and running it
5. Once you are happy with the experiments that have been run in the docker container, navigate back to the host machine and execute `extract_docker.sh` in the command line

### Windows Instructions
1. Windows Subsystem Linux is required for Windows platform users.
	1. See [here](https://docs.microsoft.com/en-us/windows/wsl/install) for additional instructions
	2. For most users:
		1. Open PowerShell or CMD and run command: `wsl --install`
		2. By default this will install Ubuntu. Our program was tested on Ubuntu. Other linux distributions may work but might lead to unexpected behavior
	3. Once WSL has been installed:
        1. Open PowerShell or CMD
        2. Activate WSL by running command `wsl`
        3. Follow instructions above as usual.