DOI: 10.25349/d9hg82
title: Data and code for: Remote sensing of riverbank migration using particle image velocimetry

description: 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.
description: 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. 
description: # Data and Code for "Remote sensing of riverbank migration using
 particle image velocimetry" --- author: Austin Chadwick contact:
 [achadwick@ucsb.edu](mailto: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](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](https://doi.org/10.1130/G45608.1) * Rowland et al., 2019: [https://doi.org/10.15485/1571527](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](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](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.