# Conversion between GIS data and SWMM with swmmr

#### Anneke Döring

#### 2020-03-02

## 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
    ## storage        :          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/09/17n5cv_n4tng_w61gx1lqwrm0000gn/T//RtmpvUSvAs/shp/Example1_polygon.shp' using driver `ESRI Shapefile'
    ## Writing 8 features with 22 fields and geometry type Polygon.
    ## Writing layer `Example1_link' to data source `/var/folders/09/17n5cv_n4tng_w61gx1lqwrm0000gn/T//RtmpvUSvAs/shp/Example1_link.shp' using driver `ESRI Shapefile'
    ## Writing 13 features with 16 fields and geometry type Line String.
    ## Writing layer `Example1_point' to data source `/var/folders/09/17n5cv_n4tng_w61gx1lqwrm0000gn/T//RtmpvUSvAs/shp/Example1_point.shp' using driver `ESRI Shapefile'
    ## Writing 13 features with 6 fields and geometry type Point.
    ## Writing layer `Example1_outfall' to data source `/var/folders/09/17n5cv_n4tng_w61gx1lqwrm0000gn/T//RtmpvUSvAs/shp/Example1_outfall.shp' using driver `ESRI Shapefile'
    ## Writing 1 features with 6 fields and 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/09/17n5cv_n4tng_w61gx1lqwrm0000gn/T//RtmpvUSvAs/shp

    ## *.txt file was written to /var/folders/09/17n5cv_n4tng_w61gx1lqwrm0000gn/T//RtmpvUSvAs/txt

    ## section curves is missing

    ## timeseries.dat files were written to /var/folders/09/17n5cv_n4tng_w61gx1lqwrm0000gn/T//RtmpvUSvAs/dat

    # check folders in your output directory:
    list.files(out_dir)

    ## [1] "dat" "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:

    # convert shp and txt files to inp object:
    Example1_con <- shp_to_inp(
      path_options = file.path(out_dir,"txt/Example1_options.txt"),
      path_timeseries = file.path(out_dir,"dat/Example1_timeseries_TS1.dat"),
      path_polygon = file.path(out_dir,"shp/Example1_polygon.shp"),
      path_line = file.path(out_dir,"shp/Example1_link.shp"),
      path_point = file.path(out_dir,"shp/Example1_point.shp"),
      path_outfall = file.path(out_dir,"shp/Example1_outfall.shp")
    )

    # glance the structure of the converted Example1
    summary(Example1_con)

    ##
    ## ** 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
    ## storage        :          0
    ## conduits       :         13
    ## pumps          :          0
    ## orifices       :          0
    ## weirs          :          0
    ## outlets        :          0
    ## controls       :          0
    ## pollutants     :          2
    ## landuses       :          2
    ## lid_controls   :          0
    ## treatment      :          0
    ## *************************************

    # save the input file to a new folder in the output directory:
    dir.create(file.path(out_dir, "inp_new"))
    write_inp(Example1_con, file.path(out_dir, "inp_new", "Example1_con.inp"))

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:

    # ... assuming infiltration parameters are not given in the .shp file, an R object (tibble or data.frame) called infiltration can be added. Additionally a column 'Soil' must be added to polygon shp file.

    infiltration <- tibble(
      Soil = c("A", "B"), # or: unique(polygon$Soil)
      MaxRate = c(76.2, 127),
      MinRate = c(3.81, 7.62),
      Decay = c(0.069, 0.069),
      DryTime = c(1,1),
      MaxInf = c(0,0)
    )

    # ... assuming not all subcatchment related parameters are given in the polygon .shp-file, an R object (tibble or data.frame) called subcatchment_typologies can be added. Additionally a column 'Type' must be added to the polygon .shp file.

    subcatchment_typologies <- tibble(
      Type = c("Street", "Park"), # or: unique(polygon$Type)
      Perc_Imperv = c(100, 10),
      Width = c(9, 30),
      Slope = c(0.57, 1),
      CurbLen = 0,
      Snowpack = ' ',
      Rain_Gage = "Test_rain",
      N_Imperv = c(0.01, 0.025),
      N_Perv = c(0.01, 0.2),
      S_Imperv = c(1.5, 0.58),
      S_Perv = c(1.5, 0.58),
      Pct_Zero = 0,
      PctRouted = 100
    )

    #...assuming roughness is not given in the line .shp file, an R object (tibble or data.frame) called conduit_material can be added. Additionally a column 'Material' must be added to the line .shp file
    conduit_material <- tibble(
      Material = "B", # or: unique(lines$Material)
      Roughness = 0.018
    )

    #... assuming surcharge of junctions should be added later:
    junction_parameters <- tibble(
      Y = 0,
      Ysur = 1,
      Apond = 1
    )

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:

- options
- raingages
- subcatchments
- subareas
- infiltration
- junctions
- outfalls
- storage
- conduits
- weirs
- xsections
- pollutants
- landuses
- coverages
- buildup
- washoff
- curves
- report
- coordinates
- polygons

The following sections are implemented with restrictions:

- evaporation: only constant value
- pumps: missing default values
- timeseries: *.dat file only