RivGraph is a python package that provides tools for converting a binary mask of a channel network into a graph (i.e. a set of connected links and nodes). One major component of RivGraph is its ability to automatically set flow directions in each link of the network. It also computes morphologic metrics (lengths, widths, branching angles, etc.) and topologic metrics. RivGraph also contains a smattering of other tools and features, including some functions for helping clean and prepare your binary mask.
Check out the documentation.
You can see some of RivGraph's functionality via this AGU poster, and the flow directionality logic and validation is described in our ESurf Dynamics paper.
As of 5/26/2020, we are working on buttoning down RivGraph, including documentation, examples, and packaging. Please check back soon, and feel free to interact by opening an issue or emailing j........k@gmail.com. Now is a good time to add feature requests!
RivGraph v0.3 is hosted on the anaconda channel jschwenk. We recommend installing into a fresh conda environment to minimize the risk of dependency clashes. The easiest way to do this is to download the environment.yml file, then open Terminal (Mac/Unix) or Anaconda Prompt (Windows) and type:
conda env create --file /path/to/environment.yml # the environment name will be 'rivgraph', but you can change the environment file to name it anythingYou 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 jschwenkNote: While packaged for all platforms, we have currently only tested the win32, win64, and linux-64 platforms.
Savvy users have been able to install RivGraph from this Github repo, but usually not without dependency headaches. See the environment file for dependencies.
We are working on documentation and examples. Your best bet for getting started is to reproduce the Colville delta example or the Brahmaputra river example. Otherwise, use RivGraph by creating either a delta or a river class, then applying the associated methods. Look at the classes.py script to get a sense for what methods are available, and what they're actually doing.
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!
These tasks represent what is needed before we "officially" release RivGraph via publication in the Journal of Open Source Software.
3/29/2020 - Task list created
- Conda Packaging - Updates 5/25/2020
- Delta example
- Braided river example
- How to fix flow directions (shown in braided river example, section 7.1)
- Function for removing artificial nodes. Restructured code to not add these automatically, but can be added with a function.
- Unit testing
- Function documentation
- How to prepare masks for inputs
- Where to get masks
- How to draw shorelines
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 j.........k@gmail.com
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.
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.
As of 5/26/2020, please cite our ESurf Dynamics paper and/or our AGU Presentation. We hope to soon publish RivGraph in the Journal of Open Source Software.
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.