iRiverMetrics is an open-source Python toolkit designed for analysing the surface water dynamics of intermittent rivers. It offers a set of modules to help researchers and environmental professionals to detect water and compute ecohydrological metrics from multispectral satellite imagery efficiently.
- Modular Design: Divided into two modules, each serving a specific purpose. This modular approach allows you to use only the components relevant to your project.
- Remote Sensing Integration: Leverages multispectral and multitemporal satellite imagery, enabling you to analyse surface water features and assess river characteristics. It supports common satellite sensors and data formats.
- Efficient Processing: Employs Dask for distributed computing, ensuring local processing of large-scale datasets.
- User-Friendly: Suitable for users with varying levels of expertise. It includes detailed documentation and code comments to guide you through the process.
iRiverMetrics consists of two main modules:
- Water Detection (
waterdetect_batch)): Generate water masks from multispectral imagery using the Water Detect package. It integrates spectral water indices and clustering techniques to delineate and map aquatic bodies accurately. - Calculate Metrics (
calculate_metrics)): Utilises the water masks to compute a range of metrics comprising various aspects of river surface water, such as morphological characteristics, water persistence, and fragmentation.
To get started with iRiverMetrics, follow these steps:
- Clone the Repository: Clone the iRiverMetrics repository from GitHub to your local machine.
cd paste/your/directory/here
git clone https://github.com/tayerthiaggo/iRiverMetrics.git- Requirements: Ensure Python 3.x is installed. Set up the environment and install dependencies using: (install GDAL with conda for less headache)
conda create -n irivermetrics python=3.x
conda activate irivermetrics
conda install conda-forge::gdal
pip install -r paste/clone/directory/requirements.txt-
Explore the Modules: Dive into the documentation for each module to understand their functionality and usage.
-
Example Usage: Review example use cases and code snippets in the documentation of each module (waterdetect_batch and calculate_metrics) apply iRiverMetrics effectively to your projects.
-
Contribute: Contributions are welcome! If you have enhancements or additional features, please consider contributing back to the project via GitHub.
# Add cloned directory to path
import sys
sys.path.append(r'path\to\clone\irivermetrics')
# Import modules
from src.irm_main import waterdetect_batch, calculate_metrics
## Module 1
# Path to a directory containing multispectral images (e.g., TIFF files)
input_img = "path/to/images"
# Path to the river corridor extent shapefile (.shp)
r_lines = "path/to/rcor_extent.shp"
# Generate a DataArray containing water masks based on the specified parameters
da_wmask = waterdetect_batch(input_img, r_lines)
## Module 2
# Path to a directory containing water masks or use a defined DataArray
da_wmask = "path/to/water masks"
# Path to the river corridor extent (sections) shapefile (.shp)
rcor_extent = "path/to/rcor_extent.shp"
# Calculate river metrics
metrics = calculate_metrics(da_wmask, rcor_extent)If you use iRiverMetrics in your research or projects, please consider citing the original paper:
Tayer T.C., Beesley L.S., Douglas M.M., Bourke S.A., Meredith K., McFarlane D. (2023) Ecohydrological metrics derived from multispectral images to characterize surface water in an intermittent river, Journal of Hydrology, Volume 617, Part C, DOI:10.1016/j.jhydrol.2023.129087
and
Tayer T.C., Beesley L.S., Douglas M.M., Bourke S.A., Meredith K., McFarlane D. (2023) Identifying intermittent river sections with similar hydrology using remotely sensed metrics, Journal of Hydrology, Volume 626, Part A, DOI:10.1016/j.jhydrol.2023.130266