-
Notifications
You must be signed in to change notification settings - Fork 15
/
README.Rmd
169 lines (132 loc) · 6.3 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
---
title: "swmmr"
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-"
)
Sys.setenv(LANG = "en")
```
[](https://cran.r-project.org/package=swmmr) [](https://travis-ci.org/dleutnant/swmmr)
Functions to connect the widely used [Storm Water Management Model (SWMM)](https://www.epa.gov/water-research/storm-water-management-model-swmm)
of the United States Environmental Protection Agency (US EPA) to R with currently
two main goals: (1) Run a SWMM simulation from R and (2) provide fast
access to simulation results, i.e. SWMM's binary '.out'-files. High performance is
achieved with help of Rcpp. Additionally, reading SWMM's '.inp' and '.rpt' files is supported to
glance model structures and to get direct access to simulation summaries.
## Installation
Installation is easy thanks to CRAN:
```{r cran, eval = FALSE}
install.packages("swmmr")
```
You can install the dev version from github with:
```{r gh-installation, eval = FALSE}
# install.packages("remotes")
remotes::install_github("dleutnant/swmmr")
```
## Example
This is a basic example which shows you how to work with the package. We use
the example shipped with the SWMM5 executable.
### Initiate a SWMM run and retrieve simulation results
```{r example}
library(swmmr)
library(purrr) # to conveniently work with list objects
# set path to inp
# If your operating system is Windows, the Example model files are usually
# located at "C:\Users\your user name\Documents\EPA SWMM Projects\Examples".
# For convenience the Example1.inp model is also included in the swmmr package.
inp_path <- system.file("extdata", "Example1.inp", package = "swmmr", mustWork = TRUE)
# glance model structure, the result is a list of data.frames with SWMM sections
inp <- read_inp(x = inp_path)
# show swmm model summary
summary(inp)
# for example, inspect section subcatchments
inp$subcatchments
# run a simulation
# the result is a named list of paths, directing
# to the inp, rpt and out-file, respectively.
files <- run_swmm(inp = inp_path)
# we can now read model results from the binary output:
# here, we focus on the system variable (iType = 3) from which we pull
# total rainfall (in/hr or mm/hr) and total runoff (flow units) (vIndex = c(1,4)).
results <- read_out(files$out, iType = 3, vIndex = c(1, 4))
# results is a list object containing two time series
str(results, max.level = 2)
# basic summary
results[[1]] %>% invoke(merge, .) %>% summary
# basic plotting
results[[1]] %>% imap( ~ plot(.x, main = .y))
# We also might be interested in the report file:
# use read_rpt to get is a list of data.frames with SWMM summary sections
report <- read_rpt(files$rpt)
# glance available summaries
summary(report)
# convenient access to summaries through list structure
report$subcatchment_runoff_summary
```
### Visualisation of model structure
With help of packages 'ggplot2' and 'sf' we can easily plot entire swmm models.
Note that ggplot2 (>= 2.2.1.9000) is required, which provides the geometric
object `geom_sf()`.
```{r visualization}
library(ggplot2)
# initially, we convert the objects to be plotted as sf objects:
# here: subcatchments, links, junctions, raingages
sub_sf <- subcatchments_to_sf(inp)
lin_sf <- links_to_sf(inp)
jun_sf <- junctions_to_sf(inp)
rg_sf <- raingages_to_sf(inp)
# calculate coordinates (centroid of subcatchment) for label position
lab_coord <- sub_sf %>%
sf::st_centroid() %>%
sf::st_coordinates() %>%
tibble::as_tibble()
# raingage label
lab_rg_coord <- rg_sf %>%
{sf::st_coordinates(.) + 500} %>% # add offset
tibble::as_tibble()
# add coordinates to sf tbl
sub_sf <- dplyr::bind_cols(sub_sf, lab_coord)
rg_sf <- dplyr::bind_cols(rg_sf, lab_rg_coord)
# create the plot
ggplot() +
# first plot the subcatchment and colour continously by Area
geom_sf(data = sub_sf, aes(fill = Area)) +
# label by subcatchments by name
geom_label(data = sub_sf, aes(X, Y, label = Name), alpha = 0.5, size = 3) +
# add links and highlight Geom1
geom_sf(data = lin_sf, aes(colour = Geom1), size = 2) +
# add junctions
geom_sf(data = jun_sf, aes(size = Elevation), colour = "darkgrey") +
# finally show location of raingage
geom_sf(data = rg_sf, shape = 10) +
# label raingage
geom_label(data = rg_sf, aes(X, Y, label = Name), alpha = 0.5, size = 3) +
# change scales
scale_fill_viridis_c() +
scale_colour_viridis_c(direction = -1) +
# change theme
theme_linedraw() +
theme(panel.grid.major = element_line(colour = "white")) +
# add labels
labs(title = "SWMM model Example1",
subtitle = "customized visualization")
```
## Contributions
With the release of `swmmr` 0.9.0, the latest contributions and other code that will appear in the next CRAN release is contained in the [`master`](https://github.com/dleutnant/swmmr) branch. Thus, contributing to this package is easy. Just send a simple [pull request](https://help.github.com/articles/using-pull-requests/). Your PR should pass `R CMD check --as-cran`, which will also be checked by <a href="https://travis-ci.org/dleutnant/swmmr">Travis CI</a> when the PR is submitted.
## Code of condcut
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/dleutnant/swmmr/blob/master/CONDUCT.md). By participating in this project you agree to abide by its terms.
## Acknowledgments
This package has been mainly developed in the course of the project [STBMOD](https://www.fh-muenster.de/forschung/forschungskatalog/projekt.php?pr_id=722),
carried out at the [Institute for Infrastructure, Water, Resources, Environment (IWARU)](https://en.fh-muenster.de/iwaru/index.php) of the
[Muenster University of Applied Sciences](https://www.fh-muenster.de).
The project was funded by the German Federal Ministry of Education and Research (BMBF, FKZ 03FH033PX2).
The development of the R package was inspired by the work of [Peter Steinberg](https://github.com/PeterDSteinberg/RSWMM). Also, it benefits from the Interface Guide of [SWMM](https://www.epa.gov/water-research/storm-water-management-model-swmm).
## Citation
```{r citation, echo=FALSE, results='asis', warning=FALSE}
citation("swmmr")
```