Skip to content

Commit 16a9608

Browse files
christophertullchristophertull
committed
updated README as rmarkdown doc with code snippets
1 parent 046162a commit 16a9608

2 files changed

Lines changed: 165 additions & 2 deletions

File tree

‎README.Rmd‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: "RateParser"
3+
output: github_document
4+
---
5+
6+
[![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)
7+
8+
9+
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.
10+
11+
##Installation
12+
13+
To install the latest version from Github, sinply run the following from an R console:
14+
15+
```r
16+
if (!require("devtools"))
17+
install.packages("devtools")
18+
devtools::install_github("California-Data-Collaborative/RateParser")
19+
```
20+
21+
## Getting Started
22+
23+
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.
24+
25+
First we load the RateParser package and read in the example OWRS file.
26+
```{r}
27+
library(RateParser)
28+
29+
# read in example OWRS file
30+
owrs_file <- read_owrs_file("examples/smc-2016-03-01.owrs")
31+
32+
# view residential single-family rates
33+
owrs_file$rate_structure$RESIDENTIAL_SINGLE
34+
```
35+
36+
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.
37+
```{r}
38+
santamonica$meter_size <- '5/8"'
39+
santamonica$water_type <- 'POTABLE'
40+
```
41+
42+
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.
43+
44+
Finally we can pass our dataframe and our OWRS file as inputs into the `calculate_bill` function.
45+
```{r}
46+
library(dplyr, warn.conflicts = FALSE)
47+
48+
# filter out "OTHER" class
49+
filtered <- dplyr::tbl_df(santamonica) %>% dplyr::filter(cust_class != "OTHER")
50+
51+
# calculate water bills
52+
calced <- calculate_bill(filtered, owrs_file)
53+
```
54+
55+
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`.
56+
57+
In particular,
58+
59+
* `bill` is the water bill (in dollars) for that customer in that month
60+
* `Xn` is the amount of water use (in billing units) in the *nth* rate tier
61+
* `XRn` is the amount of revenue (in dollars) generated by the *nth* rate tier
62+
63+
```{r}
64+
glimpse(calced)
65+
```
66+

‎README.md‎

Lines changed: 99 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,103 @@
1-
# RateParser
1+
RateParser
2+
================
23

34
[![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)
45

6+
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.
57

6-
Interpret [OWRS files](https://github.com/California-Data-Collaborative/Open-Water-Rate-Specification) and calculate water bills.
8+
Installation
9+
------------
10+
11+
To install the latest version from Github, sinply run the following from an R console:
12+
13+
``` r
14+
if (!require("devtools"))
15+
install.packages("devtools")
16+
devtools::install_github("California-Data-Collaborative/RateParser")
17+
```
18+
19+
Getting Started
20+
---------------
21+
22+
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.
23+
24+
First we load the RateParser package and read in the example OWRS file.
25+
26+
``` r
27+
library(RateParser)
28+
29+
# read in example OWRS file
30+
owrs_file <- read_owrs_file("examples/smc-2016-03-01.owrs")
31+
32+
# view residential single-family rates
33+
owrs_file$rate_structure$RESIDENTIAL_SINGLE
34+
```
35+
36+
## $tier_starts
37+
## [1] 0 15 41 149
38+
##
39+
## $tier_prices
40+
## [1] 2.87 4.29 6.44 10.07
41+
##
42+
## $commodity_charge
43+
## [1] "Tiered"
44+
##
45+
## $bill
46+
## [1] "commodity_charge"
47+
48+
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.
49+
50+
``` r
51+
santamonica$meter_size <- '5/8"'
52+
santamonica$water_type <- 'POTABLE'
53+
```
54+
55+
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.
56+
57+
Finally we can pass our dataframe and our OWRS file as inputs into the `calculate_bill` function.
58+
59+
``` r
60+
library(dplyr, warn.conflicts = FALSE)
61+
62+
# filter out "OTHER" class
63+
filtered <- dplyr::tbl_df(santamonica) %>% dplyr::filter(cust_class != "OTHER")
64+
65+
# calculate water bills
66+
calced <- calculate_bill(filtered, owrs_file)
67+
```
68+
69+
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`.
70+
71+
In particular,
72+
73+
- `bill` is the water bill (in dollars) for that customer in that month
74+
- `Xn` is the amount of water use (in billing units) in the *nth* rate tier
75+
- `XRn` is the amount of revenue (in dollars) generated by the *nth* rate tier
76+
77+
``` r
78+
glimpse(calced)
79+
```
80+
81+
## Observations: 217,256
82+
## Variables: 21
83+
## $ cust_id (int) 25886, 74585, 57854, 58210, 25002, 68393, 257...
84+
## $ usage_ccf (dbl) 388, 9, 73, 22, 11, 84, 670, 170, 0, 102, 107...
85+
## $ usage_month (int) 3, 1, 1, 1, 1, 3, 3, 3, 3, 3, 3, 3, 3, 1, 4, ...
86+
## $ usage_year (int) 2014, 2015, 2015, 2015, 2015, 2015, 2015, 201...
87+
## $ cust_class (chr) "COMMERCIAL", "COMMERCIAL", "COMMERCIAL", "CO...
88+
## $ usage_date (chr) "2014-03-01", "2015-01-01", "2015-01-01", "20...
89+
## $ rate_code (chr) "WANR5", "WANR2", "WANR3", "WANR1", "WANR2", ...
90+
## $ meter_size (chr) "5/8\"", "5/8\"", "5/8\"", "5/8\"", "5/8\"", ...
91+
## $ water_type (chr) "POTABLE", "POTABLE", "POTABLE", "POTABLE", "...
92+
## $ tier_starts (chr) "0\n211", "0\n211", "0\n211", "0\n211", "0\n2...
93+
## $ tier_prices (chr) "4.07\n10.03", "4.07\n10.03", "4.07\n10.03", ...
94+
## $ X1 (dbl) 210, 9, 73, 22, 11, 84, 210, 170, 0, 102, 210...
95+
## $ X2 (dbl) 178, 0, 0, 0, 0, 0, 460, 0, 0, 0, 865, 0, 0, ...
96+
## $ XR1 (dbl) 854.70, 36.63, 297.11, 89.54, 44.77, 341.88, ...
97+
## $ XR2 (dbl) 1785.34, 0.00, 0.00, 0.00, 0.00, 0.00, 4613.8...
98+
## $ commodity_charge (dbl) 2640.04, 36.63, 297.11, 89.54, 44.77, 341.88,...
99+
## $ bill (dbl) 2640.04, 36.63, 297.11, 89.54, 44.77, 341.88,...
100+
## $ X3 (dbl) NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N...
101+
## $ X4 (dbl) NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N...
102+
## $ XR3 (dbl) NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N...
103+
## $ XR4 (dbl) NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N...

0 commit comments

Comments
 (0)