README.Rmd

---
title: "RateParser"
output: github_document
---

[![Build Status](https://travis-ci.org/California-Data-Collaborative/RateParser.svg?branch=master)](https://travis-ci.org/California-Data-Collaborative/RateParser) [![Coverage Status](https://img.shields.io/codecov/c/github/California-Data-Collaborative/RateParser.svg)](https://codecov.io/gh/California-Data-Collaborative/RateParser)


RateParser is an R package to parse files written using the [Open Water Rate Specification (OWRS)](https://github.com/California-Data-Collaborative/Open-Water-Rate-Specification) and use them to calculate water bills.

##Installation

To install the latest version from Github, sinply run the following from an R console:

```r
if (!require("devtools"))
  install.packages("devtools")
devtools::install_github("California-Data-Collaborative/RateParser")
```

## Getting Started

This section demonstrates how to apply RateParser to calculate water bills given a dataframe of publicly available [billing data](https://data.smgov.net/Public-Services/Water-Usage/4nnq-5vzx) from the City of Santa Monica.

First we load the RateParser package and read in the example OWRS file. The example OWRS file for the city of Santa Monica can be downloaded directly from [this link](https://raw.githubusercontent.com/California-Data-Collaborative/RateParser/master/examples/smc-2016-03-01.owrs) (right-click, Save as...) or can be found in the `examples` directory if this repository is downloaded or cloned.
```{r}
library(RateParser)

# read in example OWRS file
owrs_file <- read_owrs_file("examples/smc-2016-03-01.owrs")

# view residential single-family rates
owrs_file$rate_structure$RESIDENTIAL_SINGLE
```

Not all of the data columns needed to calculate their water bills are included in the public data, so instead we need to assign some default values.
```{r}
santamonica$meter_size <- '5/8"' 
santamonica$water_type <- 'POTABLE'
```

Our dataframe currently contains an "OTHER" class (a byproduct of the author's inability to properly classify some of the rate codes). Our sample OWRS file, on the other hand, contains no information for "OTHER" customer class, so we need to filter those out.

Finally we can pass our dataframe and our OWRS file as inputs into the `calculate_bill` function.
```{r}
library(dplyr, warn.conflicts = FALSE)

# filter out "OTHER" class
filtered <- dplyr::tbl_df(santamonica) %>% dplyr::filter(cust_class != "OTHER")

# calculate water bills
calced <- calculate_bill(filtered, owrs_file)
```

The results in a number of additional columns being appended to the original dataframe. Note that the first 9 columns are the original input columns, while the rest have been added by `calculate_bills`.

In particular, 

* `bill` is the water bill (in dollars) for that customer in that month
* `Xn` is the amount of water use (in billing units) in the *nth* rate tier
* `XRn` is the amount of revenue (in dollars) generated by the *nth* rate tier

```{r}
glimpse(calced)
```