About

RivGraph is a Python package that provides tools for converting a binary mask of a channel network into a directed, weighted graph (i.e. a set of connected links and nodes).

The figure above demonstrates the core components of RivGraph, but many other features are provided, including:

• Morphologic metrics (lengths, widths, branching angles, braiding indices)
• Algebraic representations of the channel network graph
• Topologic metrics (both topologic and dynamic such as alternative paths, flux sharing, entropies, mutual information, etc.)
• Tools for cleaning and preparing your binary channel network mask
• Island detection, metrics, and filtering
• Mesh generation for characterizing along-river characteristics
• (beta) Tools for centerline migration analysis

All of RivGraph's functionality maintains and respects georeferencing information. If you start with a georeferenced mask (e.g. a GeoTIFF), RivGraph exports your results in the CRS (coordinate reference system) of your mask for convenient mapping, analysis, and fusion with other datasets in a GIS.

You can see some description of RivGraph's functionality via this AGU poster, and the flow directionality logic and validation is described in our ESurf Dynamics paper. Examples demonstrating the basic RivGraph features are available for a delta channel network and a braided river.

Installing

RivGraph is hosted at conda-forge. We recommend installing into a fresh conda environment to minimize the risk of dependency clashes. The easiest way to do this is to open Terminal (Mac/Unix) or Anaconda Prompt (Windows) and type:

You may then want to install Spyder or your preferred IDE. Conda should fetch all the required dependencies and handle versioning.

If you want to install RivGraph into an already-existing environment, you can run conda activate myenv
conda install rivgraph -c conda-forge

You may also install RivGraph from this Github repo.

Instructions for testing your installation are available here.

How to use?

Please see the documentation for more detailed instructions.

RivGraph requires that you provide a binary mask of your network. This page provides some help, hints, and tools for finding or creating your mask.

To see what RivGraph does and how to operate it, you can work through the Colville Delta example or the Brahmaputra River example. Both examples include sample masks.

RivGraph contains two primary classes (delta and river) that provide convenient methods for creating a processing workflow for a channel network. As the examples demonstrate, you can instantiate a delta or river class, then apply associated methods for each. After looking at the examples, take a look at classes.py to understand what methods are available.

Note: there are many functions under the hood that may be useful to you. Check out the im_utils script (image utilities) in particular for functions to help whip your mask into shape!

Contributing

If you think you're not skilled or experienced enough to contribute, think again! We agree wholeheartedly with the sentiments expressed by this Imposter syndrome disclaimer. We welcome all forms of user contributions including feature requests, bug reports, code, documentation requests, and code. Simply open an issue in the tracker. For code development contributions, please contact us via email to be added to our slack channel where we can hash out a plan for your contribution.

Citing RivGraph

Citations help us justify the effort that goes into building and maintaining this project. If you used RivGraph for your research, please consider citing us.

If you use RivGraph's flow directionality algorithms, please cite our ESurf Dynamics paper. Additionally, if you publish work wherein RivGraph was used to process your data, please cite our JOSS Paper.

Contacting us

The best way to get in touch is to open an issue or comment on any open issue or pull request. Otherwise, send an email to [email protected]

License

This is free software: you can redistribute it and/or modify it under the terms of the BSD 3-clause License. A copy of this license is provided in LICENSE.txt.

RivGraph has been assigned number C19049 by the Feynman Center for Innovation.