Satellite surface reflectance data and predictors of water color in Texas reservoirs

Malcolm Macleod

About

This repository is in support of the Water Color in Texan Reservoirs which quantified water color using dominant wavelength for 190 major reservoirs in Texas, calculated the water color in reservoir arms and main bodies using a standardized reservoir arm selection procedure, and conducted an analysis of water color predictors at the reservoir centers (Chebyshev centers, n = 190 reservoirs) and arm-body locations (n =103 reservoirs). Dominant wavelength was calculated using chromaticity analysis with surface reflectance data from 3 satellite sensors: Landsat 8/9 OLI and Sentinel-2 MSI. The primary goal of this data repository is for the replication of the analysis conducted, a secondary objective is to provide the necessary tools for someone to conduct similar research for other reservoirs. As such, the contents of this repository are categorized into 1) Data used in the analysis of dominant wavelength at reservoir centers and at paired arm-body sites; 2) Code used to calculate dominant wavelength and minimum surface extents in Google Earth Engine; 3) R scripts to run the interactive reservoir arm point selection tool.

Repository contents

1) Data for analysis

Data: raw surface reflectance data with quality assurance flags ("dwlraw_chebyshev_flags.csv" and "dwlraw_armbody_flags.csv"); monthly dominant wavelength data used in linear mixed-effects models and summary statistics ("chebyshev_monthlydwl.csv" and "armbody_monthlydwl.csv"); and predictors of dominant wavelength at the reservoir centers to run boosted regression trees ("chebyshev_brt_predictors.csv"). Scripts: Code used to run the analysis for final results ("WaterColorTX_analysis.R")

2) Downloading raw data:

Scripts: JavaScript code to calculate dominant wavelength with sensor-specific coefficients ("ArmBody_DominantWavelength_L8_L9_S2.js"); Code to determine minimum surface water extent using the JRC Global Surface Water product in GEE ("JRC_MinExtent.js")

3) Reservoir arm point selection method

Scripts: R scripts to run the arm selection method starting with loading reservoir-specific data ("01_load_data.R"), the script with all of the functions in which buffer distances can be adjusted ("02_reservoir_arm_selection.R"), and the code to run the interactive arm selection tool in the R console ("03_run_full.R")

1) Data for analysis

This study analyzed patterns of water color measured as dominant wavelength over a 10-year period (2014-2025) at three locations within reservoirs including the reservoir centers and paired near-dam and reservoir arm points determined using an arm selection method. For each of these we provide dominant wavelength values per scene with raw surface reflectance values used in calculations, these files are "dwlraw_chebyshev_flags.csv" and "dwlraw_armbody_flags.csv". We provide the monthly aggregated dominant wavelength data without flagged observations which was used in the analyses along with the predictors used in the corresponding linear mixed-effects models, these files are "chebyshev_monthlydwl.csv" and "armbody_monthly.csv". We also conducted an predictor analysis for dominant wavelength at the reservoir center using Boosted Regression Trees for the reservoirs with the most complete data (n =110), this data file is "chebyshev_brt_predictors.csv".

dwlraw_chebyshev_flags.csv - Dominant wavelength calculated at the reservoir center (n =190 reservoirs) with raw surface reflectance values (Coastal aerosol, blue, green, red, near infrared, shortwave infrared), quality assurance bands, and flags to identify potentially contaminated images. This file includes point coordinates (longitude, latitude) and date of satellite image acquisition.

dwlraw_armbody_flags.csv - Dominant wavelength calculated for paired reservoir arm and near-dam locations (n =103 reservoirs) with raw surface reflectance values (Coastal aerosol, blue, green, red, near infrared, shortwave infrared), quality assurance bands, and flags to identify potentially contaminated images. This file includes point coordinates (longitude, latitude) and date of satellite image acquisition.

chebyshev_monthlydwl.csv - Data for analyzing the monthly mean dominant wavelength calculated at the Chebyshev center of 190 Texas reservoirs with corresponding Forel-Ule Index number to aid with visualization of water color as perceived by the human eye. Palmer Drought Severity Index (PDSI) sourced from GridMET is aggregated at the monthly scale to match the water color data. Other variables include month which was used to model seasonal effects, and a two-category region variable (region2; east, central/west.

armbody_monthlydwl.csv - Dominant wavelength data calculated at reservoir arms and near-dam points for all 103 reservoirs with resolvable arms. In addition to region2, month, and PDSI, this file includes percent storage capacity (pct_full_monthly) for the 64 reservoirs used in the drawdown models.

chebyshev_brt_predictors.csv - Compiled list of 21 predictor variables of dominant wavelength at the reservoir center of 110 reservoirs used to run Boosted Regression Tree models. The variables range from physical, watershed, water quality, and climatic/geographic.

2) Chromaticity analysis code

DominantWavelength_L8_L9_S2.js - JavaScript file to be used in Google Earth Engine for calculating dominant wavelength from surface reflectance using Bands 1-4 in the visible spectrum (Coastal/Aerosol, Blue, Green, and Red). This code integrates image collections across Landsat 8 (LANDSAT/LC08/C02/T1_L2), Landsat 9 (LANDSAT/LC09/C02/T1_L2), and Sentinel-2 (COPERNICUS/S2_SR_HARMONIZED). Clouds and cloud shadows are masked using QA_PIXEL filtering for Landsat 8/9 OLI and S2 Cloud Probability (COPERNICUS/S2_CLOUD_PROBABILITY) for Sentinel-2 MSI. The function rgb2wavelength_Lehmann is adapted for each sensor and converts surface reflectance from the visible bands into dominant wavelength (Lehmann et al. 2018). Sensor-specific linear coefficients and hue-angle correction polynomial values are sourced from Van der Woerd and Wernand 2018. samplePoints will be assigned to the featureCollection for the systems you are interested in doing this analysis for. runForYear function allows you to input the year range of interest and calculate dominant wavelength for every cloud free pixel in your samplePoints.

JRC_Reservoirs.js - JavaScript file to be used in Google Earth Engine for determining minimum surface water extent using the JRC Global Surface Water product (Pekel et al. 2016) with a >90% occurrence threshold. Polygons for reservoirs of interest can be loaded as an asset (for our work we used the TWDB Existing Reservoirs shapefile) which will be clipped to minimum surface extent and exported as a shapefile which can be used in the reservoir arm selection procedure.

3) Reservoir arm selection point method

Workflow starts with specifying data to load in 01, setting buffer distances in 02, and running the interactive reservoir arm selection tool in 03

01_load_data.R - Start here to specify the data sources to be used within this standardized reservoir arm selection tool. The first step is determining the minimum surface water extent in Google Earth Engine using the JRC Global Surface Water Product filtered to a >=90% threshold and exporting these as polygons. These minimum surface extent polygons become your input for reservoirs and your folder that contains them can be specified as the "jrc_folder". The flowlines come from the National Hydrography Dataset Plus High Resolution, these should be clipped to you region of interest and this file can be specified as the "flowlines_path".

02_reservoir_arm_selection.R - This script contains all of the functions needed to run the tool, these include: 1) Identifying flowline intersections with the minimum surface water extent; 2) Healing fragmented sections through buffering and union to ensure a continuous polygon from which to select arm points; 3) Identifying up to 6 arm candidates per reservoir at greatest distance from the dam, along with categorizing the most downstream intersection as the dam outflow; 4) Applying a buffer on the selected arm candidate and the minimum extent polygon, using pole of inaccessibility to place a point maximally distant from the edges of this buffered overlap. The interactive arm selection has customizable buffer distances "dam_buffer_dist" and "arm_buffer_dist" can each be set to a different number than the 3000m and 1500m, respectively, used for large reservoirs in this study.

03_run_full.R - This is the script that will actually run the tool, it takes the user-specified "load_data" file and the "reservoir_arm_selection" geospatial framework as inputs. Running the "interactive_arm_selection" function will result in a command line selection where the user can select arm candidate points for each minimum extent polygon loaded. At the end, a CSV with all selected near-dam and arm points is produced to be imported as a featureCollection in GEE to calculate dominant wavelength or any other satellite-derived water quality variable.