Geospatial Analytics for Multisector Urban Teleconnections

Description

gamut is a tool for exploring teleconnections between cities of the United States and human activities that occur in their associated water supply catchments. A teleconnection is a causal connection or correlation between human and environmental phenomena that occur a long distance apart.

Get Started with gamut

gamut can be installed remotely from the repository using the R devtools package. From an R prompt, run the command:

install.packages("devtools")
library(devtools)
devtools::install_github('IMMM-SFA/gamut')
library(gamut)

If you run into problems with the remote installation, you may also try these other options to install gamut:

  1. Save the package file by clicking here, then run install_local() as shown below:
install_local('path/to/package')
  1. Clone the repo to your computer using git clone "https://github.com/IMMM-SFA/gamut". You can then load this project into your RStudio and install it.

NOTE: Depending on your version of R, you may need to install Rtools to retrieve the package. If you have trouble installing it with install.packages("Rtools"), you can find the install file here. Depending on your version of sf, also may need to install the package Rcpp in order for gamut to build correctly.

Data Files

To download all of the gamut input datasets, visit the Zenodo data repository and download the zipped data files to your preferred directory. Make sure to combine the energy, land, misc, and water folders into a single directory. The table below shows all the files used within the gamut software package.

gamut Name Sub Folder Location Full File Path Data Source
watersheds water water/CWM_v2_2/World_Watershed8.shp https://knb.ecoinformatics.org/view/doi%3A10.5063%2FF1J67DWR
withdrawal water water/CWM_v2_2/Snapped_Withdrawal_Points.shp https://knb.ecoinformatics.org/view/doi%3A10.5063%2FF1J67DWR
citypoint water water/CWM_v2_2/City_Centroid.shp https://knb.ecoinformatics.org/view/doi%3A10.5063%2FF1J67DWR
powerplants water water/UCS-EW3-Energy-Water-Database.xlsx https://www.ucsusa.org/resources/ucs-ew3-energy-water-database
crop land land/2016_90m_cdls/cdl_lowres_usa.img https://www.nass.usda.gov/Research_and_Science/Cropland/Release/
crop_attributes land land/2016_90m_cdls/cdl_lowres_usa.img.vat.dbf https://www.nass.usda.gov/Research_and_Science/Cropland/Release/
irrigation land land/Version2_USA_Demeter.csv GCAM Demeter Data
nlud land land/usa_nlud_LR.tif https://drive.google.com/file/d/1vmNfwjcaLf0sZTYJ1wsB3liG37sN8gyC/view
hydro energy energy/EHA_Public_PlantFY2019_GIS_6/ORNL_EHAHydroPlant_FY2020revised.xlsx https://hydrosource.ornl.gov/node/250
climate land land/kop_climate_classes.tif http://koeppen-geiger.vu-wien.ac.at/present.htm
HUC4 water water/USA_HUC4/huc4_to_huc2.shp http://prd-tnm.s3-website-us-west-2.amazonaws.com/?prefix=StagedProducts/Hydrography/WBD/National/GDB/
population land land/pden2010_block/pden2010_60m.tif https://www.sciencebase.gov/catalog/item/57753ebee4b07dd077c70868
runoff water water/UWSCatCH/Historical_Mean_Runoff/USA_Mean_Runoff.tif https://zenodo.org/record/4315195
nhd_flow water water/UWSCatCH/Watershed_Flow_Contributions/UWB_Intake_Flows.shp https://zenodo.org/record/4315195
contributions water water/UWSCatCH/Watershed_Flow_Contributions/Watershed_Contributions.csv https://zenodo.org/record/4315195

Usage

Once all the necessary data is organized in the correct format, the package is ready to be used. The main function is count_watershed_teleconnections. Within this function, set up your data directory and select cities. The city names need to be in the format of City | State, and for multiple cities, place them inside c(). Available cities can be found on the Available Cities wiki page.

Here is an example of what you would type into your console:

count_watershed_teleconnections(data_dir = "your/gamut/data_dir", cities = c("Portland | OR", "Knoxville | TN", "New York | NY", "Indianapolis | IN", "Seattle | WA"))

The package will cycle through each city and their respective watersheds, and produce a table with several columns of information. To learn what each of these variables mean, scroll to the bottom of this section and see the table of variables. The result of this function will look something like this:

city city_population n_watersheds n_other_cities dependent_city_pop watershed_area_sqkm storage_BCM yield_BCM irr_cons_BCM n_climate_zones n_hydro_plants n_thermal_plants n_fac_agcrop n_fac_aglivestock n_fac_cnsmnf n_fac_mining n_fac_oilgas n_fac_total hydro_gen_MWh thermal_gen_MWh thermal_cons_BCM thermal_with_BCM n_utilities n_ba n_crop_classes cropland_fraction developed_fraction ag_runoff_max ag_runoff_av_exgw ag_runoff_av dev_runoff_max dev_runoff_av_exgw dev_runoff_av np_runoff_max np_runoff_av_exgw np_runoff_av_exgw_unweighted np_runoff_av n_economic_sectors max_withdr_dist_km avg_withdr_dis_km n_treatment_plants watershed_pop pop_cons_m3sec av_fl_sur_conc_pct av_fl_sur_conc_pct_unweighted av_ro_sur_conc_pct av_fl_all_conc_pct av_ro_all_conc_pct av_fl_max_conc_pct av_ro_max_conc_pct surface_contribution_pct importance_of_worst_watershed_pct
Portland | OR 653115 1 1 653115 280.7526 0.0970009 0.0930801 0.0000000 1 1 0 0 0 0 0 0 0 55263.24 0.0 0.0000000 0.0000000 0 0 0 0.0000000 0.0044529 0.0000000 0.0000000 0.0000000 0.0000172 0.0000172 0.0000172 0.0000172 0.0000172 0.0000172 0.0000172 4 40.923236 40.923236 0 1.963243e+01 0.0000454 0.0000000 0.0000000 0.0000000 0.0000000 0.0000000 0.000000 0.000000 100 100
Knoxville | TN 187500 1 2 159230 23196.0276 5.1667173 0.2792402 0.0132724 2 13 4 0 7 149 20 0 569 1633153.23 8595013.6 0.0105083 0.9841422 4 4 7 0.0392887 0.1217025 0.0017350 0.0017350 0.0017350 0.0187317 0.0187317 0.0187317 0.0204667 0.0204667 0.0204667 0.0204667 13 5.942854 5.942854 0 1.559519e+06 3.6100047 1.4421179 1.4421179 1.7276066 1.4421179 1.7276066 1.442118 1.727607 100 100
New York | NY 8398748 8 1 8398748 5203.8799 2.3480124 0.7446405 0.0046190 3 5 0 0 3 45 7 0 377 155873.63 0.0 0.0000000 0.0000000 0 0 7 0.0473016 0.0822482 0.0207107 0.0034037 0.0034037 0.3966929 0.0263228 0.0263228 0.3966933 0.0297265 0.0667699 0.0297265 13 191.509637 130.711473 0 2.566443e+05 0.5940853 0.1757086 0.3212001 0.1946581 0.1757086 0.1946581 1.363024 1.150314 100 5
Indianapolis | IN 867125 2 1 867125 4564.3384 0.1120111 0.1861601 0.0085113 2 0 2 0 3 226 17 0 2590 0.00 184897.6 0.0001779 0.0002461 2 1 7 0.6037272 0.2275309 0.8135638 0.7875826 0.6536936 0.1440485 0.1319367 0.1095075 0.9432512 0.9195193 0.8674918 0.7632010 11 13.022947 7.316844 0 9.299683e+05 2.1527092 5.8410899 5.9615696 5.1381545 4.8481046 4.2646682 6.137005 5.636823 83 13
Seattle | WA 744955 2 1 744955 400.0307 0.2083348 0.1861601 0.0000000 2 1 0 0 0 0 0 0 0 74449.12 0.0 0.0000000 0.0000000 0 0 1 0.0000223 0.0760191 0.0000000 0.0000000 0.0000000 0.0066085 0.0059192 0.0059192 0.0066085 0.0059192 0.0054596 0.0059192 7 48.461821 42.872284 0 1.245807e+03 0.0028838 0.0000000 0.0000000 0.0000000 0.0000000 0.0000000 0.000000 0.000000 100 70

This table can be used to compare different variables between multiple cities. Below is a graph comparing how much developed land are in cities’ watersheds.

The table below shows explanations for each of these variables that are created through this function:

Variable Name Description Units
city_population The population of the city being analyzed people
n_watersheds Number of watersheds that city uses to source drinking water watersheds
n_other_cities Number of other cities pulling off the same watersheds cities
dependent_city_pop Total population of people dependent on that city’s watersheds people
watershed_area_sqkm Combined area of all the source watersheds of a city square kilometers
storage_BCM Combined storage capacity of all the city catchments billion cubic meters
yield_BCM Combined yield capacity of all the city catchments billion cubic meters
irr_cons_BCM Combined water consumption that is used for irrigation with the watersheds billion cubic meters
n_climate_zones Number of climate zones that the source watersheds cover zones
n_hydro_plants Number of hydroelectric power plants operating within the source watersheds plants
n_thermal_plants Number of thermal power plants operating within the source watersheds plants
n_fac_agcrop Number of agricultural crop facilities within the source watersheds facilities
n_fac_aglivestock Number of agicultural livestock facilities within the source watersheds facilities
n_fac_cnsmnf Number of construction and manufacturing facilities within the source watersheds facilities
n_fac_mining Number of mining facilities within the source watersheds facilities
n_fac_oilgas Number of oil and gas facilities within the source watersheds facilities
n_fac_total Total number of facilities operating within the source watersheds facilities
hydro_gen_MWh Combined hydroelectric generation from all the facilities within the source watersheds megawatt-hours
thermal_gen_MWh Combined thermal generation from all the facilities within the source watersheds megawatt-hours
thermal_cons_BCM Combined water consumption that is used for thermal generation billion cubic meters
thermal_with_BCM Combined water withdrawal for thermal generation billion cubic meters
n_utilities Number of electric utilities within the source watersheds utilities
n_ba Number of balancing authorities within the source watersheds balancing authorities
n_crop_classes Total number of different types of crops within the source watersheds crops
cropland_fraction Fraction of land that is used for crops within the source watersheds fraction
developed_fraction Fraction of land that is developed within the source watersheds fraction
ag_runoff_max Max amount of agricultural runoff within the source watersheds fraction
ag_runoff_av_exgw Average agricultural runoff (excluding ground water) fraction
ag_runoff_av Average runoff from agricultural lands fraction
dev_runof_max Max amount of agricultural runoff within the source watersheds fraction
dev_runof_av_exgw Average developed runoff (excluding ground water) fraction
dev_runof_av Average runoff from developed lands fraction
np_runoff_max Max amount of non-point source runoff within the source watersheds fraction
np_runoff_av_exgw Average non-point runoff (excluding ground water) fraction
np_runoff_av_exgw_unweighted Average non-point runoff unweighted (excluding ground water) fraction
np_runoff_av Average non-point source runoff. fraction
n_economic_sectors Total number of different economic sectors within the source watersheds sectors
max_withdr_dis_km Maximum distance between a city’s intake points kilometers
avg_withdr_dis_km Average distance between a city’s intake points kilometers
n_treatment_plants Total number of waste water treatment plants operating within the source watersheds plants
watershed_pop Total number of people living within the source watershed boundaries people
pop_cons_m3sec Combined water consumption from the source watersheds that is used for people m3/sec
av_fl_sur_conc_pct Average surface flow concentration %
av_fl_sur_conc_pct_unweighted Average surface flow concentration unweighted %
av_ro_sur_conc_pct Average surface runoff concentration %
av_fl_all_conc_pct Average flow concentration %
av_ro_all_conc_pct Average runoff concentration %
av_fl_max_conc_pct Max average flow concentration %
av_ro_max_conc_pct Max average runoff concentration %
surface_contribution_pct Surface contribution %
importance_of_worst_watershed_pct Measures the importance of the watershed with the worst contamination %

Dependencies

gamut relies on functionality from the following R packages: clisymbols, crayon, dplyr, dams, exactextractr, foreign, geosphere, ggplot2, lwgeom, magrittr, purrr, raster, readxl, reservoir, rgdal, rgeos, sf, sp, spex, stringr, tibble, tidyr, vroom, testthat, knitr, rmarkdown, knitr.

Support

For any questions about the package, please contact any of the contributors below:

Kristian Nelson:

Sean Turner:

Chris Vernon

Authors and Acknowledgement

Authors: Kristian Nelson, Sean Turner, Chris Vernon, Jennie Rice, Casey Burleyson, Ryan McManamay, Kerim Dickson

This research was supported by the US Department of Energy, Office of Science, as part of research in the MultiSector Dynamics, Earth and Environmental System Modeling Program.