Conversion between GIS data and SWMM with swmmr

Anneke Döring

2019-03-18

swmmr’s function inp_to_files


This function is an addition to the swmmr package. The function inp_to_files is used to convert SWMM projects saved as .inp to several independent files. While geographical informations are stored in .shp files, informations of the sections options, report, raingages, evaporation, pollutants, landuses, buildup, washoff and coverages are stored in one .txt file named ‘options.txt’. Furthermore timeseries are converted to SWMM’s timeseries format and saved in .dat files.

The usage of swmmr’s function inp_to_files is explained with Example1 shipped with the SWMM executable:

# First load the following packages:
library(swmmr)
library(purrr)
library(dplyr)
library(sf)
# in case your operating system is Windows, the examples are saved in the following directory:
# "C:/Users/.../Documents/EPA SWMM Projects/Examples/"
# please change the path to:
# "C:/Users/.../Documents/EPA_SWMM_Projects/Examples/"
# substitute '...' with your user name
# set path to inp
# If your operating system is Windows, the Example1.inp model is 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.
# Feel free to change this to your path of choice.
inp_file <- system.file("extdata", "Example1.inp", package = "swmmr", mustWork = TRUE)
# set the path to the output directory for the example files (here, we use a temp directory)
# Feel free to change this to your path of choice. 
out_dir <- tempdir()
# read the "Example1.inp" using read_inp
Example1 <- read_inp(x = inp_file)

# glance the structure of Example1
summary(Example1)
## 
## ** summary of swmm model structure ** 
## infiltration   :     horton 
## flow_units     :        cfs 
## flow_routing   :    kinwave 
## start_date     : 01/01/1998 
## end_date       : 01/02/1998 
## raingages      :          1 
## subcatchments  :          8 
## aquifers       :          0 
## snowpacks      :          0 
## junctions      :         13 
## outfalls       :          1 
## dividers       :          0 
## storages       :          0 
## conduits       :         13 
## pumps          :          0 
## orifices       :          0 
## weirs          :          0 
## outlets        :          0 
## controls       :          0 
## pollutants     :          2 
## landuses       :          2 
## lid_controls   :          0 
## treatment      :          0 
## *************************************
# convert .inp file into independent .shp and .txt files
inp_to_files(x = Example1, name = "Example1", path_out = out_dir)
## Warning in abbreviate_shapefile_names(obj): Field names abbreviated for
## ESRI Shapefile driver
## Writing layer `Example1_polygon' to data source `/var/folders/5s/kgm05t2s0_52gz1s445mnlgw0000gn/T//Rtmp7YYaAn/shp/Example1_polygon.shp' using driver `ESRI Shapefile'
## features:       8
## fields:         22
## geometry type:  Polygon
## Writing layer `Example1_link' to data source `/var/folders/5s/kgm05t2s0_52gz1s445mnlgw0000gn/T//Rtmp7YYaAn/shp/Example1_link.shp' using driver `ESRI Shapefile'
## features:       13
## fields:         16
## geometry type:  Line String
## Writing layer `Example1_point' to data source `/var/folders/5s/kgm05t2s0_52gz1s445mnlgw0000gn/T//Rtmp7YYaAn/shp/Example1_point.shp' using driver `ESRI Shapefile'
## features:       13
## fields:         6
## geometry type:  Point
## Writing layer `Example1_outfall' to data source `/var/folders/5s/kgm05t2s0_52gz1s445mnlgw0000gn/T//Rtmp7YYaAn/shp/Example1_outfall.shp' using driver `ESRI Shapefile'
## features:       1
## fields:         6
## geometry type:  Point
## section weirs is missing
## section orifices is missing
## section pumps is missing
## section storage is missing
## *.shp files were written to /var/folders/5s/kgm05t2s0_52gz1s445mnlgw0000gn/T//Rtmp7YYaAn/shp
## *.txt file was written to /var/folders/5s/kgm05t2s0_52gz1s445mnlgw0000gn/T//Rtmp7YYaAn/txt
## section curves is missing
## timeseries.dat files were written to /var/folders/5s/kgm05t2s0_52gz1s445mnlgw0000gn/T//Rtmp7YYaAn/dat
# check folders in your output directory:
list.files(out_dir)
## [1] "dat"              "file736a15c39de6" "file736a5db37233"
## [4] "shp"              "txt"
# check existence of shape, text and dat files:
c("shp", "txt", "dat") %>% 
  map( ~ file.path(out_dir, .)) %>% 
  map(list.files)
## [[1]]
##  [1] "Example1_link.dbf"    "Example1_link.shp"    "Example1_link.shx"   
##  [4] "Example1_outfall.dbf" "Example1_outfall.shp" "Example1_outfall.shx"
##  [7] "Example1_point.dbf"   "Example1_point.shp"   "Example1_point.shx"  
## [10] "Example1_polygon.dbf" "Example1_polygon.shp" "Example1_polygon.shx"
## 
## [[2]]
## [1] "Example1_options.txt"
## 
## [[3]]
## [1] "Example1_timeseries_TS1.dat"

swmmr’s function shp_to_inp


This is the counterpart to inp_to_files. Geographical informations stored in .shp files are converted to the input file format ‘.inp’ of SWMM using R. Informations on simulation settings, rain timeseries etc., stored in .txt or .dat files, complete these geographical informations.

Conversion of Example1 files to one inp file

Based on the converted files of Example1, the usage of swmmr’s function shp_to_inp is explained:

## 
## ** summary of swmm model structure ** 
## infiltration   :     horton 
## flow_units     :        cfs 
## flow_routing   :    kinwave 
## start_date     : 01/01/1998 
## end_date       : 01/02/1998 
## raingages      :          1 
## subcatchments  :          8 
## aquifers       :          0 
## snowpacks      :          0 
## junctions      :          0 
## outfalls       :          1 
## dividers       :          0 
## storages       :          0 
## conduits       :         13 
## pumps          :          0 
## orifices       :          0 
## weirs          :          0 
## outlets        :          0 
## controls       :          0 
## pollutants     :          2 
## landuses       :          2 
## lid_controls   :          0 
## treatment      :          0 
## *************************************

Now simulation runs can be initiated…

setup a new SWMM project using shp_to_inp

There are three different ways to define the parameters of the different SWMM sections:

  1. all parameter values are given in .shp files containing polygon, point or line features and one .txt file containing informations on simulation settings
  2. a minimum of information is given in the attribute tables of the shp files, additional parameters are completed with information given in the R objects: infiltration, subcatchment_typologies, conduit_material and junction_parameters
  3. information that is neither given in the input files (.shp or .txt) or supplementary R objects is internally complemented with default values

supplementary R objects:

Here examples for the structure of supplementary R objects are given:

The shp_to_inp function relies on the correct naming of the column names given in the .shp files: either you use the original swmm encoding (also given in swmmr::read_inp) or the swmm encoding abbreviated to seven characters (which is coerced when storing shp files, e.g. with sf::st_write).

In the moment, inp_to_files and shp_to_inp support the following SWMM inp sections:

The following sections are implemented with restrictions: