WigglyRivers documentation

WigglyRivers is a Python package that builds on existing work using wavelet-based methods to create supervised and unsupervised meander identification tools. This tool allows the characterization of the multiscale nature of river transects and the identification of individual meandering features. The package uses any set of river coordinates and calculates the curvature and direction-angle to perform the characterization, and also leverages the use of the High-Resolution National Hydrography Dataset (NHDPlus HR) to assess river transects at a catchment scale. Additionally, the WigglyRivers package contains a supervised river identification tool that allows the visual selection of individual meandering features with satellite imagery in the background.

Example Notebooks

You can find examples of how to use this package as examples workflows for synthetic and natural river transects in the examples/new_user_workflow/ folder.

The synthetic river transect examples are generated using idealized Kinoshita-type curves, implemented in the code, and using the meanderpy package coded by Sylvester, Durkin, and Covault (2019). The natural river transect example uses the information from the High-Resolution National Hydrography Dataset (NHDPlus HR) to extract the river transects and assess the meandering features.

The package includes several Jupyter notebooks that demonstrate its functionality:

Synthetic Rivers

  1. Kinoshita Examples (Kinoshita_Examples.ipynb): Demonstrates how to generate and analyze synthetic river transects using Kinoshita curves. This notebook shows:

    • Generation of Kinoshita curves with different parameters

    • Curvature and direction-angle calculations

    • Wavelet analysis of river planforms

    • Meander identification and characterization

  2. Meanderpy River Example (Meanderpy_River_Example.ipynb): Shows how to use the meanderpy package integration to:

    • Generate synthetic meandering rivers

    • Analyze their morphological characteristics

    • Compare with Kinoshita curves

Natural Rivers

  1. NHDPlus HR Data Extraction (Extract_NHDPlus_HR_Data.ipynb): Demonstrates how to:

    • Extract river data from the NHDPlus HR dataset

    • Process and analyze real river transects

    • Identify and characterize natural meanders

    • Visualize results with interactive plots

These notebooks can be found in the examples/new_user_workflow/ directory of the repository.

Installation

Requirements

This package has a few requirements. I encourage using a virtual environment of Anaconda 3 with Python 3.10 or higher. The virtual environment creation can be seen here. Below, we list the process to create a virtual environment and install the requirements for the package.

conda create -n wigglyrivers_env python=3.XX
conda activate wigglyrivers_env
conda install -c conda-forge geopandas
conda install -c conda-forge h5py

This package was tested in Python version 3.10 and higher. Some incompatible dependencies might arise with older versions of Python. geopandas is installed first because the package generates the most incompatibilities. After that package, we install the other dependencies with pip

pip install simpledbf
pip install statsmodels
pip install seaborn
pip install pyarrow
pip install plotly
pip install salem
pip install anytree
pip install circle-fit

The package uses anytree to store the information of the meanders.

For interactive plots

pip install ipympl

If you are using .env files, remember to also install

pip install python-dotenv

To run one of the synthetic examples, you will need to install the meanderpy package. You can install it using the following command:

pip install meanderpy

Install WigglyRivers

To install the package you need to clone the repository and install it using pip.

pip install -e .

Some known incompatible dependencies are addressed in the troubleshooting section. If you have any issues not discussed in the troubleshooting section, please open an issue in the repository.

Troubleshooting Package Installation

  • If you have problems with geopandas look at this website.

  • h5py and fiona might have some issues when importing at the same time. Installing both of them using conda install -c -conda-forge solved the issue for me.

  • If the interactive plot with plotly gives you issues with ipywidgets and jupyterlab-widgets, install the following versions pip install ipywidgets==7.7.1 jupyterlab-widgets==1.1.1

  • There is a known issue with plotly<=5.15 where plotting MAPBOX with the interactive widget will prompt the following error message:

    ValueError:
Invalid property path 'mapbox._derived' for layout

    There is a temporary fix to this issue given in the following GitHub issue webpage that requires the use of the function below and restart the kernel.

    def fix_widget_error():
    """
    Fix FigureWidget - 'mapbox._derived' Value Error.
    Adopted from: https://github.com/plotly/plotly.py/issues/2570#issuecomment-738735816
    """
    import shutil
    import pkg_resources

    pkg_dir = os.path.dirname(pkg_resources.resource_filename("plotly", "plotly.py"))

    basedatatypesPath = os.path.join(pkg_dir, "basedatatypes.py")

    backup_file = basedatatypesPath.replace(".py", "_bk.py")
    shutil.copyfile(basedatatypesPath, backup_file)

    # read basedatatypes.py
    with open(basedatatypesPath, "r") as f:
        lines = f.read()

    find = "if not BaseFigure._is_key_path_compatible(key_path_str, self.layout):"

    replace = """if not BaseFigure._is_key_path_compatible(key_path_str, self.layout):
                if key_path_str == "mapbox._derived":
                    return"""

    # add new text
    lines = lines.replace(find, replace)

    # overwrite old 'basedatatypes.py'
    with open(basedatatypesPath, "w") as f:
        f.write(lines)

# Run fix
fix_widget_error()

How to cite

If you use this package, please cite the following paper:

Gonzalez-Duque, D., & Gomez-Velez, J. D. (2025). WigglyRivers: Characterizing the Multiscale Nature of Meandering Channels [Submitted]. Environmental Modelling & Software.

Credit and Acknowledgments

The Continous Wavelet Transform (CWT) computation uses an updated version of the code created by Torrence and Compo (1998) brought to Python by Evgeniya Predybaylo. Also, the unsupervised identification algorithm is based on previous work coded in Matlab by Vermeulen et al. (2016). Each code and function is adequately accredited and cited in the code.

References

Sylvester, Z., Durkin, P., & Covault, J. A. (2019). High curvatures drive river meandering. Geology, 47(3), 263–266. https://doi.org/10.1130/G45608.1

Torrence, C., & Compo, G. P. (1998). A Practical Guide to Wavelet Analysis. Bulletin of the American Meteorological Society, 79(1), 61–78. https://doi.org/10.1175/1520-0477(1998)079<0061:APGTWA>2.0.CO;2

Vermeulen, B., Hoitink, A. J. F., Zolezzi, G., Abad, J. D., & Aalto, R. (2016). Multiscale structure of meanders. Geophysical Research Letters, 2016GL068238. https://doi.org/10.1002/2016GL068238

Contents: