VisWaterNet: A Python package for visualization of water distribution networks

Water distribution systems (WDSs) are complex networks and are typically represented as graphs with multiple types of nodes (e.g., junctions, reservoirs, and tanks) and links (e


Statement of need
Existing open-source tools for analyzing WDSs, such as EPANET (Rossman et al., 2020) and the Water Network Tool for Resilience Python package (WNTR) (Klise et al., 2017), allow users to perform extended period simulations and analyze system hydraulic performance under a range of different conditions.However, while these tools provide basic network visualization options, they are limited in their flexibility and capabilities.EPANET wrappers in other programming languages also offer few plotting functions; for example, an EPANET-interfacing toolkit developed for MATLAB (Eliades et al., 2016) only generates network layouts, and a similar R application (Arandia & Eck, 2018) generates basic network representations.On the other hand, popular software such as Cytoscape (Shannon et al., 2003) and Graphviz (Ellson et al., 2004) allow the easy integration of attribute data into sophisticated network plots, but it is challenging to apply them to provide meaningful results in the context of WDSs.VisWaterNet was developed to provide an accessible and multifunctional approach to WDS-specific network visualization.The package is accompanied by clear documentation and code examples in order to facilitate ease of adoption, and can prove to be a helpful tool for researchers and practitioners in the domain of WDS analysis.Users are welcome to further develop, improve and extend these open-source scripts.

Functionality
VisWaterNet extracts WDS characteristics and simulation results from a standardized userprovided input file, i.e., EPANET .INP file (Rossman et al., 2020), using WNTR (Klise et al., 2017), and then constructs a NetworkX (Hagberg et al., 2008) graph on a Matplotlib (Hunter, 2007) figure axis.The hydraulic simulation results are based on the EPANET 2.2 (Rossman et al., 2020) hydraulic engine.The main plotting functions offered by VisWaterNet include: 1. Continuous plotting -users can choose to represent numerical data in a continuous manner, i.e., by assigning nodes or links colors chosen from a color gradient scale.
Figure 1 (left) shows an example of a continuous plot of mean nodal pressure data for network CTown (Ostfeld et al., 2012) generated by VisWaterNet.2. Discrete plotting -users can plot numerical data in a discrete manner, i.e., the data is grouped into intervals and each interval is assigned a single color from a selected color palette.Figure 1 (right) shows an example of a discrete plot generated for the same nodal pressure data shown in Figure 1 (left).
3. Categorical plotting -categorical data, i.e., a property of each node or link that belongs to a fixed set of categories, can also be plotted.This functionality is useful in visualizing node or link attributes that are represented as strings, such as nodal demand pattern names or pipe material, or for numerical attributes that typically take on only a discrete set of values, such as pipe diameter.Figure 2 shows an example of a categorical data plot depicting link diameters in the CTown network.Additionally, VisWaterNet can perform the following functions: 1. Import and visualize custom data generated either in Python scripts or in Excel files.2. Add a second dimension of information to a plot by customizing node markers/sizes and link styles/widths.3. Convert units (e.g., a user can choose to represent length data in units of m, cm, ft, or in). 4. Represent simulation results at a specified time step or summarized throughout the duration (e.g., a user can choose to visualize minimum, maximum, or mean pressure, or pressure at a particular time step).5. Customize the number of intervals or width of intervals for discrete data plots, and hide intervals with no data points.6. Customize the appearance of specific nodes and links.7. Add text labels to specific nodes and links.
VisWaterNet is a practical tool to aid WDS analyses and visualization.Example applications include visualizing different demand areas and pressure zones, highlighting the critical locations in the system, tracking water quality, and visualizing multiple statistics including continuous and categorical values.VisWaterNet scripts are under continuous development and can be further extended and improved by users and developers for specific applications.