| Title: | Read Epanet Files into R |
|---|---|
| Description: | Reads water network simulation data in 'Epanet' text-based '.inp' and '.rpt' formats into R. Also reads results from 'Epanet-msx'. Provides basic summary information and plots. The README file has a quick introduction. See <http://www2.epa.gov/water-research/epanet> for more information on the Epanet software for modeling hydraulic and water quality behavior of water piping systems. |
| Authors: | Bradley J. Eck |
| Maintainer: | Bradley Eck <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.8.0 |
| Built: | 2025-02-05 05:11:14 UTC |
| Source: | https://github.com/bradleyjeck/epanetreader |
Generate break points for use with cut() and range labels based on sample max and min
binBreaker(x, nbin)binBreaker(x, nbin)
x |
vector to find cuts for |
nbin |
number of bins |
Helpful in making labels use the acutal max and min rather than the +/- 1
list with elements Breaks and Labels
A list of Epanet's default options
epanetDefaultOptions()epanetDefaultOptions()
Provides a named list in the form of OPTION = default_value where the values are taken from pages 152-154 of the manual.
Rossman, L. A. (2000). Epanet 2 users manual. US EPA, Cincinnati, Ohio. http://nepis.epa.gov/Adobe/PDF/P1007WWU.pdf
epanetDefaultOptions()epanetDefaultOptions()
epanetReader is a package for reading water network information and simulation results in Epanet's .inp and .rpt files into R. See functions read.inp, read.rpt, and read.msxrpt for some examples.
Bradley J. Eck
Create an expandedLinkTable object by adding node coordinates to a data frame of pipes, pumps, or valves.
expandedLinkTable(Links, Coordinates)expandedLinkTable(Links, Coordinates)
Links |
data frame of Pipes, Pumps or Valves of from epanet.inp |
Coordinates |
table of epanet.inp |
an expandedLinkTable object
x <- expandedLinkTable(Net1$Pipes, Net1$Coordinates) print(x) plot(x)x <- expandedLinkTable(Net1$Pipes, Net1$Coordinates) print(x) plot(x)
Check if an object as class 'epanet.inp'
is.epanet.inp(x)is.epanet.inp(x)
x |
an R object |
Check if an object has class 'epanet.rpt'
is.epanet.rpt(x)is.epanet.rpt(x)
x |
an R object |
Check if an object has class 'epanetmsx.rpt'
is.epanetmsx.rpt(x)is.epanetmsx.rpt(x)
x |
an R object |
Check if an object has class 'expandedLinkTable'
is.expandedLinkTable(x)is.expandedLinkTable(x)
x |
an R object |
Check if an object has class 'sparkline'
is.sparkline(x)is.sparkline(x)
x |
an R object |
Check if an object has class 'sparklineTable'
is.sparklineTable(x)is.sparklineTable(x)
x |
an R object |
A dataset created by reading the Net1.inp file distributed with Epanet using this package's read.inp() function.
Net1Net1
An object of class epanet.inp created by read.inp.
http://www.epa.gov/sites/production/files/2014-06/en2setup_0.exe
#confirm built-in dataset matches output of read.inp inp <- file.path( find.package("epanetReader"), "extdata","Net1.inp") n1 <- suppressWarnings( read.inp(inp) ) ok <- isTRUE( all.equal(Net1, n1)) if( ok==FALSE) stop("built-in Net1 doesn't match read.inp")#confirm built-in dataset matches output of read.inp inp <- file.path( find.package("epanetReader"), "extdata","Net1.inp") n1 <- suppressWarnings( read.inp(inp) ) ok <- isTRUE( all.equal(Net1, n1)) if( ok==FALSE) stop("built-in Net1 doesn't match read.inp")
A dataset created by reading the Net1.rpt file distributed with Epanet using this package's read.rpt() function.
Net1rptNet1rpt
An object of class epanet.rpt created by read.rpt.
#confirm built-in dataset matches output of read.rpt rpt <- file.path( find.package("epanetReader"), "extdata","Net1.rpt") n1r <- read.rpt(rpt) ok <- isTRUE( all.equal(Net1rpt, n1r)) if( ok==FALSE) stop("built-in Net1rpt doesn't match read.rpt")#confirm built-in dataset matches output of read.rpt rpt <- file.path( find.package("epanetReader"), "extdata","Net1.rpt") n1r <- read.rpt(rpt) ok <- isTRUE( all.equal(Net1rpt, n1r)) if( ok==FALSE) stop("built-in Net1rpt doesn't match read.rpt")
Make a plot of the network using base graphics
## S3 method for class 'epanet.inp' plot(x, plot.junctions = TRUE, legend.locn = "topright", plot.labels = FALSE, link.lwd = 3, link.col = "black", ...)## S3 method for class 'epanet.inp' plot(x, plot.junctions = TRUE, legend.locn = "topright", plot.labels = FALSE, link.lwd = 3, link.col = "black", ...)
x |
object of class epanet.inp |
plot.junctions |
logical indicating whether to plot junctions |
legend.locn |
character string passed to legend() specifying the location of the legend on the plot |
plot.labels |
logical indicating whether to plot the labels using text() |
link.lwd |
value of lwd passed to segments() |
link.col |
value of col passed to segments() |
... |
other arguments passed to plot() |
Implements the generic plot function for S3 objects of class epanet.inp. The plot is built from base graphics by creating a blank plot and then calling the helper functions plotInpLinks(), plotInpNodes(), plotElementsLegend().
plot(Net1) plot(Net1, plot.labels=TRUE)plot(Net1) plot(Net1, plot.labels=TRUE)
Plots simulation results for a single time step in map form
## S3 method for class 'epanet.rpt' plot(x, inp, Timestep = "0:00:00", juncQty = "Demand", linkQty = "Velocity", legend1.locn = "topright", legend2.locn = "topleft", ...)## S3 method for class 'epanet.rpt' plot(x, inp, Timestep = "0:00:00", juncQty = "Demand", linkQty = "Velocity", legend1.locn = "topright", legend2.locn = "topleft", ...)
x |
epanet.rpt object |
inp |
epanet.inp object associated with x |
Timestep |
string indicating the time to plot |
juncQty |
string specifying which column of x$nodeResults (Demand, Head, Pressure, Chlorine, etc.) to show by circle size at network junctions |
linkQty |
string specifying which column of x$linkResults (Flow, Velocity, Headloss) to show by line width on network links |
legend1.locn |
string passed to legend() for placing legend of network elements |
legend2.locn |
string passed to legend() for placing legend of junction and link quantities |
... |
further arguments passed to plot |
juncQty plots and values for Junctions only; Tanks and Reservoirs are not included. In contrast, linkQty is scaled over all of the link types: Pipes, Pumps & Valves. These choices aim at a map showing demand at junctions and velocity in links.
Plots a sparkline table of Epanet-msx results
## S3 method for class 'epanetmsx.rpt' plot(x, elementType = "Nodes", ...)## S3 method for class 'epanetmsx.rpt' plot(x, elementType = "Nodes", ...)
x |
epanetmsx.rpt object |
elementType |
character indicating whether results for "nodes" or links" should be plotted |
... |
further arguments passed to plotSparklineTable |
plotSparklineTable
plot an expanded link table
## S3 method for class 'expandedLinkTable' plot(x, add = FALSE, label = FALSE, linewidths = 3, color = "black", ...)## S3 method for class 'expandedLinkTable' plot(x, add = FALSE, label = FALSE, linewidths = 3, color = "black", ...)
x |
object of type expandedLinkTable |
add |
logical indicating whether to add to the currently active plot. add=FALSE creates a new plot. |
label |
logical indicating if the links should be labeled at the mid points |
linewidths |
passed to lwd argument in segments() |
color |
passed to col argument in segments() |
... |
further arguments passed to segments() |
An implementation of the generic plot function for expandedLinkTable objects. Links are drawn using segments(). Useful for building up network plots.
Plot a sparkline
## S3 method for class 'sparkline' plot(x, ...)## S3 method for class 'sparkline' plot(x, ...)
x |
sparkline object |
... |
further arguments passed to plot.default |
Implementation of the generic plot function for a single sparkline object. The primarily used to build up plots of a sparklineTable
sparkline
Plot Sparkline Table
## S3 method for class 'sparklineTable' plot(x, ...)## S3 method for class 'sparklineTable' plot(x, ...)
x |
object of class sparklineTable |
... |
further arguments passed to par |
Add legend of network elements to the active plot
plotElementsLegend(legend.locn)plotElementsLegend(legend.locn)
legend.locn |
keyword for location of legend. See details of legend() function. |
Helper function for adding a legend to the active plot. Uses plot characters 16, 15, 8 and 25 for Tanks, Reservoirs, Pumps and Valves for compatibility with plotInpNodes()
## make a new blank plot plot( c(0,1), c(0,1), type = 'n') ## add the nodes, including junctions plotElementsLegend('topright')## make a new blank plot plot( c(0,1), c(0,1), type = 'n') ## add the nodes, including junctions plotElementsLegend('topright')
Add lines for pipes, pumps and valves from an epanet.inp object to an existing plot
plotInpLinks(x, lwd = 3, col = "black")plotInpLinks(x, lwd = 3, col = "black")
x |
epanet.inp object |
lwd |
width of lines |
col |
color of lines |
Helper function for building up a plot of the network by adding links to an existing plot.
## make a new blank plot plot( range(Net1$Coordinates$X), range(Net1$Coordinates$Y), type = 'n') ## add the links plotInpLinks(Net1)## make a new blank plot plot( range(Net1$Coordinates$X), range(Net1$Coordinates$Y), type = 'n') ## add the links plotInpLinks(Net1)
Adds node elements from epanet.inp object to an existing plot
plotInpNodes(x, plot.junctions)plotInpNodes(x, plot.junctions)
x |
epanet.inp object |
plot.junctions |
logical indicating whether to plot junctions |
Helper function for building up a network plot. Tanks and Reservoirs are shown using plot characters (pch) ' 16 and 15. Junctions, if plotted, appear as pch ="."
## make a new blank plot plot( range(Net1$Coordinates$X), range(Net1$Coordinates$Y), type = 'n') ## add the nodes, including junctions plotInpNodes(Net1, TRUE )## make a new blank plot plot( range(Net1$Coordinates$X), range(Net1$Coordinates$Y), type = 'n') ## add the nodes, including junctions plotInpNodes(Net1, TRUE )
Generate a table of sparkline plots
plotSparklineTable(df, row.var, col.vars, xvar = NULL, xrange.labels = NULL)plotSparklineTable(df, row.var, col.vars, xvar = NULL, xrange.labels = NULL)
df |
data.frame of values to plot. |
row.var |
variable for rows of the table |
col.vars |
variables for columns of the table |
xvar |
optional name of variable for horizontal axis of sparkline plots |
xrange.labels |
optional vector of length 2 with labels for the first and last quantities plotted on x-axis, often a date and/or time |
Generates a table of 'sparkline' plots of data in df. rows the table correspond to different values of row.var. The table's first column gives the value of row.var. The remaining columns contain sparkline plots for the values of col.vars. When xvar is not provided values are plotted against their index in the extracted vector. The starting and ending values are labeled. Uses layout() function to arrange plots.
E. Tufte, Beautiful Evidence, Graphics Press, 2006.
yaletoolkit and sparkTable packages
plotSparklineTable( Orange, row.var = 'Tree', col.vars = c('age','circumference')) plotSparklineTable( Loblolly, row.var = 'Seed', col.vars = 'height') ## specify the x variable if you have it, especially if it differs plotSparklineTable(Theoph, row.var = 'Subject', col.vars = 'conc') ## a warning is normally issued with the ranges of xvar differ suppressWarnings( plotSparklineTable(Theoph, row.var = 'Subject', col.vars = 'conc', xvar = 'Time'))plotSparklineTable( Orange, row.var = 'Tree', col.vars = c('age','circumference')) plotSparklineTable( Loblolly, row.var = 'Seed', col.vars = 'height') ## specify the x variable if you have it, especially if it differs plotSparklineTable(Theoph, row.var = 'Subject', col.vars = 'conc') ## a warning is normally issued with the ranges of xvar differ suppressWarnings( plotSparklineTable(Theoph, row.var = 'Subject', col.vars = 'conc', xvar = 'Time'))
The function prints a summary of simulation results contained in the rpt file.
## S3 method for class 'summary.epanet.rpt' print(x, ...)## S3 method for class 'summary.epanet.rpt' print(x, ...)
x |
a summary.epanet.rpt object |
... |
further arguments passed to print |
The function prints a summary of multi-species simulation results contained in the report file
## S3 method for class 'summary.epanetmsx.rpt' print(x, ...)## S3 method for class 'summary.epanetmsx.rpt' print(x, ...)
x |
a summary.epanetmsx.rpt object |
... |
further arguments passed to print |
Wrapper function for different implementations of readlines functions
read_lines_wrapper(file)read_lines_wrapper(file)
file |
the name of the file to read |
calls Kmisc::readlines if available and base::readLines otherwise
character vector where each entry corresponds to a line in the file.
Read an Epanet .inp file into R
read.inp(file)read.inp(file)
file |
the name of the file to read |
This function reads a text file in Epanet's .inp format and returns an S3 object with entries for sections of the .inp file. Sections of the .inp file that are implemented appear in the Value section.
Fields for node or link ID are stored as characters not factors or integers. However, some fields are stored as factors to allow more informative summaries. Examples include valve type and pipe status.
Sections that are absent from the .inp file are NULL in the list.
Columns of data.frames use the headings exported by the Epanet GUI.
The [OPTIONS] section in the .inp file is used to update a list of Epanet's default options. In this way if an option such as units is not specified by the .inp file, the units that would be used by default are provided.
In the [PATTERNS] and [CURVES] sections, integers used as names of list elements are backquoted according to the default behavior in R. So if the .inp file has a pattern "1" this pattern will appear as element '1' in the list that is returned. A warning is issued in this case.
Returns an epanet.inp S3 object with elements of the following names and types corresponding to sections of the .inp file. Sections missing from the .inp file have a value of NULL.
Title |
character |
Junctions |
data.frame |
Tanks |
data.frame |
Reservoirs |
data.frame |
Pipes |
data.frame |
Pumps |
data.frame |
Valves |
data.frame |
Demands |
data.frame |
Status |
data.frame |
Emitters |
data.frame |
Quality |
data.frame |
Sources |
data.frame |
Reactions |
character |
Mixing |
data.frame |
Patterns |
list |
Curves |
list |
Controls |
character |
Rules |
character |
Energy |
character |
Times |
character |
Report |
character |
Options |
list |
Coordinates |
data.frame |
Vertices |
data.frame |
Labels |
data.frame |
Backdrop |
character |
Tags |
character |
Rossman, L. A. (2000). Epanet 2 users manual. US EPA, Cincinnati, Ohio.
http://nepis.epa.gov/Adobe/PDF/P1007WWU.pdf
# path to Net1.inp example file included with this package inp <- file.path( find.package("epanetReader"), "extdata","Net1.inp") #read the network file into R n1 <- read.inp(inp) summary(n1) names(n1) summary(n1$Junctions) summary(n1$Pipes) plot(n1)# path to Net1.inp example file included with this package inp <- file.path( find.package("epanetReader"), "extdata","Net1.inp") #read the network file into R n1 <- read.inp(inp) summary(n1) names(n1) summary(n1$Junctions) summary(n1$Pipes) plot(n1)
reads an Epanet-msx .rpt file into R
read.msxrpt(file)read.msxrpt(file)
file |
the name of the file to read |
Specify the needed outputs from an Epanet-msx simulation in the [REPORT] section of the .msx file to create reports for reading with with this function.
The function returns an S3 object (list) with a data.frame for node results and data.frame for link results. These data.frames contain results from all the time periods to facilitate time series plots.
Returns an epanetmsx.rpt S3 object .
nodeResults |
data.frame |
linkResults |
data.frame |
Shang, F., Uber, J.G., Rossman, L.A. (2011) EPANET Multi-species Extension User's Manual. US Environmental Protection Agency, Cincinnati.
# path to example file included with this package msr <- file.path( find.package("epanetReader"), "extdata","example.rpt") #read the results into R x <- read.msxrpt(msr) names(x) summary(x) plot(x)# path to example file included with this package msr <- file.path( find.package("epanetReader"), "extdata","example.rpt") #read the results into R x <- read.msxrpt(msr) names(x) summary(x) plot(x)
reads an Epanet .rpt file into R
read.rpt(file)read.rpt(file)
file |
the name of the file to read |
add lines "Page 0", "Links All" and "Nodes All" to the [REPORT] section of the .inp file to output info to read in with this function
In contrast to the treatment of .inp files, data from .rpt files is stored using a slightly different structure than the .rpt file. The function returns an object (list) with a data.frame for node results and data.frame for link results and a data.frame for energy usage. The node and link results data frames contain results from all the time periods to facilitate time series plots.
Returns an epanet.rpt S3 object with two data.frame elements.
nodeResults |
data.frame |
linkResults |
data.frame |
energyUsage |
data.frame |
Rossman, L. A. (2000). Epanet 2 users manual. US EPA, Cincinnati, Ohio.
http://nepis.epa.gov/Adobe/PDF/P1007WWU.pdf
# path to Net1.rpt example file included with this package rpt <- file.path( find.package("epanetReader"), "extdata","Net1.rpt") n1r <- read.rpt(rpt) summary(n1r) names(n1r) #Results for a chosen time period can be retrieved using the subset function. subset(n1r$nodeResults, Timestamp == "0:00:00") # time series plot for a nodal value plot( Chlorine ~ timeInSeconds, data = subset(n1r$nodeResults, ID == "22")) # Plotting the epanet.rpt object itself gives a map. # Note that the object created from the .inp file is required. inp <- file.path( find.package("epanetReader"), "extdata","Net1.inp") n1 <- read.inp(inp) plot( n1r, n1) # Energy Usage table print(n1r$energyUsage)# path to Net1.rpt example file included with this package rpt <- file.path( find.package("epanetReader"), "extdata","Net1.rpt") n1r <- read.rpt(rpt) summary(n1r) names(n1r) #Results for a chosen time period can be retrieved using the subset function. subset(n1r$nodeResults, Timestamp == "0:00:00") # time series plot for a nodal value plot( Chlorine ~ timeInSeconds, data = subset(n1r$nodeResults, ID == "22")) # Plotting the epanet.rpt object itself gives a map. # Note that the object created from the .inp file is required. inp <- file.path( find.package("epanetReader"), "extdata","Net1.inp") n1 <- read.inp(inp) plot( n1r, n1) # Energy Usage table print(n1r$energyUsage)
Create sparkline object by extracting from a data frame
sparkline(df, id.var, ID, yvar, xvar)sparkline(df, id.var, ID, yvar, xvar)
df |
data.frame from which data for the sparkline is extracted |
id.var |
variable in df with IDs |
ID |
value in id.var on which to extract |
yvar |
name of variable for the y values in the sparkline |
xvar |
optional name of variable for horizontal axis of sparkline plots |
Creates an object with info for a single sparkline by extracting from a data.frame. The function works on data.frames with one column of ID variables and possibly several columns of other variables. The main use is as a helper function for building up a sparklineTable.
## look at the names in the built-in data set Theoph names(Theoph) ## make sparkline object for the concentration over time in subject 2 sl <- sparkline(df= Theoph, id.var = 'Subject', ID = 2, yvar='conc', xvar = 'Time') plot(sl)## look at the names in the built-in data set Theoph names(Theoph) ## make sparkline object for the concentration over time in subject 2 sl <- sparkline(df= Theoph, id.var = 'Subject', ID = 2, yvar='conc', xvar = 'Time') plot(sl)
Create S3 object of data for table of sparklines
sparklineTable(df, row.var, col.vars, xvar = NULL, xrange.labels = NULL)sparklineTable(df, row.var, col.vars, xvar = NULL, xrange.labels = NULL)
df |
data.frame of values to plot. |
row.var |
variable for rows of the table |
col.vars |
variables for columns of the table |
xvar |
optional name of variable for horizontal axis of sparkline plots |
xrange.labels |
optional vector of length 2 with labels for the first and last quantities plotted on x-axis, often a date and/or time |
plotSparklineTable
Summarizes the network by printing the Title of the network and the number of each type of elements.
## S3 method for class 'epanet.inp' summary(object, ...)## S3 method for class 'epanet.inp' summary(object, ...)
object |
of class epanet.inp |
... |
futher arguments |
Provides a basic summary of simulation results
## S3 method for class 'epanet.rpt' summary(object, ...)## S3 method for class 'epanet.rpt' summary(object, ...)
object |
of epanet.rpt class |
... |
further arguments passed to summary() |
Summary of pipe results shows positive and negative values of flow but only positive values of velocity as in the rpt file.
Provides a basic summary of simulation results
## S3 method for class 'epanetmsx.rpt' summary(object, ...)## S3 method for class 'epanetmsx.rpt' summary(object, ...)
object |
of epanetmsx.rpt class |
... |
further arguments passed to summary() |
Write an epanet.inp object to a file
write.inp(x, file)write.inp(x, file)
x |
epanet.inp object to write |
file |
the name of the file where object is written |
Writes an epanet.inp object to a file suitable for simulation with EPANET.
nothing
write.inp(Net1, "Net1-fromR.inp") n1 <- read.inp("Net1-fromR.inp") all.equal(Net1, n1)write.inp(Net1, "Net1-fromR.inp") n1 <- read.inp("Net1-fromR.inp") all.equal(Net1, n1)