README.md

In IMMM-SFA/teleconnect: Geospatial Analytics for Multisector Urban Teleconnections

gamut

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: [e-mail]

Sean Turner: [e-mail]

Chris Vernon [e-mail]

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.

IMMM-SFA/teleconnect documentation built on Oct. 22, 2021, 2 p.m.