.. image:: https://github.com/tylertrimble/viswaternet/blob/main/logo/viswaternet_logo.png?raw=true
:target: https://github.com/tylertrimble/viswaternet/blob/main/logo/viswaternet_logo.png?raw=true
.. image:: https://joss.theoj.org/papers/10.21105/joss.05139/status.svg
:target: https://doi.org/10.21105/joss.05139
.. image:: https://img.shields.io/pypi/v/viswaternet.svg
:target: https://pypi.python.org/pypi/viswaternet
.. image:: https://readthedocs.org/projects/viswaternet/badge/?version=latest
:target: https://viswaternet.readthedocs.io/en/latest/
:alt: Documentation Status
.. image:: https://img.shields.io/pypi/l/ansicolortags.svg
:target: https://pypi.python.org/pypi/ansicolortags/
An open-source Python package for easy generation and customization of water distribution network visualizations. Find the `documentation here`_.
.. _`documentation here`: https://viswaternet.readthedocs.io
Dependencies
------------
â—‰ WNTR â—‰ NetworkX 2.7+ â—‰ Matplotlib 3.5.0+ â—‰ Pandas â—‰ NumPy â—‰ imageio â—‰
VisWaterNet has been tested on Python **3.8** and **3.9**.
Features
--------
VisWaterNet is designed to plot simulation data onto a network graph, with a large variety of customization options available. The package includes the capabilities to:
* Discretize network or simulation data.
* Visualize discretized or continuous data on network graphs.
* Import data from excel files or data generated with Python.
* Create GIFs of data across simulation timesteps.
* Customize style of virtually every element of the network graph, including: reservoirs, tanks, valves, pumps, links, and nodes.
* Draw labels relative to nodes or based on an absolute position on the figure.
* Draw specific nodes or links with their own data and style.
Installation
---------------
To install VisWaterNet, run this command in your terminal:
.. code:: python
pip install viswaternet
Alternatively, the sources for VisWaterNet can be downloaded from the Github repo. You can clone the public repository:
.. code:: python
git clone git://github.com/tylertrimble/viswaternet
Once you have a copy of the source, you can install it with:
.. code:: python
python setup.py install
Getting Started
---------------
To get started, import the VisWaterNet package:
.. code:: python
import viswaternet as vis
Next, initialize a VisWaterNet model. For example purposes, we use the CTown network from `Ostfeld (2016)`_ included in the Examples folder:
.. code:: python
model = vis.VisWNModel('Networks/CTown.inp')
.. _`Ostfeld (2016)`: https://uknowledge.uky.edu/wdst_models/2/
Then, call on any of the plotting functions with the argument inputs of your choice. For example, the following line of code displays the network layout of CTown with each node colored according its mean pressure (in *psi*). This is a **continuous** node plot, where the nodal colors are assigned based a gradient scale:
.. code:: python
model.plot_continuous_nodes(parameter="pressure", value='mean', unit="psi")
.. figure:: logo/readme1.png
:width: 600
:alt: Basic network layout
We can represent the same data in a different way by generating a **discrete** node plot in which mean pressure data is grouped into 4 discrete intervals and node colors are assigned based on the corresponding value shown on a legend:
.. code:: python
model.plot_discrete_nodes(parameter="pressure", value='mean', unit="psi",
legend_loc_2 = 'lower left', intervals = [0,40,80,120],
legend_sig_figs =0)
.. figure:: logo/readme2.png
:width: 600
:alt: Basic network layout
If the plot does not show up after you run the script, it is possible that your IDE does not support interactive plotting (e.g., IDLE) or interactive mode is off. To see the plot, add the following line to display the figures:
.. code:: python
plt.show()
Since several VisWaterNet function arguments rely on Matplotlib visualization inputs, it is recommended to visit the `Matplotlib docs`_ to view customization options for `colors`_, `colorbars`_, `node markers`_, `line styles`_, etc.
.. _`Matplotlib docs`: https://matplotlib.org/stable/index.html
.. _`colors`: https://matplotlib.org/stable/gallery/color/named_colors.html
.. _`colorbars`: https://matplotlib.org/stable/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py
.. _`node markers`: https://matplotlib.org/stable/gallery/lines_bars_and_markers/marker_reference.html
.. _`line styles`: https://matplotlib.org/stable/gallery/lines_bars_and_markers/linestyles.html
More examples that demonstrate the range of VisWaterNet's plotting abilities can be found in the `Example Applications`_ section of the docs.
.. _`Example Applications`: https://viswaternet.readthedocs.io/en/latest/examples.html
Contributing
------------
We welcome contributions in the form of suggestions, feedback, reports of bugs, and additions to code functionality and documentation from all users! You can find instructions to raise issues, submit pull requests, and `run automated tests`_ in the `docs`_ or the `CONTRIBUTING page`_.
.. _`CONTRIBUTING page`: https://github.com/tylertrimble/viswaternet/blob/main/CONTRIBUTING.rst
.. _`docs`: https://viswaternet.readthedocs.io/en/latest/contributing.html
.. _`run automated tests`: https://viswaternet.readthedocs.io/en/latest/contributing.html#testing
Cite Us
-------
To cite VisWaterNet, please use the following publication: `VisWaterNet: A Python package for visualization of water distribution networks`_
.. _`VisWaterNet: A Python package for visualization of water distribution networks`: https://joss.theoj.org/papers/10.21105/joss.05139
::
@article{doi:10.21105/joss.05139,
title={VisWaterNet: A Python package for visualization of water distribution networks},
author={Thomas, Meghna and Trimble, Tyler and Sela, Lina},
journal={Journal of Open Source Software},
volume={8},
number={84},
pages={5139},
year={2023}}
Contact
-------
Tyler Trimble - tylerl.trimble@utexas.edu
Meghna Thomas - meghnathomas@utexas.edu
Lina Sela - linasela@utexas.edu
Credits
-------
This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
=======
History
=======
2.0.0 (2024-04-12)
-----------------------
* Added new label customization options
* Added ability to plot valves as links, and pumps as markers
* Added EPANET icons for pumps, valves, reservoirs, and tanks.
* Renamed, consolidated many arguments for clarity and to reduce # of aruments.
* Removed superfluous arguments.
* Added ability to make discrete legend text color align with interval color.
* Legend label colors can now be changed independently for base legend and discrete legend.
* Title color for discrete legend can now be changed.
* Rewrote code to use data structures more consistently.
* Base links and nodes are now only drawn when necessary when not all nodes/links have data associated with them.
* Added ability to choose to include pump/valve or reservoir/tank data.
* Further improved animate plot speed for excel data plotting
* Animate plot output layout now conforms to normal plotting layout.
* Fixed discrete plotting when empty interval is present.
* Fixed animation issue where color bar label would be cut off.
* Fixed animation of custom data and excel data
* Fixed node size legend not properly showing up
* Fixed case where base elements legend and discrete legend were joined into one legend
* Fixed missing argument passes
* Fixed instances where network elements don't know show up when they should.
1.2.0 (2023-08-01)
------------------
* Overhauled animate_plot function to allow for plotting of custom data and use different file formats
* Plotting custom data now uses new parameter data_file instead of parameter
* Improved initilization time by switching to numpy
* Fixed blank figure appearing before plotting occurs
1.1.0a (2023-03-15)
-------------------
* Fixed colorbar functionality with subplots
* Added ability to customize colorbar size
* Legend/colorbar labels are automatically generated based on parameter/value type
* A default matplotlib figure and axis is created if no axis is specified
* Fixed deprecation issue with matplotlib colormaps
* Updated supported versions of dependecies
* Updated supported python versions
1.0.0 (2023-02-07)
------------------
* Greatly improved animate_plot() function speed
* Fixed numerous bugs related to excel data plotting
* Added ability to use directional arrows with continuous plots
0.1.5 (2023-01-22)
------------------
* Complete documentation
* Fixed animate plot bugs
* Changed how num_interval parameter works
* Fixed warnings
0.1.4 (2022-12-19)
------------------
* Updated requirements
0.1.3 (2022-12-17)
------------------
* Bug fixes
* Some documentation added
0.1.2 (2022-11-11)
------------------
* Rename package once more to avoid confusion with R package 'visnetwork'.
0.1.1 (2022-11-11)
------------------
* Fix import errors due to package name change.
0.1.0 (2022-11-11)
------------------
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/tylertrimble/viswaternet",
"name": "viswaternet",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.10,>=3.8",
"maintainer_email": null,
"keywords": "viswaternet",
"author": "Tyler Trimble",
"author_email": "TylerL.Trimble@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/76/0e/42c0fa9c965306770f99af894f2c7dc31f0171d8f500003a99197dd3d39d/viswaternet-2.0.0.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/tylertrimble/viswaternet/blob/main/logo/viswaternet_logo.png?raw=true\r\n\t\t:target: https://github.com/tylertrimble/viswaternet/blob/main/logo/viswaternet_logo.png?raw=true\r\n\r\n.. image:: https://joss.theoj.org/papers/10.21105/joss.05139/status.svg\r\n :target: https://doi.org/10.21105/joss.05139\r\n\r\n.. image:: https://img.shields.io/pypi/v/viswaternet.svg\r\n :target: https://pypi.python.org/pypi/viswaternet\r\n\r\n.. image:: https://readthedocs.org/projects/viswaternet/badge/?version=latest\r\n :target: https://viswaternet.readthedocs.io/en/latest/\r\n :alt: Documentation Status\r\n\r\n.. image:: https://img.shields.io/pypi/l/ansicolortags.svg\r\n :target: https://pypi.python.org/pypi/ansicolortags/\r\n \r\n\r\nAn open-source Python package for easy generation and customization of water distribution network visualizations. Find the `documentation here`_.\r\n\r\n.. _`documentation here`: https://viswaternet.readthedocs.io\r\n\r\n\r\nDependencies\r\n------------\r\n\u00e2\u2014\u2030 WNTR \u00e2\u2014\u2030 NetworkX 2.7+ \u00e2\u2014\u2030 Matplotlib 3.5.0+ \u00e2\u2014\u2030 Pandas \u00e2\u2014\u2030 NumPy \u00e2\u2014\u2030 imageio \u00e2\u2014\u2030\r\n\r\nVisWaterNet has been tested on Python **3.8** and **3.9**.\r\n\r\nFeatures\r\n--------\r\nVisWaterNet is designed to plot simulation data onto a network graph, with a large variety of customization options available. The package includes the capabilities to:\r\n\r\n* Discretize network or simulation data.\r\n* Visualize discretized or continuous data on network graphs.\r\n* Import data from excel files or data generated with Python.\r\n* Create GIFs of data across simulation timesteps.\r\n* Customize style of virtually every element of the network graph, including: reservoirs, tanks, valves, pumps, links, and nodes.\r\n* Draw labels relative to nodes or based on an absolute position on the figure.\r\n* Draw specific nodes or links with their own data and style.\r\n\r\nInstallation\r\n---------------\r\nTo install VisWaterNet, run this command in your terminal:\r\n\r\n.. code:: python\r\n\r\n pip install viswaternet\r\n \r\nAlternatively, the sources for VisWaterNet can be downloaded from the Github repo. You can clone the public repository:\r\n\r\n.. code:: python\r\n\r\n git clone git://github.com/tylertrimble/viswaternet\r\n\r\nOnce you have a copy of the source, you can install it with:\r\n\r\n.. code:: python\r\n\r\n python setup.py install\r\n\r\nGetting Started\r\n---------------\r\nTo get started, import the VisWaterNet package:\r\n\r\n.. code:: python\r\n\r\n import viswaternet as vis\r\n \r\nNext, initialize a VisWaterNet model. For example purposes, we use the CTown network from `Ostfeld (2016)`_ included in the Examples folder:\r\n\r\n.. code:: python\r\n\r\n model = vis.VisWNModel('Networks/CTown.inp')\r\n\r\n.. _`Ostfeld (2016)`: https://uknowledge.uky.edu/wdst_models/2/\r\n \r\nThen, call on any of the plotting functions with the argument inputs of your choice. For example, the following line of code displays the network layout of CTown with each node colored according its mean pressure (in *psi*). This is a **continuous** node plot, where the nodal colors are assigned based a gradient scale:\r\n\r\n.. code:: python\r\n\r\n model.plot_continuous_nodes(parameter=\"pressure\", value='mean', unit=\"psi\")\r\n \r\n.. figure:: logo/readme1.png\r\n :width: 600\r\n :alt: Basic network layout\r\n\r\nWe can represent the same data in a different way by generating a **discrete** node plot in which mean pressure data is grouped into 4 discrete intervals and node colors are assigned based on the corresponding value shown on a legend:\r\n\r\n.. code:: python\r\n\r\n model.plot_discrete_nodes(parameter=\"pressure\", value='mean', unit=\"psi\",\r\n legend_loc_2 = 'lower left', intervals = [0,40,80,120],\r\n legend_sig_figs =0)\r\n\r\n.. figure:: logo/readme2.png\r\n :width: 600\r\n :alt: Basic network layout\r\n\r\nIf the plot does not show up after you run the script, it is possible that your IDE does not support interactive plotting (e.g., IDLE) or interactive mode is off. To see the plot, add the following line to display the figures: \r\n\r\n.. code:: python\r\n\r\n plt.show()\r\n\r\nSince several VisWaterNet function arguments rely on Matplotlib visualization inputs, it is recommended to visit the `Matplotlib docs`_ to view customization options for `colors`_, `colorbars`_, `node markers`_, `line styles`_, etc.\r\n\r\n.. _`Matplotlib docs`: https://matplotlib.org/stable/index.html\r\n.. _`colors`: https://matplotlib.org/stable/gallery/color/named_colors.html\r\n.. _`colorbars`: https://matplotlib.org/stable/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py\r\n.. _`node markers`: https://matplotlib.org/stable/gallery/lines_bars_and_markers/marker_reference.html\r\n.. _`line styles`: https://matplotlib.org/stable/gallery/lines_bars_and_markers/linestyles.html\r\n\r\nMore examples that demonstrate the range of VisWaterNet's plotting abilities can be found in the `Example Applications`_ section of the docs.\r\n\r\n.. _`Example Applications`: https://viswaternet.readthedocs.io/en/latest/examples.html\r\n\r\nContributing\r\n------------\r\nWe welcome contributions in the form of suggestions, feedback, reports of bugs, and additions to code functionality and documentation from all users! You can find instructions to raise issues, submit pull requests, and `run automated tests`_ in the `docs`_ or the `CONTRIBUTING page`_.\r\n\r\n.. _`CONTRIBUTING page`: https://github.com/tylertrimble/viswaternet/blob/main/CONTRIBUTING.rst\r\n.. _`docs`: https://viswaternet.readthedocs.io/en/latest/contributing.html\r\n.. _`run automated tests`: https://viswaternet.readthedocs.io/en/latest/contributing.html#testing\r\n\r\nCite Us\r\n-------\r\n\r\nTo cite VisWaterNet, please use the following publication: `VisWaterNet: A Python package for visualization of water distribution networks`_\r\n\r\n.. _`VisWaterNet: A Python package for visualization of water distribution networks`: https://joss.theoj.org/papers/10.21105/joss.05139\r\n\r\n::\r\n\r\n @article{doi:10.21105/joss.05139,\r\n title={VisWaterNet: A Python package for visualization of water distribution networks},\r\n author={Thomas, Meghna and Trimble, Tyler and Sela, Lina},\r\n journal={Journal of Open Source Software},\r\n volume={8},\r\n number={84},\r\n pages={5139},\r\n year={2023}}\r\n\r\nContact\r\n-------\r\nTyler Trimble - tylerl.trimble@utexas.edu\r\n\r\nMeghna Thomas - meghnathomas@utexas.edu\r\n\r\nLina Sela - linasela@utexas.edu\r\n\r\nCredits\r\n-------\r\n\r\nThis package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.\r\n\r\n.. _Cookiecutter: https://github.com/audreyr/cookiecutter\r\n.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage\r\n\r\n\r\n=======\r\nHistory\r\n=======\r\n2.0.0 (2024-04-12)\r\n-----------------------\r\n* Added new label customization options\r\n* Added ability to plot valves as links, and pumps as markers\r\n* Added EPANET icons for pumps, valves, reservoirs, and tanks.\r\n* Renamed, consolidated many arguments for clarity and to reduce # of aruments.\r\n* Removed superfluous arguments.\r\n* Added ability to make discrete legend text color align with interval color. \r\n* Legend label colors can now be changed independently for base legend and discrete legend.\r\n* Title color for discrete legend can now be changed.\r\n* Rewrote code to use data structures more consistently.\r\n* Base links and nodes are now only drawn when necessary when not all nodes/links have data associated with them.\r\n* Added ability to choose to include pump/valve or reservoir/tank data.\r\n* Further improved animate plot speed for excel data plotting\r\n* Animate plot output layout now conforms to normal plotting layout.\r\n* Fixed discrete plotting when empty interval is present.\r\n* Fixed animation issue where color bar label would be cut off.\r\n* Fixed animation of custom data and excel data\r\n* Fixed node size legend not properly showing up\r\n* Fixed case where base elements legend and discrete legend were joined into one legend\r\n* Fixed missing argument passes\r\n* Fixed instances where network elements don't know show up when they should.\r\n\r\n1.2.0 (2023-08-01)\r\n------------------\r\n* Overhauled animate_plot function to allow for plotting of custom data and use different file formats\r\n* Plotting custom data now uses new parameter data_file instead of parameter\r\n* Improved initilization time by switching to numpy\r\n* Fixed blank figure appearing before plotting occurs\r\n\r\n1.1.0a (2023-03-15)\r\n-------------------\r\n* Fixed colorbar functionality with subplots\r\n* Added ability to customize colorbar size\r\n* Legend/colorbar labels are automatically generated based on parameter/value type\r\n* A default matplotlib figure and axis is created if no axis is specified\r\n* Fixed deprecation issue with matplotlib colormaps\r\n* Updated supported versions of dependecies\r\n* Updated supported python versions \r\n\r\n1.0.0 (2023-02-07)\r\n------------------\r\n* Greatly improved animate_plot() function speed\r\n* Fixed numerous bugs related to excel data plotting\r\n* Added ability to use directional arrows with continuous plots\r\n\r\n0.1.5 (2023-01-22)\r\n------------------\r\n* Complete documentation\r\n* Fixed animate plot bugs\r\n* Changed how num_interval parameter works\r\n* Fixed warnings\r\n\r\n0.1.4 (2022-12-19)\r\n------------------\r\n* Updated requirements\r\n\r\n0.1.3 (2022-12-17)\r\n------------------\r\n* Bug fixes\r\n* Some documentation added\r\n\r\n0.1.2 (2022-11-11)\r\n------------------\r\n\r\n* Rename package once more to avoid confusion with R package 'visnetwork'.\r\n\r\n0.1.1 (2022-11-11)\r\n------------------\r\n\r\n* Fix import errors due to package name change.\r\n\r\n0.1.0 (2022-11-11)\r\n------------------\r\n\r\n* First release on PyPI.\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "A python package for easy generation and customization of water network graphs.",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/tylertrimble/viswaternet"
},
"split_keywords": [
"viswaternet"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "760e42c0fa9c965306770f99af894f2c7dc31f0171d8f500003a99197dd3d39d",
"md5": "41deacad4f62a00045e8134f038f3c3f",
"sha256": "3953be12910b337edaff050c0d3ab1315b55bb1c26940cde52ccfd0e5d1dd5b6"
},
"downloads": -1,
"filename": "viswaternet-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "41deacad4f62a00045e8134f038f3c3f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.10,>=3.8",
"size": 13978761,
"upload_time": "2024-04-12T23:03:30",
"upload_time_iso_8601": "2024-04-12T23:03:30.611094Z",
"url": "https://files.pythonhosted.org/packages/76/0e/42c0fa9c965306770f99af894f2c7dc31f0171d8f500003a99197dd3d39d/viswaternet-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-12 23:03:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tylertrimble",
"github_project": "viswaternet",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pandas",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.0"
]
]
},
{
"name": "wntr",
"specs": []
},
{
"name": "imageio",
"specs": []
},
{
"name": "imageio-ffmpeg",
"specs": []
},
{
"name": "networkx",
"specs": [
[
">=",
"2.7"
]
]
},
{
"name": "sphinx_rtd_theme",
"specs": []
}
],
"tox": true,
"lcname": "viswaternet"
}
JSON
