gamut

gamut: A Geospatial R Package to Analyze Multisectoral Urban Teleconnections - Published in JOSS (2021)

https://github.com/immm-sfa/gamut

Repository

An R package to identify multi-sector teleconnection complexity

README.Rmd

---
output: github_document
always_allow_html: yes
---



![build](https://github.com/IMMM-SFA/gamut/workflows/build/badge.svg) [![codecov](https://codecov.io/gh/IMMM-SFA/gamut/branch/main/graph/badge.svg?token=uF3EvxwvCO)](https://codecov.io/gh/IMMM-SFA/gamut) 
[![DOI](https://zenodo.org/badge/203447802.svg)](https://zenodo.org/badge/latestdoi/203447802) 

# `gamut`

## **G**eospatial **A**nalytics for **M**ultisector **U**rban **T**eleconnections

## 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:
```r
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](https://api.github.com/repos/IMMM-SFA/gamut/tarball/HEAD), then run `install_local()` as shown below:
```r
install_local('path/to/package')
```

2. 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](https://cran.r-project.org/bin/windows/Rtools/). 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](https://zenodo.org/record/5554939#.YV9dnNrMJPY) 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.
    
```{r, echo=FALSE,message=FALSE}
library(tibble)
library(knitr)

tribble(
  ~`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"
) -> files

kable(files)
```

## 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](https://github.com/IMMM-SFA/gamut/wiki/Available-Cities).__

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

```r
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:

```{r,echo=FALSE, message=FALSE, warning=FALSE}
library(vroom)
vroom("inst/extdata/example_dataset.csv") -> results
knitr::kable(results)
```

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:

```{r, echo=FALSE,message=FALSE}
tibble::tribble(
  ~`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","%",
) -> variables
kable(variables)
```

### 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:
kristian.nelson@pnnl.gov

Sean Turner:
sean.turner@pnnl.gov

Chris Vernon
chris.vernon@pnnl.gov


## 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.

Owner

JOSS Publication

gamut: A Geospatial R Package to Analyze Multisectoral Urban Teleconnections

Published

October 21, 2021

DOI

10.21105/joss.03383

Volume 6, Issue 66, Page 3383

Authors

Kristian D. Nelson
Pacific Northwest National Laboratory, Richland, Washington, USA

Sean W. Turner
Pacific Northwest National Laboratory, Richland, Washington, USA

Chris R. Vernon
Pacific Northwest National Laboratory, Richland, Washington, USA

Jennie S. Rice
Pacific Northwest National Laboratory, Richland, Washington, USA

Editor

Kristina Riemer

Tags

Multisector Dynamics Water Energy Land Urban Geospatial

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago