Merge pull request #370 from kaklise/docs

Update in snap GIS function to use node name as a tie breaker

documentation/conf.py

@@ -250,14 +250,25 @@ def setup(app):
 
 latex_elements = {
 'printindex': '',
+
+'sphinxsetup': 'hmargin={0.9in,0.9in}, vmargin={0.9in,0.9in}, marginpar=1.0in',
+
 # The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+'papersize': 'letterpaper',
 
 # The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+'pointsize': '10pt',
 
 # Additional stuff for the LaTeX preamble.
-#'preamble':  '''%
+'preamble':  r'''
+\usepackage{tcolorbox}
+\definecolor{sphinxnoteBgColor}{RGB}{221,233,239}
+\renewenvironment{sphinxnote}[1]
+{\begin{tcolorbox}[colback=sphinxnoteBgColor,
+colframe=red!35!green!50!blue!87!,
+title=\sphinxstrong{#1}]}
+{\end{tcolorbox}}
+''',
 #  \usepackage[nottoc]{tocbibind}
 #  \pagestyle{plain}
 #  \pagenumbering{gobble}
@@ -266,7 +277,8 @@ def setup(app):
 #''',
 
 # Latex figure (float) alignment
-#'figure_align': 'htbp',
+'figure_align': 'htbp',
+
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

documentation/fragility.rst

@@ -62,7 +62,7 @@ of exceeding the Minor damage state is 0.80.
 
 .. _fig-fragility:
 .. figure:: figures/fragility_curve.png
-   :width: 800
+   :width: 640
    :alt: Fragility curve
 
    Example fragility curve.

documentation/getting_started.rst

@@ -49,7 +49,6 @@ Example files can be run as follows:
 
 * Open the example file within an IDE like Spyder and run or step through the file. 
 
-
 Example Files
 -----------------------
 
@@ -64,7 +63,11 @@ WNTR comes with Python code examples that illustrate advanced use cases, includi
 * `Sensor placement example <https://github.com/sandialabs/chama/blob/main/examples/water_network_example.py>`_: 
   This example is hosted in Chama repository (https://github.com/sandialabs/chama) and uses WNTR to optimize the placement of sensors that minimizes detection time. 
   Note that Chama requires Pyomo and a MIP solver, see Chama installation instructions for more details.
-
+
+For example, to run the pipe criticality example, run the following command::
+	
+	python -i pipe_criticality.py
+
 Additionally, the examples folder contains demonstrations using Jupyter Notebooks. 
 A Jupyter Notebook, an open-sourced web-based application, can be accessed through Anaconda or by installing the 
 associated software available at https://jupyter.org. These demonstrations include the following: 
@@ -79,11 +82,18 @@ associated software available at https://jupyter.org. These demonstrations inclu
   This demonstration runs multiple hydraulic simulations with and without fire fighting flow demand to multiple fire hydrant nodes. 
   It also plots the pressure and population impacts for junctions affected by the additional fire fighting flow demand. 
 * `Earthquake demo <https://github.com/USEPA/WNTR/blob/main/examples/demos/earthquake_demo.ipynb>`_: 
-  This demostration runs hydraulic simulations of earthquake damage with and without repair efforts. It plots fragility curves, 
+  This demonstration runs hydraulic simulations of earthquake damage with and without repair efforts. It plots fragility curves, 
   peak ground acceleration, peak ground velocity, repair rate, leak probability, and damage states. In addition, it compares 
   junction pressure 24 hours into the simulation, and tank and junction pressure over time. The demonstration also plots water 
   service availability and population impacted by low pressure conditions.
-
+
+For example, to open the pipe break demo using Jupyter, run the following command::
+	
+	jupyter notebook pipe_break_demo.ipynb
+	
+The Jupyter Notebook will open in a browser (e.g., Chrome, Firefox) and the example can be run using 'Run' button.  
+Additional information on Jupyter Notebooks is available at https://jupyter.org.
+
 For more details about the steps in the demonstrations, review Chapter 12: Water network tool for resilience in 
 `Embracing Analytics in the Drinking Water Industry <https://iwaponline.com/ebooks/book/849/Embracing-Analytics-in-the-Drinking-Water-Industry>`_. 
 

documentation/gis.rst

@@ -134,17 +134,17 @@ Attributes
 
     The following example adds the simulated pressure at hour 1 to the water network GIS data 
     (which includes pressure at junctions, tanks, and reservoirs).
-
+    
     .. doctest::
        :skipif: gpd is None
-	   
+
         >>> sim = wntr.sim.EpanetSimulator(wn)
         >>> results = sim.run_sim()
-    	>>> wn_gis.add_node_attributes(results.node['pressure'].loc[3600,:], 
+        >>> wn_gis.add_node_attributes(results.node['pressure'].loc[3600,:], 
     	...     'Pressure_1hr')
-
+    
     Attributes can also be added directly to individual GeoDataFrames, as shown below.
-
+    
     .. doctest::
        :skipif: gpd is None
 
@@ -410,7 +410,8 @@ the hydrants snapped to the junctions in Net1.
     :skipif: gpd is None
 
     >>> ax = hydrant_data.plot()
-    >>> ax = wntr.graphics.plot_network(wn, node_attribute=snapped_to_junctions['node'].to_list(), ax=ax)
+    >>> ax = wntr.graphics.plot_network(wn, 
+    ...     node_attribute=snapped_to_junctions['node'].to_list(), ax=ax)
 
 .. doctest::
     :skipif: gpd is None
@@ -422,7 +423,7 @@ the hydrants snapped to the junctions in Net1.
 
 .. _fig-snap-points:
 .. figure:: figures/snap_points.png
-   :width: 800
+   :width: 640
    :alt: Hydrants snapped to junctions in EPANET example Net1 using the snapped points to points function
 
    Net1 with example hydrants snapped to junctions, in which the larger blue circles are the hydrant locations and the smaller red circles are the associated junctions.
@@ -506,7 +507,7 @@ illustrates the valve layer created by snapping points to lines in Net1.
 
 .. _fig-snap-lines:
 .. figure:: figures/snap_lines.png
-   :width: 600
+   :width: 640
    :alt: Isolation valves snapped to pipes in EPANET example Net1 using the snapped points to lines function
 
    Net1 with example valve layer created by snapping points to lines, in which the blue circles are the isolation valve locations 
@@ -597,7 +598,8 @@ The pipes are colored based upon their maximum earthquake probability.
 
     >>> ax = earthquake_data.plot(column='Pr', alpha=0.5, cmap='bone', vmin=0, vmax=1)
     >>> ax = wntr.graphics.plot_network(wn, link_attribute=pipe_Pr['max'], link_width=1.5, 
-    ...     node_range=[0,1], link_range=[0,1], ax=ax, link_colorbar_label='Earthquake Probability')
+    ...     node_range=[0,1], link_range=[0,1], ax=ax, 
+    ...     link_colorbar_label='Earthquake Probability')
 
 .. doctest::
     :skipif: gpd is None
@@ -609,7 +611,7 @@ The pipes are colored based upon their maximum earthquake probability.
 
 .. _fig-intersect-earthquake:
 .. figure:: figures/intersect_earthquake.png
-   :width: 800
+   :width: 640
    :alt: Intersection of pipes with earthquake fault lines in EPANET example Net1
 
    Net1 with example earthquake fault lines intersected with pipes, which are colored based upon their maximum earthquake probability.  
@@ -680,7 +682,8 @@ The pipes are colored based upon their weighted mean landslide probability.
 
     >>> ax = landslide_data.plot(column='Pr', alpha=0.5, cmap='bone', vmin=0, vmax=1)
     >>> ax = wntr.graphics.plot_network(wn, link_attribute=pipe_Pr['weighted_mean'], 
-    ...     link_width=1.5, node_range=[0,1], link_range=[0,1], ax=ax, link_colorbar_label='Landslide Probability')
+    ...     link_width=1.5, node_range=[0,1], link_range=[0,1], ax=ax, 
+    ...     link_colorbar_label='Landslide Probability')
 
 .. doctest::
     :skipif: gpd is None
@@ -692,7 +695,7 @@ The pipes are colored based upon their weighted mean landslide probability.
 
 .. _fig-intersect-landslide:
 .. figure:: figures/intersect_landslide.png
-   :width: 800
+   :width: 640
    :alt: Intersection of junctions with landslide zones in EPANET example Net1
 
    Net1 with example landslide zones intersected with pipes, which are colored based upon their weighted mean landslide probability. 
@@ -800,7 +803,7 @@ the census tracts (polygons) is different than the junction and pipe attributes.
 
 .. _fig-intersect-demographics:
 .. figure:: figures/intersect_demographics.png
-   :width: 800
+   :width: 640
    :alt: Intersection of junctions and pipes with mean income demographic data in EPANET example Net1
 
    Net1 with mean income demographic data intersected with junctions and pipes.

documentation/graphics.rst

@@ -91,7 +91,7 @@ The following example plots the network along with node population (:numref:`fig
 
 .. _fig-plotly:
 .. figure:: figures/plot_plotly_network.png
-   :width: 715
+   :width: 640
    :alt: Network
 
    Interactive network graphic with the legend showing the node population.
@@ -152,7 +152,8 @@ when mapping colors to ``node_attribute`` values.
     >>> sim = wntr.sim.EpanetSimulator(wn)
     >>> results = sim.run_sim()
     >>> water_age = results.node['quality']/3600 # convert seconds to hours
-    >>> anim = wntr.graphics.network_animation(wn, node_attribute=water_age, node_range=[0,24]) # doctest: +SKIP
+    >>> anim = wntr.graphics.network_animation(wn, node_attribute=water_age, 
+    ...     node_range=[0,24]) # doctest: +SKIP
 
 Time series
 ------------------
@@ -243,7 +244,7 @@ The following example plots a fragility curve with two states (:numref:`fig-frag
 
 .. _fig-fragility2:
 .. figure:: figures/fragility_curve.png
-   :width: 800
+   :width: 640
    :alt: Fragility curve
 
    Fragility curve graphic.
@@ -275,7 +276,7 @@ The following example plots a pump curve (:numref:`fig-pump`).
 
 .. _fig-pump:
 .. figure:: figures/plot_pump_curve.png
-   :width: 800
+   :width: 640
    :alt: Pump curve
 
    Pump curve graphic.
@@ -364,7 +365,7 @@ The valves and valve segments are plotted on the network (:numref:`fig-valve_seg
 
 .. _fig-valve_segment:
 .. figure:: figures/plot_valve_segment.png
-   :width: 800
+   :width: 640
    :alt: Valve segment attributes
 
    Valves layer and segments.
@@ -391,7 +392,7 @@ valves surrounding each valve is plotted on the network
 
 .. _fig-valve_segment_attributes:
 .. figure:: figures/plot_valve_segment_attributes.png
-   :width: 800
+   :width: 640
    :alt: Valve segment attributes
 
    Valve segment attribute showing the number of valves surrounding each valve.

documentation/layers.rst

@@ -83,7 +83,7 @@ The valve layer can be included in water network graphics (:numref:`fig-random-v
 
 .. _fig-random-valve-layer:
 .. figure:: figures/random_valve_layer.png
-   :width: 500
+   :width: 640
    :alt: Valve layer
 
    Valve layer using random placement.
@@ -107,7 +107,7 @@ The valve layer can be included in water network graphics (:numref:`fig-strategi
 
 .. _fig-strategic-valve-layer:
 .. figure:: figures/strategic_valve_layer.png
-   :width: 500
+   :width: 640
    :alt: Valve layer
 
    Valve layer using strategic N-2 placement.

documentation/resilience.rst

@@ -230,8 +230,8 @@ use NetworkX directly, while others use metrics included in WNTR.
 
       >>> average_expected_demand = wntr.metrics.average_expected_demand(wn)
       >>> link_lengths = wn.query_link_attribute('length')
-      >>> valve_attributes = wntr.metrics.valve_segment_attributes(valve_layer, node_segments, 
-      ...     link_segments, average_expected_demand, link_lengths)
+      >>> valve_attributes = wntr.metrics.valve_segment_attributes(valve_layer, 
+      ...     node_segments, link_segments, average_expected_demand, link_lengths)
 
 ..
 	Clustering coefficient: Clustering coefficient is the ratio between the total number of triangles and 

wntr/gis/geospatial.py

@@ -98,7 +98,7 @@ def snap(A, B, tolerance):
     closest = closest[closest['snap_distance'] <= tolerance]
 
     # Sort on ascending snap distance, so that closest goes to top
-    closest = closest.sort_values(by=["snap_distance"]) 
+    closest = closest.sort_values(by=["snap_distance", "indexB"]) 
 
     # group by the index of the points and take the first, which is the closest line
     closest = closest.groupby("point").first()      

wntr/tests/test_gis.py

@@ -259,7 +259,7 @@ def test_snap_points_to_lines(self):
 
         # distance = 1,5,3
         expected = pd.DataFrame([{'link': '12', 'node': '12', 'snap_distance': 1, 'line_position': 0.1, 'geometry': Point([52.0,70.0])},
-                                 {'link':  '22', 'node': '23', 'snap_distance': 5.0, 'line_position': 1.0, 'geometry': Point([70.0,40.0])},
+                                 {'link': '113', 'node': '23', 'snap_distance': 5.0, 'line_position': 1.0, 'geometry': Point([70.0,40.0])},
                                  {'link': '121', 'node': '21', 'snap_distance': 3.0, 'line_position': 0.1, 'geometry': Point([30.0,37.0])}])
 
         assert_frame_equal(pd.DataFrame(snapped_points), expected, check_dtype=False)