Data and code for: Remote sensing of riverbank migration using particle image velocimetry
Data files
Abstract
Roughly three billion people worldwide live along large rivers and rely upon them for food, water, transport, and energy. To ensure the safety and sustainability of these riverside communities, it is important that we understand how rivers migrate over time. Satellite missions like NASA Landsat have captured millions of images of migrating rivers worldwide for more than thirty years—more images than can be feasibly mapped manually. These data and codes accompany the manuscript "Remote Sensing of Riverbank Migration using Particle Image Velocimetry" by Austin J. Chadwick, Evan Greenberg, and Vamsi Ganti. In this manuscript, we build on previous work and present a method to automatically map riverbank migration from satellite images using a technique called particle image velocimetry (PIV). We apply PIV to Landsat-image time series for 21 example rivers and show PIV results are efficient, reproducible, and accurate compared with existing automatic techniques. Importantly, unlike existing techniques, the PIV method directly accounts for the inherent uncertainty in migration-rate measurements that arises when identifying riverbanks from satellite imagery. Furthermore, PIV is equally applicable to all kinds of rivers (e.g., meandering, braided), opening up new opportunities to investigate the diversity of rivers and their responses to climate change and human activities in our rapidly changing world.
README: Data and Code for "Remote sensing of riverbank migration using particle image velocimetry"
author: Austin Chadwick
contact: achadwick@ucsb.edu
These materials are organized into two folders, Codes and Data. The Data folder contains spreadsheets, GIS geopackages, remote sensing images, and MATLAB data files for the associated manuscript "Remote Sensing of Riverbank Migration using Particle Image Velocimetry". The Codes folder provides MATLAB scripts and functions to generate the analysis and figures of the main manuscript, as well as to implement the PIV method to some example remote sensing data. The last folder, temp, is empty; it acts as a temporary destination for output files that can be generated by the codes.
Description of the data and file structure
All data are found in the folder "Data". The following is a breakdown of each file and subfolder in the Data folder.
- DataLog_031623_1.xlsx This excel document records the files used to apply PIV to remote sensing imagery, organized on a site-by-site basis. All files referenced therein are found in the Data folder. See the first sheet therein "Readme" for details.
- LatLonBySite_013023_1.xlsx This excel document records the approximate latitude and longitude coordinates of each studied reach in the main manuscript (see main manuscript Table 1 for details). These coordinates were used to generate Fig. 1 in the main manuscript, and were obtained by manually inspecting the coordinates of each .gpkg file in QGIS. The precise geographic coordinates for each reach can be found in the .gpkg files, in the GIS subfolder described below.
- DiscrepancyAndDownstreamMotion_030923_1.xlsx This excel document contains data for the fraction of downstream motion detected by PIV and the quantified agreement between PIV and DTW/SCREAM, organized on a site-by-site basis. These data were used to generate Fig. S3 of the main manuscript, and were obtained by running the following codes and visually inspecting the output plots: PlotFig4andS2_QueryWindowAnalysisRowland_030923_1.m PlotFig4andS1_QueryWindowAnalysisSylvester_030923_1.m Detailed descriptions for these codes can be found later in this readme.
- GIS subfolder This subfolder contains geopackage files (.gpkg) for each study reach in the main manuscript. Each file contains geopackage data for a single polygon that outlines and defines the study reach. These data were used to extract GEOTIFFs using google earth engine, and were obtained by manual selection in QGIS. See main manuscript for details on the selection process and sizing of each polygon.
- GEOTIFFS subfolder This folder contains DSWE-derived river-mask GEOTIFFs derived from Landsat median annual composites, used for the analysis and figures of the main manuscript "Remote Sensing of Riverbank Migration using Particle Image Velocimetry". The DSWE-derived river masks were created in Google Earth Engine using the "GEE_watermasks" code found on the GitHub Repository (https://github.com/evan-greenbrg/GEE_watermasks). Each subfolder corresponds to a study reach in the main manuscript (see Table 1 in main manuscript), with nested subfolders containing river masks derived using DSWE confidence levels 1 through 4 (mask1, mask2, mask3, mask4). For a few reaches (Mamore, Purus_2-C, Yukon, PechoraNorth, Jurua-A) we also include Landsat median annual composites ("image" subfolder), as they were used when generating Figures.
- PreparedImagery subfolder This folder contains true-color images and DSWE-derived river masks (.tif) for each study reach. These data were used as input data for PIV, and were obtained by running the code Methods_ImagePreparation_GEOG288VG_031723_1.m (described later in this readme). For each site, there is a subfolder containing truecolor images ("Color") and sixteen subfolders containing DSWE-derived river masks for the four different confidence levels and four different tilt angles ("MaskX_TiltYY", where X is the confidence level and YY is the tilt angle). In each of these subfolders, there are two nested subfolders "RemovedBlanks" and "RemovedForSubsampling" which contain additional .tif's that were removed because they were blank or because optimal PIV analysis required subsampling, respectively. The removal process was performed using the script Methods_RemoveImages_GEOG288VG_110422_1.m (described later in this readme). A table of the removed images for each site can be found in DataLog_031623_1.xlsx.
- RawPIV subfolder This folder contains the Raw PIV data output from Methods_ImplementPIV_GEOG288VG_100522_1.m and the associated PIVlab software for each site. Each site-specific subfolder contains sixteen .mat files, each of which corresponds to a specific confidence level and tilt angle in the prepared imagery (see DataLog_031623_1.xlsx for details on which file corresponds to which confidence level and tilt angle).
- PostprocessedPIV subfolder This folder contains the postprocessed PIV data output from Methods_PostProcessing_GEOG288VG_110422_1.m. Each site-specific subfolder contains four .mat files. These files contain the postprocessed data before filtering (Unfiltered.mat), the postprocessed data after filtering ("Filtered.mat"), the postprocessed data after filtering and setting all NaN values along high-confidence banks to zero ("Filtered_NanToZeroOnBank"), and a single file containing the sixteen retilted and interpolated vector fields that were used in postprocessing "AllRealizations_RetiltedAndInterpolated.mat".
- ComparisonWindows subfolder This folder contains the identified comparison windows and window-averaged migration rates calculated in the following codes: PlotFig4andS2_QueryWindowAnalysisRowland_030923_1.m PlotFig4andS1_QueryWindowAnalysisSylvester_030923_1.m A detailed description of these codes are found later in this readme.
- FromRowland subfolder This folder contains the data from Rowland et al. (2019) that was used to produce data in the ComparisonWindows subfolder (mentioned above). See "Sharing/Access information".
- FromSylvester subfolder This folder contains the data from Sylvester et al. (2019) that was used to produce data in the ComparisonWindows subfolder (mentioned above). See "Sharing/Access information".
Sharing/Access information
Data was derived from the following sources:
- Sylvester et al., 2019: https://doi.org/10.1130/G45608.1
- Rowland et al., 2019: https://doi.org/10.15485/1571527
Code/Software
All codes are found in the folder "Codes". To run any codes, it is necessary to set your Current Folder in MATLAB to the main directory (DataSubmission), and to add the folders "Codes" and "Data" to the MATLAB path. This will ensure that all input and output files are identified properly. The following is a breakdown of each file and subfolder in the Codes folder:
- Methods_ImagePreparation_GEOG288VG_031723_1.m This MATLAB script performs the first step of the PIV method, image preparation. See the main manuscript (Section 2.1) and in-line comments for details. User inputs are at the top of the script. As default it is set to analyze the reach "Jurua-A".
- Methods_RemoveImages_GEOG288VG_110422_1.m This MATLAB script performs an optional step after image preparation: image removal. At the top of the script, the user can designate years where Landsat images are blank, and years that should be removed for subsampling at the optimum image timestep for PIV (see main manuscript Section 2.1 for details). This step is necessary if any of the landsat images are blank (this crashes PIVlab) and if the desired image timestep is more than 1 year. Running the script will organize these removed images into subfolders (they will not be deleted). See Data/Datalog_031623_1.xlsx for a list of years that were removed for each reach in our analysis.
- Methods_ImplementPIV_GEOG288VG_100522_1.m This MATLAB script performs the second step of the PIV method, PIV implementation. It is responsible for initiating the PIVlab GUI where the user selects the input imagery and parameters for PIV. See the main manuscript (Section 2.1) and in-line comments for details. For additional instructions on how to operate the PIVlab GUI, please see the following links: http://sead-published.ncsa.illinois.edu/seadrepository/api/researchobjects/urn:uuid:6154f24ae4b0312e761fb761 https://www.mathworks.com/matlabcentral/fileexchange/27659-pivlab-particle-image-velocimetry-piv-tool-with-gui
- Methods_PostProcessing_GEOG288VG_110422_1.m This MATLAB script performs the third step of the PIV method, PIV postprocessing. See the main manuscript (Section 2.1) and in-line comments for details. User inputs are at the top of the script. As default it is set to analyze the reach "Jurua-A".
- PlotFig1_Worldmap_013023_1.m This MATLAB script plots the world map in Fig. 1 of the main manuscript.
- PlotFig3_GetQueryWindowsRowland_031623_1.m This MATLAB script defines the windows for comparing data between PIV and SCREAM methods, and calculates window-averaged migration rates in each window. It is also used to plot images in Figure 3. User inputs are at the top of the script. See main manuscript (Section 2.2) and in-line comments for details.
- PlotFig3_GetQueryWindowsSylvester_030823_1.m This MATLAB script defines the windows for comparing data between PIV and DTW methods, and calculates window-averaged migration rates in each window. User inputs are at the top of the script. It is also used to plot images in Figure 3. See main manuscript (Section 2.2) and in-line comments for details.
- PlotFig4andS2_QueryWindowAnalysisRowland_030923_1.m This MATLAB script analyzes and compares window-averaged migration rates between PIV and SCREAM. It generates plots shown in Fig. 4 and in Fig. S2. User inputs are at the top of the script. It is also used to plot images in Figure 3. See main manuscript (Section 3.2) and in-line comments for details.
- PlotFig4andS1_QueryWindowAnalysisSylvester_030923_1.m This MATLAB script analyzes and compares window-averaged migration rates between PIV and DTW. It generates plots shown in Fig. 4 and in Fig. S1. User inputs are at the top of the script. It is also used to plot images in Figure 3. See main manuscript (Section 3.1) and in-line comments for details.
- PlotFig4_TimeSlicesRowland_Xslice_012623_2.m This MATLAB script analyzes and plots PIV data for a cross-section at specified x-location for a reach with SCREAM data (Rowland et al., 2019). User inputs are at the top of the script. It is used to generate plots in Figure 4.
- PlotFig4and5_TimeSlicesSylvester_Yslice_031023_1.m This MATLAB script analyzes and plots PIV data for a cross-section at specified y-location for a reach with SCREAM data (Sylvester et al., 2019). User inputs are at the top of the script. It is used to generate plots in Figure 4.
- PlotFigS3_DiscrepancyVersusDownstreamMotion_030923_1.m This MATLAB script analyzes and plots the discrepancy between PIV and other methods (SCTEAM, DTW) as a function of the measured amount of downstream motion. It is used to generate plots in Figure S3.
- Functions subfolder This subfolder contains MATLAB functions used by the scripts above. These are all either downloaded from the Mathworks website, except for two written by Austin (filldomain.m and fillrange.m). See in-line comments for details on each function.
Usage notes
Refer to the README.md and the DataLog_031623_1.xlsx files for usage notes and details. These data and codes are used to reproduce the analysis and figures from the associated manuscript. Imagery data was collected from NASA Landsat via Google Earth Engine, using Python codes previously published on Zenodo. In these codes, images for a given year were combined into median annual composites, and these composites were analyzed to produce binary images (masks) representing the river channel. For a given image, there are sixteen binary images representing distinct but defensible realizations of the river channel network, which were used to quantify uncertainty in riverbank position and propagate this uncertainty into river mobility. See the associated manuscript for details and references. River mobility data were collected using a method based on particle image velocimetry (PIV), developed in the main manuscript. Originally designed to track particles in a moving fluid, the PIV algorithm was here used to quantify riverbank migration by correlating numerous sub-images nested within each binary image pair. PIV-derived vector fields of riverbank migration were produced for all sixteen realizations of each studied river reach. Then, these data were post-processed using circular statistics to generate a mean vector field and associated uncertainty across realizations. See the associated manuscript for details and references. We include codes used to plot this data for figures in the associated manuscript.