DOI: 10.5061/dryad.x69p8cztk
title: Data and code for: River planforms originate from (im)balance between riverbank erosion and bar accretion

description: 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. 
description: # Data and code for: River planforms originate from (im)balance between
 bank erosion and bar accretion --- author: Austin Chadwick contact:
 [achadwick@ldeo.columbia.edu](mailto:achadwick@ldeo.columbia.edu),
 [austin.chadwick23@gmail.com](mailto: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", which can be accessted by opening the zip
 file "Data.zip". 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](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](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](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) * 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](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](https://doi.org/10.1130/G45608.1) * Rowland et al., 2019: [https://doi.org/10.15485/1571527](https://doi.org/10.15485/1571527) * Galeazzi et al., 2021: [https://doi.org/10.1130/G49121.1](https://doi.org/10.1130/G49121.1) * Ielpi et al., 2023: [https://doi.org/10.1029/2022GL101285](https://doi.org/10.1029/2022GL101285) ## Code/Software All codes are found in the folder "Codes", which can be accessed by opening the zip folder "Codes.zip". 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--&gt;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. ### Change Log Version 2: minor changes in README.