Data and code for: River planforms originate from (im)balance between riverbank erosion and bar accretion
Data files
Abstract
Why rivers confine flow to a single channel (single-thread planform) or divide flow into multiple sub-channels (multi-thread planform) forms a longstanding fundamental question in river science, which to date remains poorly understood. In the associated manuscript, we probe planform origins using a novel dataset of 11+ million riverbank migration vectors mapped from 36 years of global satellite imagery along 84 river systems. Results show single-thread rivers originate from a balance between bank erosion and opposing-bar deposition, which maintains an equilibrium width as channels migrate. In contrast, multi-thread rivers originate from imbalance: bank erosion outpaces opposing-bar deposition, causing sub-channels to repeatedly widen and split. This width instability challenges equilibrium paradigms in river science, endangers riverside communities, and lowers the potential costs of nature-based river restoration projects along multi-thread rivers. Here, we provide the data and codes that form the foundation of this manuscript.
README: Data and code for: River planforms originate from (im)balance between bank erosion and bar accretion
author: Austin Chadwick
contact: achadwick@ldeo.columbia.edu, austin.chadwick23@gmail.com
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 "River planforms originate from (im)balance between bank erosion and bar accretion". The Codes folder provides MATLAB scripts and functions to generate the analysis and figures of the main manuscript. 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_082224_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.
- Polygons 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 "River planforms originate from (im)balance between bank erosion and bar accretion". 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).
- 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. 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. For details of this process, see: https://doi.org/10.1029/2023JF007177.
- OutputFromPIVlab subfolder This folder contains the Raw PIV data output from 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_082224_1.xlsx for details on which file corresponds to which confidence level and tilt angle). For additional instructions on how to operate PIVlab , 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
- PostprocessedPIV subfolder This folder contains the postprocessed PIV data output. 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").
- BankNormalVectors subfolder This folder contains the bank-normal vector fields for each image. The data structure is identical to the PostprocssedPIV data, with a single .mat file for each river "BankNormalVectors.mat". All vectors have a length of 1, and are oriented perpendicular to the nearest channel bank, pointing away from the wetted area and towards the dry area. For details on this calculation, see: https://doi.org/10.1029/2021WR031236.
- CrossSections subfolder This folder contains the data for the thread cross sections randomly sampled in each reach to calculate the differential migration rate (delv). Each site-specific subfolder contains a single mat file, "CrossSections.mat". This mat contains the positions (x,y) and the bank migration vectors (u,v) for each cross section. Spatial units are in pixels, and temporal units are in frames, such that velocities are in units of pixels/frame.
- WettedAreas subfolder This folder contains the data for the wetted channel areas, used to investigate apparent changes in water discharge and plot supplemental figures. Each site-specific subfolder contains a single mat file, "WettedAreas.mat". This mat contains the positions (x,y) and the bank migration vectors (u,v) for each cross section.
Sharing/Access information
Some data referenced in the Datalog_082224.xlsx spreadsheet was derived from previous work:
- Sylvester et al., 2019: https://doi.org/10.1130/G45608.1
- Rowland et al., 2019: https://doi.org/10.15485/1571527
- Galeazzi et al., 2021: https://doi.org/10.1130/G49121.1
- Ielpi et al., 2023: https://doi.org/10.1029/2022GL101285
Code/Software
All codes are found in the folder "Codes". To run any codes, it is necessary to add the "Codes" and "Data" folders (and their subfolders) to your current MATLAB path. This can be easily achieved by right-clicking the folder in the MATLAB GUI and selecting "Add To Path-->SelectedFolders and Subfolders", and 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:
- AnalsysisAndFigures1_Worldmap_082924_1.m This MATLAB script reproduces Figure 1A of the manuscript and its associated analysis.
- AnalysisAndFigures2_PIVmethods_082924_1.m This MATLAB script reproduces Figure 1E of the manuscript and its associated analysis.
- AnalysisAndFigures3_DifferentialMigration_082924_1.m This MATLAB script reproduces Figure 2A and Figure 4 of the manuscript, Text S1 Figures 1–4 of the supplement, and their associated analysis. It also reproduces the tabular data in Data S1, performs the statistical tests on delv* reported in the text, and counts the number of vector measurements in our database as reported in the text.
- AnalysisAndFigures4_TimeSlices_082924_1.m This MATLAB script reproduces Figure 2B-G and Figure 4 of the manuscript and Figures S1–S3 of the supplement and their associated analysis. In the first code block (L23–36), the user designates the reach and cross section to plot by uncommenting the corresponding line. See code's comments on L23–36 for details.
- AnalysisAndFigures5_MaterialsAndMethods_082924_1 This MATLAB script reproduces the supplement's Materials & Methods Figures 1–6 and their associated analysis. In the first code block (L19-23), the user designates the reach to plot by uncommenting the corresponding line. See code's comments on L19-23 for details.
- AnalysisAndFigures6_SuppMovieFrames_082924_1.m This MATLAB script reproduces the frames of supplementary Movies S1–S3. In the first code block (L18-23), the user designates the reach to plot by uncommenting the corresponding line. See code's comments on L18-23 for details.
- LatLonBySite_081924_1.xlsx This excel document records the approximate latitude and longitude coordinates of each studied reach in the main manuscript. 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 Polygons subfolder described above.