RivMapper

Channel mobility, sediment storage, and transit-time analysis for global alluvial rivers, from decadal Landsat remote sensing to millennial sediment dynamics.

RivMapper implements the Geomorphic Clock framework: a 13-step pipeline that turns a single master CSV plus public datasets (HydroRIVERS, Landsat, NASADEM / ArcticDEM, GQBF, GRWL, WBMsed, Nyberg channel belts) into per-reach estimates of channel mobility timescales, sediment storage-time distributions, transit lengths, and total alluvial transit times — for any alluvial river that is Landsat mapable and has coverage by the input datasets.

Status: 0.1 — pipeline functional end-to-end, tests in progress.

Citation

If you use RivMapper in your research, please cite the package release and the accompanying paper. Both citations will be added here once the manuscript and Zenodo deposit are public.

Pipeline

 1. extract_hydrorivers   trace HydroRIVERS polylines downstream
 2. create_reaches        split + buffer reaches by upstream area
 3. channel_belt          Nyberg channel-belt extraction + per-reach split
 4. create_masks          DSWE / Landsat masks via GEE in per-reach UTM
 5. planform              skeleton -> main channel + sinuosity / CCI / CFI
 6. clean_masks           main-channel-filtered cleaned masks
 7. hydraulic_geometry    width / slope / depth / Q_bf via GQBF + BASED
 8. extract_wbmsed        per-reach WBMsed sediment flux components
 9. mobility              T_R, T_M, T_W, p_switch, A_W distributions
10. storage_time          sticky random-walk t_stor distributions
11. transit_length        x_tran + n_stor from sediment budget
12. transit_time          t_reach, u_reach, t_tot Monte Carlos
13. visualization         channel-evolution GIFs

Modules are independent — each reads its inputs from disk and writes its outputs to a fixed sub-tree under the per-river working_directory — so single steps can be re-run without redoing the whole pipeline.

Module	Reads from	Writes to
extract_hydrorivers	HydroATLAS/HydroRIVERS/HydroRIVERS_v10_<zone>_shp/	HydroATLAS/HydroRIVERS/Extracted_Rivers/<river>/<river>.shp
create_reaches	step 1 output	<...>/Extracted_Rivers/<river>/<river>_reaches.shp, RiverMapping/Reaches/<river>/<river>.shp
channel_belt	ChannelBelts/, step 2 reaches	ChannelBelts/Extracted_ChannelBelts/<river>/{*_channelbelt.shp, *_channelbelt_split.shp, *_channelbelt_areas.csv}
create_masks	step 2 reaches, GEE, GRWL	RiverMapping/RiverMasks/<river>/reach_N/{Raw,Processed}/*.tif
planform	step 4 Processed/ masks	RiverMapping/Channels/<river>/reach_N/<year>/*.shp, <river>_metrics.xlsx
clean_masks	step 4 Processed/ masks + step 5 main channels	RiverMapping/RiverMasks/<river>/reach_N/Cleaned/*.tif
hydraulic_geometry	step 2 reaches, GQBF, GEE DEM, BASED	RiverMapping/HydraulicGeometry/<river>/<river>_hydraulic_geometry.csv
extract_wbmsed	WBMsed/Averages/, step 2 reaches	WBMsed/Extracted_Rivers/<river>_wbmsed.csv
mobility	step 6 Cleaned/ masks	RiverMapping/Mobility/<river>/{AW_distributions/, Mobility_plots/, <river>_mobility_metrics.csv}
storage_time	step 9 + step 3 outputs	RiverMapping/Mobility/<river>/Tstor_distributions/Reach_N_Tstor_distribution.csv
transit_length	steps 2, 7, 8, 9 outputs	RiverMapping/Mobility/<river>/<river>_transit_lengths.csv
transit_time	steps 10 + 11 outputs	RiverMapping/Mobility/<river>/{treach_distributions/, ureach_distributions/, *_ttot_distribution.csv}
visualization	step 6 Cleaned/ masks	RiverMapping/Visualization/<river>/Reach_N_evolution.gif

A natural execution order is 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10 -> 12 -> 11 -> 13 (the dependency between transit_time and transit_length runs counter to the module numbering — see docs/master_csv.md).

Installation

git clone https://github.com/huck-rees/RivMapper.git
cd RivMapper
pip install -e .

Python 3.10+ is required. A [dev] extra installs pytest, ruff, and notebook tooling:

pip install -e ".[dev]"

External requirements

Several modules need accounts, authentication, or external datasets to run:

• Google Earth Engine account, plus earthengine authenticate once. Newer earthengine-api versions require a Cloud project — pass it through with the --ee-project flag where supported (e.g. hydraulic_geometry). Used by: create_masks, hydraulic_geometry.
• HydroRIVERS v1.0 continental shapefiles (https://www.hydrosheds.org/products/hydrorivers). One zone per continent; place each at <working_directory>/HydroATLAS/HydroRIVERS/HydroRIVERS_v10_<zone>_shp/.
• GRWL vector tiles (Allen & Pavelsky 2018) plus the IMWtiles tile index. The IMWtiles index ships in shapefile_data/; the per-tile vector data must be downloaded separately and placed at <working_directory>/Allen_Pavelsky_2018/GRWL_vector_V01.01/. Used by: create_masks.
• Nyberg channel-belt rasters (Nyberg et al. 2023) plus the GRM tile index. Place at <working_directory>/ChannelBelts/{tifs/, GRM_index.shp}. Used by: channel_belt.
• GQBF geopackages (Liu et al. 2024) — one per continent at <working_directory>/GQBF/GQBFv0.1_reaches_<continent>_EPSG4326.gpkg. Used by: hydraulic_geometry, transit_length.
• WBMsed Annual Averages (Cohen et al. 2022) .asc rasters at <working_directory>/WBMsed/Averages/. Used by: extract_wbmsed.
• BASED model (Gearon et al. 2024) — .ubj weights at <working_directory>/Gearon_etal_2024/based-api/. Used by: hydraulic_geometry. Optional: if the model file is missing, depths come back as NaN and a warning is logged.

A consolidated download checklist with version-pinned URLs, citations, and the on-disk layout each module expects lives in docs/data.md.

Quickstart

Every step reads a master CSV that lists rivers as rows and parameters as columns. A minimal CSV for one river (OkTedi) looks like:

river_name,working_directory,us_hyriv_id,ds_hyriv_id,end_condition,max_length_km,hydroatlas_zone,reach_length_modulator,buffer_width,DSWE_threshold_level,year_range,reach_range,min_pixels,dilation_radius,min_blob_size,num_xcs,num_vertices,fraction_length,sediment_bulkdensity_kg_m3,model_iterations,max_timesteps
OkTedi,E:\Dissertation\Data,<US_HYRIV_ID>,<DS_HYRIV_ID>,specific_segment,200,au,10,0.15,2,"(1985, 2024)","(1, 2)",100,5,10,50,4,2/3,1600,10000,10000

Run any step from the repo root:

python -m rivmapper.extract_hydrorivers   "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.create_reaches        "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.channel_belt          "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.create_masks          "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.planform              "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.clean_masks           "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.hydraulic_geometry    "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.extract_wbmsed        "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.mobility              "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.storage_time          "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.transit_length        "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.transit_time          "E:/Dissertation/Data/OkTedi_river_datasheet.csv"
python -m rivmapper.visualization         "E:/Dissertation/Data/OkTedi_river_datasheet.csv"

Each step iterates over every row of the master CSV, so running on multiple rivers is just a matter of adding rows.

Master CSV columns

Pipeline parameters are driven entirely by the master CSV. The required-column set varies by module. Full schema, per-step requirements, and the CSV-quoting rule for tuple-valued cells (e.g. year_range) are in docs/master_csv.md. The columns referenced in this README are the minimum needed to run every step end-to-end.

Development

pip install -e ".[dev]"
pytest                       # run tests
ruff check rivmapper/        # lint
ruff format rivmapper/       # format

License

MIT — see LICENSE.

Author

James (Huck) Rees — PhD student, UCSB Geography jamesrees@ucsb.edu

Acknowledgments

Built on prior remote-sensing mobility work by Evan Greenberg, Vamsi Ganti, Austin Chadwick, and the broader UCSB Geography fluvial group.

Key references

• Allen, G.H., Pavelsky, T.M., 2018. Global extent of rivers and streams. Science 361, 585-588.
• Cohen, S., Syvitski, J., Ashley, T., Lammers, R., Fekete, B., Li, H.-Y., 2022. Spatial Trends and Drivers of Bedload and Suspended Sediment Fluxes in Global Rivers. WRR 58, e2021WR031583.
• Gearon, J.H., et al., 2024. Boost-Assisted Stream Estimator for Depth (BASED). https://github.com/jameshgrn/based_api
• Greenberg, E., Chadwick, A.J., Ganti, V., 2023. A Generalized Area-Based Framework to Quantify River Mobility From Remotely Sensed Imagery. JGR Earth Surface 128, e2023JF007189.
• Jones, J.W., 2019. Improved Automated Detection of Subpixel-Scale Inundation - Revised Dynamic Surface Water Extent (DSWE) Partial Surface Water Tests. Remote Sensing 11, 374.
• Lehner, B., Verdin, K., Jarvis, A., 2008. New Global Hydrography Derived From Spaceborne Elevation Data. Eos 89, 93-94.
• Liu, Y., Wortmann, M., Slater, L., 2024. Global River BankFull Discharge (GQBF) v0.1. https://doi.org/10.5281/zenodo.13855371
• Nyberg, B., et al., 2023. Global scale analysis on the extent of river channel belts. Nat Commun 14, 2163.
• Pizzuto, J., et al., 2014. Characteristic length scales and time-averaged transport velocities of suspended sediment in the mid-Atlantic Region, USA. WRR 50, 790-805.
• Torres, M.A., et al., 2017. Model predictions of long-lived storage of organic carbon in river deposits. Earth Surface Dynamics 5, 711-730.