Giter Club home page Giter Club logo

rivgraph's Introduction

build Coverage Status docs DOI

RivGraph logo

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).

Core functionality of RivGraph.\label{fig:corefunctions}

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 v0.4 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 anything

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 jschwenk

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.

rivgraph's People

Contributors

elbeejay avatar jonschwenk avatar kbarnhart avatar lvulis avatar rivfam avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.