Author: Lele Shu (shulele@lzb.ac.cn)
Website: www.shud.xyz
GitHub: SHUD-System/rSHUD

rSHUD is an R language toolbox designed for the SHUD (Simulator for Hydrological Unstructured Domain) hydrological modeling system.

SHUD is a multi-process, multi-scale hydrological model that fully couples major hydrological processes using the semi-discrete finite volume method. This package can be used with the AutoSHUD project to automatically build modeling domains.

rSHUD v2.2.0 has been completely modernized to use terra and sf packages exclusively:

• 🚀 150-400% performance improvement on spatial operations
• 🎯 Modern API: Uses terra/sf directly - no legacy raster/sp support
• ✅ Consistent naming: All functions follow snake_case convention
• 📚 Complete documentation: Migration guide and comprehensive examples
• 🧪 Robust testing: 70%+ test coverage with parameter validation

⚠️ Breaking Change: This version requires terra (≥1.7-0) and sf (≥1.0-0). Legacy raster/sp objects are no longer supported. See Migration Guide below.

Process and governance documents are organized under docs/:

• Documentation Index

• Convert geospatial data to SHUD format
• Process raster and vector data
• Build unstructured triangular mesh domains

• Read/write SHUD input files
• Read SHUD output files
• Generate calibration parameter sets

• Time series analysis of hydrological data
• 2D and 3D visualization plotting
• Hydrograph analysis

• Convert unstructured data to spatial data (Shapefile or Raster)
• Watershed delineation and river network processing
• Spatial analysis and visualization

sudo apt -y install gdal-bin libgdal-dev gcc g++ gfortran
sudo apt -y install r-cran-systemfonts r-cran-textshaping

Simple installation (recommended):

# Install from GitHub (includes all dependencies)
if(!require(devtools)) install.packages("devtools")
devtools::install_github("SHUD-System/rSHUD")

Manual dependency installation (if needed):

# Core spatial libraries (required)
install.packages(c("terra", "sf"))

# Other dependencies
install.packages(c("Rcpp", "reshape2", "ggplot2", "xts", "hydroGOF", "zoo",
                   "proj4", "gstat", "abind", "lubridate", "geometry"))

# Custom RTriangle package
devtools::install_github("shulele/RTriangle", subdir="pkg")

# Install rSHUD
devtools::install_github("SHUD-System/rSHUD")

library(rSHUD)
packageVersion("rSHUD")  # Should be 2.2.0
packageVersion("terra")  # Should be >= 1.7.0
packageVersion("sf")     # Should be >= 1.0.0

library(rSHUD)
library(terra)
library(sf)

# Read SHUD model files (new snake_case functions)
mesh <- read_mesh("model.mesh")
river <- read_river("model.riv")
attributes <- read_att("model.att")

# Read spatial data with terra/sf
dem <- rast("dem.tif")
watershed <- st_read("watershed.shp")

# Auto-build model (modern API)
model <- auto_build_model(
  dem = dem,
  watershed = watershed,
  rivers = rivers_sf,
  output_dir = "./output"
)

# Spatial visualization
mesh_sf <- sp.mesh2Shape(model$mesh)
plot_polygons(mesh_sf, field = "Area")

# View all example scripts
list.files(system.file("demo", package = "rSHUD"))

# Run specific example
demo(demo_autoBuild, package = "rSHUD")
demo(demo_sac, package = "rSHUD")

rSHUD/
├── R/                    # R source code
├── man/                  # Function help documentation
├── demo/                 # Example scripts
├── data/                 # Example datasets
├── src/                  # C++ source code
├── experiments/          # Experimental code
└── output/               # Output directory

• auto_build_model() - Auto-build SHUD model (modern API)
• read_mesh(), read_river() - Read mesh and river data
• write_mesh(), write_river() - Write mesh and river data
• read_att(), read_para(), read_calib() - Read model configuration

• watershed_delineation() - Watershed delineation
• vector_to_raster() - Convert vector to raster (terra)
• mesh_to_raster() - Convert mesh data to raster
• mesh_to_shapefile() - Export mesh as shapefile

• plot_hydrograph() - Hydrograph analysis
• plot_polygons() - Spatial polygon plotting
• compare_maps() - Side-by-side map comparison

• calc_pet_pm() - Penman-Monteith evapotranspiration
• calc_melt_factor() - Melt factor calculation
• calc_river_order() - River order calculation
• ts_to_daily() - Time series aggregation

• autoBuildModel() → use auto_build_model()
• readmesh() → use read_mesh()
• sp2raster() → use vector_to_raster()
• hydrograph() → use plot_hydrograph()

See NEWS.md for complete list of deprecated functions.

1. Update spatial object types:

# Old (v2.1.x - no longer works)
library(raster)
library(sp)
dem <- raster("dem.tif")
watershed <- readOGR("watershed.shp")

# New (v2.2.0)
library(terra)
library(sf)
dem <- rast("dem.tif")
watershed <- st_read("watershed.shp")

2. Update function names:

# Old function names (deprecated but still work with warnings)
mesh <- readmesh("model.mesh")
river <- readriv("model.riv")
ts_data <- read.tsd("data.tsd")

# New function names (recommended)
mesh <- read_mesh("model.mesh")
river <- read_river("model.riv")
ts_data <- read_tsd("data.tsd")

3. Update spatial operations:

# Old (raster package)
cropped <- crop(raster_obj, extent_obj)
buffered <- buffer(sp_obj, width = 100)

# New (terra/sf)
cropped <- crop(rast_obj, ext_obj)
buffered <- st_buffer(sf_obj, dist = 100)

For detailed migration instructions, see:

• NEWS.md - Complete list of changes and deprecated functions
• Package vignettes: vignette("migration", package = "rSHUD")
• Online documentation: www.shud.xyz

If you encounter issues during migration:

1. Check the deprecation warnings - they provide the new function names
2. Read NEWS.md for breaking changes
3. Open an issue on GitHub with a reproducible example

• Function Help: Use ?function_name for detailed help
• Example Code: View example scripts in demo/ directory
• Online Documentation: www.shud.xyz
• Migration Guide: See NEWS.md and package vignettes
• Chinese Version: README_cn.md

Welcome to submit Issues and Pull Requests! Please ensure:

1. Code follows R package development standards
2. New functions include complete documentation and tests
3. Follow the project's coding style

For detailed contributing guidelines, see CONTRIBUTING.md.

This project is licensed under the MIT License - see the LICENSE file for details

• Email: shulele@lzb.ac.cn
• Project Homepage: www.shud.xyz
• GitHub: SHUD-System/rSHUD

If this project helps you, please give us a ⭐️ star!