Documentation updates (#470)

kaklise · web-flow · commit 2d96cd0b0e24 · 2025-01-31T12:51:34.000-08:00
* Updated geospatial demo

* Update copyright year

* Updated docs

* updated version for upload-pages-artifact
diff --git a/LICENSE.md b/LICENSE.md
@@ -1,7 +1,7 @@
 Copyright Notice
 =================
 
-Copyright 2023 National Technology & Engineering Solutions of Sandia, LLC 
+Copyright 2024 National Technology & Engineering Solutions of Sandia, LLC 
 (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the U.S. 
 Government retains certain rights in this software.
 
diff --git a/documentation/conf.py b/documentation/conf.py
@@ -108,7 +108,7 @@
 
 # General information about the project.
 project = u'WNTR'
-copyright = u'2023 National Technology & Engineering Solutions of Sandia, LLC (NTESS)'
+copyright = u'2024 National Technology & Engineering Solutions of Sandia, LLC (NTESS)'
 author = u'WNTR Developers'
 
 bibtex_bibfiles = ['references.bib', 'citations.bib']
diff --git a/documentation/gis.rst b/documentation/gis.rst
@@ -243,7 +243,7 @@ WNTR to add attributes to the water network model and analysis. Examples of thes
   These geometries can be associated with points and lines in a water network model by snapping the point to the nearest component.
 * **LineString or MultiLineString geometries** that could contain street layout or earthquake fault lines.
   These geometries can be associated with points and lines in a water network model by finding the intersection.
-* **Polygon geometries** that could contain elevation, building footprints, zoning, land cover, hazard maps, census data, demographics, or social vulnerability.
+* **Polygon geometries** that could contain elevation, building footprints, zoning, land cover, hazard maps, census data, or demographics.
   These geometries can be associated with points and lines in a water network model by finding the intersection.
 
 The snap and intersect examples below used additional GIS data stored in the 
@@ -537,7 +537,7 @@ Find the intersect between geometries
 
 The :class:`~wntr.gis.geospatial.intersect`  function is used to find the intersection between geometries.
 This functionality can be used to identify faults, landslides, or other hazards that intersect pipes,
-or assign community resilience indicators (e.g., population characteristics, economic), future climate projections, hazards/risks, or other data to network components.
+or assign community resilience indicators (e.g., population characteristics, economic), hazards/risks, or other data to network components.
 
 When finding the intersection of GeoDataFrame A with GeoDataFrame B (where A and B can contain points, lines, or polygons),
 the function returns the following information (one entry for each geometry in A):
@@ -740,7 +740,7 @@ Assign demographic data to pipes and junctions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 GIS data that includes community resilience indicators (e.g., population characteristics, economic data), 
-future climate projections, hazards/risks, or other data can be used to identify 
+hazards/risks, or other data can be used to identify 
 the effects of disasters to different portions of the community, which can help utilities to improve equitable resilience. 
 The following example highlights the process to assign demographic data to pipes and junctions. The demographic example dataset 
 is a GeoDataFrame with a `geometry` column that contains ``shapely.geometry.Polygon`` geometries along with 
@@ -835,7 +835,7 @@ Sample raster at points geometries
 
 The :class:`~wntr.gis.sample_raster` function can be used to sample a raster file at point geometries,
 such as the nodes of a water network. A common use case for this function is to assign elevation to the 
-nodes of a water network model, however other geospatial information such as climate or hazard data could be sampled 
+nodes of a water network model, however other geospatial information such as hazard data could be sampled 
 using this function.
 
 The network file, Net1.inp, in EPSG:4326 CRS is used in the example below. 
diff --git a/documentation/license.rst b/documentation/license.rst
@@ -17,7 +17,7 @@ Copyright
 ------------
 .. code-block:: none 
 
-   Copyright 2023 National Technology & Engineering Solutions of Sandia, 
+   Copyright 2024 National Technology & Engineering Solutions of Sandia, 
    LLC (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the U.S. 
    Government retains certain rights in this software.
 
diff --git a/examples/data/ky10_svi_data.geojson b/examples/data/ky10_svi_data.geojson
diff --git a/examples/demos/geospatial_demo.ipynb b/examples/demos/geospatial_demo.ipynb
@@ -8,11 +8,10 @@
    },
    "source": [
     "# WNTR Geospatial Tutorial\n",
-    "The following tutorial illustrates the use of the `wntr.gis` module to use geospatial data in resilience analysis.  The objective of this tutorial is to 1) quantify water service disruptions that could occur from pipes damaged in landslides and 2) identify the social vulnerability of populations impacted by the service disruptions.\n",
+    "The following tutorial illustrates the use of the `wntr.gis` module to use geospatial data in resilience analysis.  The objective of this tutorial is to 1) quantify water service disruptions that could occur from pipes damaged in landslides and 2) identify population impacted by the service disruptions.\n",
     "\n",
     "To simplify the tutorials, it is assumed that pipes within a 1000 ft buffer of each landslide susceptible region are damaged in that landslide.\n",
-    "This assumption could be replaced with detailed landslide analysis that includes slope, soil type, weather conditions, and pipe material.\n",
-    "Social vulnerability data could also be replaced by datasets that describe other attributes of the population and critical services."
+    "This assumption could be replaced with detailed landslide analysis that includes slope, soil type, weather conditions, and pipe material."
    ]
   },
   {
@@ -233,7 +232,7 @@
    "metadata": {},
    "source": [
     "# External GIS Data\n",
-    "The external data used in this tutorial includes landslide inventory and social vulnerability data."
+    "External landslide inventory data is used in this tutorial."
    ]
   },
   {
@@ -303,73 +302,6 @@
     "tmp = ax.set_ylim(zoom_coords[1])"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Load Social Vulnerability Index (SVI) GIS data\n",
-    "The social vulnerability data used in this tutorial was downloaded from the [Centers for Disease Control and Prevention/Agency for Toxic Substances and Disease Registry](https://www.atsdr.cdc.gov/placeandhealth/svi/index.html). The data contains census and social vulnerability metrics for each census tract. \n",
-    "\n",
-    "The quantity of interest used in this analysis is `RPL_THEMES` which ranks vulnerability across socioeconomic status, household characteristics, racial and ethnic minority status, and housing type and transportation.  The value ranges between 0 and 1, where higher values are associated with higher vulnerability.\n",
-    "\n",
-    "*Citation: Centers for Disease Control and Prevention/Agency for Toxic Substances and Disease Registry/Geospatial Research, Analysis, and Services Program. CDC/ATSDR Social Vulnerability Index 2020 Database Kentucky. https://www.atsdr.cdc.gov/placeandhealth/svi/data_documentation_download.html. Accessed on 4/4/2024.*"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": []
-   },
-   "outputs": [],
-   "source": [
-    "# To reduce the file size checked into the WNTR repository, the following code was run on the raw data file. \n",
-    "# The region of interest (ROI) was defined above.\n",
-    "\"\"\"\n",
-    "svi_file = '../data/SVI2020_KENTUCKY_tract.gdb'\n",
-    "svi_data = gpd.read_file(svi_file, driver=\"FileGDB\", layer='SVI2020_KENTUCKY_tract')\n",
-    "print(svi_data.crs)\n",
-    "svi_data.to_crs(crs, inplace=True)\n",
-    "svi_data = svi_data.clip(ROI)\n",
-    "svi_data.to_file(\"../data/ky10_svi_data.geojson\", index=True, driver='GeoJSON')\n",
-    "\"\"\""
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": []
-   },
-   "outputs": [],
-   "source": [
-    "# Load the SVI data from file and print the CRS to ensure it is in EPSG:3089.  \n",
-    "# The methods `to_crs` and `set_crs` can be used to change coordinate reference systems if needed.\n",
-    "svi_file = '../data/ky10_svi_data.geojson'\n",
-    "svi_data = gpd.read_file(svi_file).set_index('index') \n",
-    "print(svi_data.crs)\n",
-    "\n",
-    "svi_data.head()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": []
-   },
-   "outputs": [],
-   "source": [
-    "# Plot SVI data and pipes (higher values of SVI are associated with higher vulnerability)\n",
-    "ax = svi_data.plot(column='RPL_THEMES', label='SVI data', cmap='RdYlGn_r', vmin=0, vmax=1, legend=True)\n",
-    "ax = wn_gis.pipes.plot(color='black', linewidth=1, ax=ax)\n",
-    "ax.set_title('SVI and pipe data')\n",
-    "tmp = ax.axis('off')\n",
-    "# Comment/uncomment the following 2 lines to change the zoom on the network graphic\n",
-    "tmp = ax.set_xlim(zoom_coords[0])\n",
-    "tmp = ax.set_ylim(zoom_coords[1])"
-   ]
-  },
   {
    "attachments": {},
    "cell_type": "markdown",
@@ -428,7 +360,7 @@
    "metadata": {},
    "source": [
     "# Geospatial Intersects\n",
-    "In this section, landslide scenario and SVI data are interested with pipes and junctions in the `WaterNetworkModel`."
+    "In this section, landslide scenario data are interested with pipes and junctions in the `WaterNetworkModel`."
    ]
   },
   {
@@ -556,73 +488,6 @@
     "tmp = ax.set_ylim(zoom_coords[1])"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Assign social vulnerability to each junction\n",
-    "Junctions are intersected with SVI to determine the social vulnerability of the population at each junction.  The SVI data attribute `RPL_THEMES` is included in the intersection. <font color='red'>This information is used to determine the social vulnerability of individuals that experience water service disruptions.</font>\n",
-    "\n",
-    "The SVI data column `RPL_THEMES` ranks vulnerability across socioeconomic status, household characteristics, racial and ethnic minority status, and housing type and transportation. The value ranges between 0 and 1, where higher values are associated with higher vulnerability.\n",
-    "\n",
-    "**Note that since each junction only intersects one census tract, the SVI sum, min, max, and mean are all the same value.**"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": []
-   },
-   "outputs": [],
-   "source": [
-    "# Use the intersect function to determine SVI of each junction.  \n",
-    "A = wn_gis.junctions\n",
-    "B = svi_data\n",
-    "B_value = 'RPL_THEMES'\n",
-    "junction_svi = wntr.gis.intersect(A, B, B_value)\n",
-    "\n",
-    "junction_svi.head()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Add the intersection results (SVI value) to the GIS junction data\n",
-    "wn_gis.junctions['RPL_THEMES'] = junction_svi['mean']"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": []
-   },
-   "outputs": [],
-   "source": [
-    "# Plot SVI for each census tract and SVI assigned to each junction\n",
-    "fig, axes = plt.subplots(1,2, figsize=(15,5))\n",
-    "\n",
-    "svi_data.plot(column='RPL_THEMES', label='SVI data', vmin=0, vmax=1, legend=True, ax=axes[0])\n",
-    "wn_gis.pipes.plot(color='black', linewidth=1, ax=axes[0])\n",
-    "tmp = axes[0].set_title('Census tract SVI and pipe data')\n",
-    "tmp = axes[0].axis('off')\n",
-    "# Comment/uncomment the following 2 lines to change the zoom on the network graphic\n",
-    "tmp = axes[0].set_xlim(zoom_coords[0])\n",
-    "tmp = axes[0].set_ylim(zoom_coords[1])\n",
-    "\n",
-    "wn_gis.pipes.plot(color='gray', linewidth=1, ax=axes[1])\n",
-    "wn_gis.junctions.plot(column='RPL_THEMES', vmin=0, vmax=1, legend=True, ax=axes[1])\n",
-    "tmp = axes[1].set_title('SVI value at each junction')\n",
-    "tmp = axes[1].axis('off')\n",
-    "# Comment/uncomment the following 2 lines to change the zoom on the network graphic\n",
-    "tmp = axes[1].set_xlim(zoom_coords[0])\n",
-    "tmp = axes[1].set_ylim(zoom_coords[1])"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {
@@ -774,7 +639,7 @@
    },
    "source": [
     "# Analysis Results\n",
-    "The following section computes and plots analysis results, including water service availability (WSA) and the social vulnerability index (SVI) of impacted junctions for each scenario."
+    "The following section computes and plots analysis results, including water service availability (WSA) of impacted junctions for each scenario."
    ]
   },
   {
@@ -921,7 +786,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## SVI of impacted junctions\n",
+    "## WSA of impacted junctions\n",
     "In this analysis, impacted junctions are defined as junctions where WSA falls below 0.5 (50% of the expected water was received) at any time during the simulation. Other criteria could also be used to defined impact."
    ]
   },
@@ -943,19 +808,21 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
-    "# Plot SVI of impacted junctions for each scenario\n",
+    "# Plot WSA of impacted junctions for each scenario\n",
     "fig, axes = plt.subplots(2,3, figsize=(15,10))\n",
     "axes = axes.flatten()\n",
     "\n",
     "for i, scenario in enumerate(wsa_results.columns):\n",
     "    j = impacted_junctions[scenario]\n",
     "    wn_gis.pipes.plot(color='gray', linewidth=1, alpha=0.5, ax=axes[i]) # pipes\n",
     "    if len(j) > 0:\n",
-    "        wn_gis.junctions.loc[j,:].plot(column='RPL_THEMES', cmap='RdYlGn_r', vmin=0, vmax=1, legend=True, ax=axes[i]) # junction wsa\n",
-    "    tmp = axes[i].set_title('SVI '+scenario)\n",
+    "        wn_gis.junctions.loc[j,:].plot(column=scenario, cmap='RdYlGn', vmin=0, vmax=1, legend=True, ax=axes[i]) # junction wsa\n",
+    "    tmp = axes[i].set_title('WSA '+scenario)\n",
     "    tmp = axes[i].axis('off')\n",
     "    if i >= 6: # axes is defined to have 6 subplots\n",
     "        break"
