Package 'swmmr'

Plot a swmm model structure using ggplot2

Description

This function reads an object of class 'inp'. All objects are converted to simple feature geometries via inp_to_sf and finally passed to geom_sf. It allows to quickly visualize a model structure.

Usage

## S3 method for class 'inp'
autoplot(x, ...)

Arguments

x	An inp object
...	currently ignored

Note

Lifecycle: experimental

Examples

## Not run: 
inp <- read_inp("model.inp")
autoplot(inp)

## End(Not run)

---

Convert swmm objects to simple feature geometries

Description

• junctions_to_sf(): converts junctions to simple features (required sections: junctions and coordinates)

• outfalls_to_sf(): converts junctions to simple features (required sections: outfalls and coordinates)

• links_to_sf(): converts links to simple features (required sections: conduits and coordinates)

• subcatchments_to_sf(): converts subcatchments to simple features (required sections: subcatchments, subareas, infiltration and polygons)

• raingages_to_sf() : converts raingages to simple features (required sections: raingages and symbols)

• storages_to_sf(): converts storages to simple features (required sections: storage and coordinates)

• weirs_to_sf(): converts weirs to simple features (required sections: weirs and coordinates)

• orifices_to_sf(): converts orifices to simple features (required sections: orifices and coordinates)

• pumps_to_sf(): converts pumps to simple features (required sections: pumps and coordinates)

• inp_to_sf(): converts junctions, outfalls, links, storages, weirs, orifices, pumps, subcatchments and raingages to a list of simple features

Usage

raingages_to_sf(x)

junctions_to_sf(x)

outfalls_to_sf(x)

storages_to_sf(x)

subcatchments_to_sf(x)

links_to_sf(x)

weirs_to_sf(x)

orifices_to_sf(x)

pumps_to_sf(x)

weirs_to_sf(x)

orifices_to_sf(x)

pumps_to_sf(x)

inp_to_sf(x, remove_invalid = TRUE)

Arguments

x	An object of class 'inp', created by read_inp.
remove_invalid	Should invalid sf geometries be removed?

Value

A simple feature or a list of simple features

See Also

sf

---

Get the content of an .out file.

Description

This function opens an .out file and lists all available time series data. Currently, the list is returned 'as is' which might change in future. It belongs to a set of helper functions which aim to simplify the work with .out files. The lifecycle of this function is considered experimental.

Usage

get_out_content(file = "")

Arguments

file	The file to be read.

Value

A list showing the available content.

Examples

## Not run: 
content <- get_out_content("model.out")

## End(Not run)

---

Get the swmm version the .out file was generated with

Description

This function opens an .out file and extract the swmm version the file was generated with. It belongs to a set of helper functions which aim to simplify the work with .out files. The lifecycle of this function is considered experimental.

Usage

get_out_version(file = "")

Arguments

file	The file to be read.

Value

A vector of type integer

Examples

## Not run: 
version <- get_out_version("model.out")

## End(Not run)

---

Convert SWMM's .inp to .shp and txt files

Description

Convert SWMM's .inp to .shp and txt files

Usage

inp_to_files(x, name, path_out = getwd())

Arguments

x	An object of class inp.
name	Give a name for the current model, e.g. "Example1".
path_out	Writeable directory name where to save the converted files. Folders: dat, shp and txt will be created if not existent. Default is the current working directory of the R process.

Value

.dat, .shp and/or .txt files.

---

Read SWMM's .inp file

Description

Reads a SWMM .inp file and creates a list with corresponding SWMM sections.

Usage

read_inp(x, rm.comment = TRUE, ...)

Arguments

x	Name (incl. path) to an input file.
rm.comment	Should lines with comments starting with a ";" be discarded?
...	optional arguments passed to read_lines.

Value

An object of class inp

Examples

## Not run: 
list_of_inp_sections <- read_inp("model.inp")

## End(Not run)

---

Read SWMM's LID Report File

Description

Reads a SWMM's LID Report File and returns a tibble

Usage

read_lid_rpt(x, return_xts = TRUE, ...)

Arguments

x	Name (incl. path) to a LID report file.
return_xts	logical. Sets the return type. If set to TRUE, xts objects are returned, FALSE gives tibbles.
...	optional arguments passed to read_table2

Value

A tibble or xts object

Examples

## Not run: 
tbl_lid_rpt <- read_lid_rpt("lid_rpt.txt")

## End(Not run)

---

Read time series data from SWMM's .out file

Description

Reads the binary output ('.out') generated by the stormwater management model 'SWMM' and creates a list of xts-objects.

Usage

read_out(file = "", iType = NULL, object_name = NULL, vIndex = NULL)

Arguments

file	The file to be read.
iType	Sets the result type: 0 for Subcatchments, 1 for nodes, 2 for links, 3 for system variables. Leave empty for retrieving elements available.
object_name	Sets the objects of which time series data is returned. Leave empty for retrieving elements available.
vIndex	Sets the variables to be read (s. Details). Leave empty for retrieving elements available.

Details

vIndex depends on the result type. Choices are...

for each subcatchment variable:

• 0 for rainfall rate (in/hr or mm/hr),

• 1 for snow depth (inches or millimeters),

• 2 for evaporation loss (in/day or mm/day),

• 3 for infiltration loss (in/hr or mm/hr),

• 4 for runoff flow (flow units),

• 5 for groundwater flow into the drainage network (flow units),

• 6 for groundwater elevation (ft or m),

• 7 for soil moisture in the unsaturated groundwater zone (volume fraction),

• 7 + N for washoff concentration of each pollutant (mass/liter).

for each node variable:

• 0 for water depth (ft or m above the node invert elevation),

• 1 for hydraulic head (ft or m, absolute elevation per vertical datum),

• 2 for stored water volume (including ponded water, ft3 or m3),

• 3 for lateral inflow (runoff + all other external inflows, in flow units),

• 4 for total inflow (lateral inflow + upstream inflows, in flow units),

• 5 for surface flooding (excess overflow when the node is at full depth, in flow units),

• 5 + N for concentration of each pollutant after any treatment (mass/liter),

for each link variable:

• 0 for flow rate (flow units),

• 1 for average water depth (ft or m),

• 2 for flow velocity (ft/s or m/s),

• 3 for volume of water (ft3 or m3),

• 4 for capacity (fraction of full area filled by flow for conduits; control setting for pumps and regulators),

• 4 + N for concentration of each pollutant (mass/liter),

for each system-wide variable:

• 0 for air temperature (deg. F or deg. C),

• 1 for total rainfall (in/hr or mm/hr),

• 2 for total snow depth (inches or millimeters),

• 3 for average losses (in/hr or mm/hr),

• 4 for total runoff (flow units),

• 5 for total dry weather inflow (flow units),

• 6 for total groundwater inflow (flow units),

• 7 for total RDII inflow (flow units),

• 8 for total external inflow (flow units),

• 9 for total direct inflow (flow units),

• 10 for total external flooding (flow units),

• 11 for total outflow from outfalls (flow units),

• 12 for total nodal storage volume ( ft3 or m3),

• 13 for potential evaporation (in/day or mm/day),

• 14 for actual evaporation (in/day or mm/day).

Value

A list of xts-objects.

See Also

xts.

Examples

## Not run: 
xts_list_of_results <- read_out("model.out")

## End(Not run)

---

Read SWMM's .rpt file

Description

Reads a SWMM .rpt file and creates a list with corresponding results sections.

Usage

read_rpt(x, ...)

Arguments

x	Name (incl. path) to an report file.
...	optional arguments passed to read_lines

Value

An object of class rpt

Examples

## Not run: 
list_of_rpt_results <- read_rpt("model.rpt")

## End(Not run)

---

Initiate a simulation run

Description

This function runs a swmm inp file. If rpt and out files are not specified files are automatically created in the same directory of the inp file.

Usage

run_swmm(inp, rpt = NULL, out = NULL, exec = NULL, stdout = "", wait = TRUE)

Arguments

inp	Name and path to an input file.
rpt	Name and path to a report file.
out	Name and path to an out file.
exec	Name and path to swmm5 executable. If not manually set, the following paths are looked up when package gets loaded: windows: "C:/Program Files (x86)/EPA SWMM 5.X.XXX/swmm5.exe" not windows: "/usr/local/bin/swmm5" , "/usr/bin/swmm5"
stdout	where output to ‘stdout’ or ‘stderr’ should be sent. Possible values are "", to the R console (the default), NULL or FALSE (discard output), TRUE (capture the output in a character vector) or a character string naming a file.
wait	a logical (not NA) indicating whether the R interpreter should wait for the command to finish, or run it asynchronously. This will be ignored (and the interpreter will always wait) if stdout = TRUE or stderr = TRUE. When running the command asynchronously, no output will be displayed on the Rgui console in Windows (it will be dropped, instead).

Details

The path to a swmm5 executable is read by calling 'getOption("swmmr.exec")'.

Examples

## Not run: 
result <- run_swmm("model.inp")

## End(Not run)

---

Convert *.shp files to SWMM's *.inp file

Description

Reads *.shp files and other information needed for SWMM's *.inp file and returns a list of class inp. If paths are not specified default values are taken.

Usage

shp_to_inp(
  path_options = NULL,
  path_polygon = NULL,
  subcatchment_typologies = NULL,
  path_point = NULL,
  junction_parameters = NULL,
  path_outfall = NULL,
  path_line = NULL,
  conduit_material = NULL,
  path_timeseries = NULL,
  infiltration = NULL,
  path_pumps = NULL,
  path_pump_curve = NULL,
  path_weirs = NULL,
  path_storage = NULL,
  path_storage_curve = NULL
)

Arguments

path_options	Name (incl. path) to a .txt file with SWMM sections. Write section name in lower case and in squared brackets. The following sections are allowed: options, report, raingages, evaporation, pollutant, landuse, buildup, washoff, coverages.
path_polygon	Name (incl. path) to a .shp file with polygons features. At least the following subcatchment related columns must be specified: Name, Outlet, Area, RouteTo.
subcatchment_typologies	R data.frame or tibble with further subcatchment related parameters. If subcatchment_typologies is given, polygon feature has to include a column named Type. Parameters defined in subcatchment_typologies parameters are merged to subcatchments by Type.
path_point	Name (incl. path) to a .shp file with point features. At least the following junction related columns must be specified: Name, Bottom and Top or Ymax.
junction_parameters	R data.frame or tibble with further junction related parameters (e.g. Surcharge depth).
path_outfall	Name (incl. path) to a .shp file with point features. At least the following outfall related columns must be specified: Name, Bottom, Type, Gated.
path_line	Name (incl. path) to a .shp file with line features. At least the following conduit related coulumns must be specified: Name, Length, Type, FromNode, ToNode, OutOffset, Geom1.
conduit_material	R data.frame or tibble with further conduit related parameters (e.g. roughness). If conduit_material is given, line feature has to include a column named Material. Parameters defined in conduit_material parameters are merged to conduits by Material.
path_timeseries	Name (incl. path) to a .dat file with a timeseries in SWMM format.
infiltration	R data.frame or tibble with infiltration parameters related to soil properties. If infiltration is given, polygon feature has to include a column named soil. Infiltration parameters are merged to subcatchments by soil name.
path_pumps	Name (incl. path) to a .shp file with line features. All parameters must be given: Name, FromNode, ToNode, Pcurve, status, Startup, Shutoff.
path_pump_curve	Name (incl. path) to a .txt file with pump curve information. Having the following structure: "Name of pump" "PUMP1-4" "x" "y", without header.
path_weirs	Name (incl. path) to a .shp file with line features. All parameters must be given: Name, FromNode, ToNode, Type, CrestHt, Cd, Gated, EC, Cd2, Sur.
path_storage	Name (incl. path) to a .txt file with storage curve information. Having the following structure: "Name of storage" "Storage" "x" "y", without header.
path_storage_curve	Name (incl. path) to a .txt file with storage curve information. Having the following structure: "Name of storage unit" "Storage" "x" "y", without header.

Value

A list of class inp.

---

Show summary of a swmm model structure

Description

Show summary of a swmm model structure

Usage

## S3 method for class 'inp'
summary(object, ...)

Arguments

object	An object of class 'inp', created by read_inp.
...	Additional parameters (currently ignored).

Value

The input is returned invisibly.

Examples

## Not run: 
x <- read_inp("model.inp")
summary(x)

## End(Not run)

---

swmmr package

Description

R Interface for US EPA's SWMM

---

Write SWMM's .inp file

Description

Writes an inp object to disk which can be read and run by SWMM.

Usage

write_inp(x, file)

Arguments

x	An object of class 'inp', created by read_inp.
file	either a character string naming a file or a connection open for writing. "" indicates output to the console.

Examples

## Not run: 
  write_inp(inp, "~/model.inp")

## End(Not run)

---