Skip to content

Commit 8344884

Browse files
christophertullchristophertull
authored
Merge pull request #6 from California-Data-Collaborative/documentationUpdates
Documentation updates
2 parents 79729dd + 16a9608 commit 8344884

5 files changed

Lines changed: 378 additions & 2 deletions

File tree

‎.Rbuildignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
^.*\.Rproj$
22
^\.Rproj\.user$
33
^development_test\.R$
4+
.travis.yml

‎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...

‎data/santamonica.rda‎

-12.6 KB
Binary file not shown.

‎examples/smc-2016-03-01.owrs‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
---
2+
metadata:
3+
effective_date: 2016-03-01
4+
utility_name: "City of Santa Monica"
5+
bill_frequency: bimonthly
6+
rate_structure:
7+
RESIDENTIAL_SINGLE:
8+
tier_starts:
9+
- 0
10+
- 15
11+
- 41
12+
- 149
13+
tier_prices:
14+
- 2.87
15+
- 4.29
16+
- 6.44
17+
- 10.07
18+
commodity_charge: Tiered
19+
bill: commodity_charge
20+
RESIDENTIAL_MULTI:
21+
tier_starts:
22+
- 0
23+
- 5
24+
- 10
25+
- 21
26+
tier_prices:
27+
- 2.87
28+
- 4.29
29+
- 6.44
30+
- 10.07
31+
commodity_charge: Tiered
32+
bill: commodity_charge
33+
IRRIGATION:
34+
tier_starts:
35+
depends_on: meter_size
36+
values:
37+
5/8":
38+
- 0
39+
- 211
40+
3/4":
41+
- 0
42+
- 211
43+
1":
44+
- 0
45+
- 211
46+
1_1/2":
47+
- 0
48+
- 466
49+
2":
50+
- 0
51+
- 871
52+
3":
53+
- 0
54+
- 1701
55+
4":
56+
- 0
57+
- 2551
58+
6":
59+
- 0
60+
- 5281
61+
8":
62+
- 0
63+
- 5281
64+
10":
65+
- 0
66+
- 5281
67+
tier_prices:
68+
depends_on: water_type
69+
values:
70+
POTABLE:
71+
- 4.07
72+
- 10.03
73+
RECYCLED:
74+
- 3.66
75+
- 3.66
76+
commodity_charge: Tiered
77+
bill: commodity_charge
78+
COMMERCIAL:
79+
tier_starts:
80+
depends_on: meter_size
81+
values:
82+
5/8":
83+
- 0
84+
- 211
85+
3/4":
86+
- 0
87+
- 211
88+
1":
89+
- 0
90+
- 211
91+
1_1/2":
92+
- 0
93+
- 466
94+
2":
95+
- 0
96+
- 871
97+
3":
98+
- 0
99+
- 1701
100+
4":
101+
- 0
102+
- 2551
103+
6":
104+
- 0
105+
- 5281
106+
8":
107+
- 0
108+
- 5281
109+
10":
110+
- 0
111+
- 5281
112+
tier_prices:
113+
depends_on: water_type
114+
values:
115+
POTABLE:
116+
- 4.07
117+
- 10.03
118+
RECYCLED:
119+
- 3.66
120+
- 3.66
121+
commodity_charge: Tiered
122+
bill: commodity_charge
123+
INDUSTRIAL:
124+
tier_starts:
125+
depends_on: meter_size
126+
values:
127+
5/8":
128+
- 0
129+
- 211
130+
3/4":
131+
- 0
132+
- 211
133+
1":
134+
- 0
135+
- 211
136+
1_1/2":
137+
- 0
138+
- 466
139+
2":
140+
- 0
141+
- 871
142+
3":
143+
- 0
144+
- 1701
145+
4":
146+
- 0
147+
- 2551
148+
6":
149+
- 0
150+
- 5281
151+
8":
152+
- 0
153+
- 5281
154+
10":
155+
- 0
156+
- 5281
157+
tier_prices:
158+
depends_on: water_type
159+
values:
160+
POTABLE:
161+
- 4.07
162+
- 10.03
163+
RECYCLED:
164+
- 3.66
165+
- 3.66
166+
commodity_charge: Tiered
167+
bill: commodity_charge
168+
INSTITUTIONAL:
169+
tier_starts:
170+
depends_on: meter_size
171+
values:
172+
5/8":
173+
- 0
174+
- 211
175+
3/4":
176+
- 0
177+
- 211
178+
1":
179+
- 0
180+
- 211
181+
1_1/2":
182+
- 0
183+
- 466
184+
2":
185+
- 0
186+
- 871
187+
3":
188+
- 0
189+
- 1701
190+
4":
191+
- 0
192+
- 2551
193+
6":
194+
- 0
195+
- 5281
196+
8":
197+
- 0
198+
- 5281
199+
10":
200+
- 0
201+
- 5281
202+
tier_prices:
203+
depends_on: water_type
204+
values:
205+
POTABLE:
206+
- 4.07
207+
- 10.03
208+
RECYCLED:
209+
- 3.66
210+
- 3.66
211+
commodity_charge: Tiered
212+
bill: commodity_charge

0 commit comments

Comments
 (0)