rSTEMMUS‑SCOPE: a user‑friendly open‑source R package wrapping a coupled soil–canopy process-based model for urban soil‑moisture and ET — good practices and lessons learned

Process‑based models that explicitly couple soil water and heat transport, canopy radiative transfer, photosynthesis, and surface–atmosphere exchange are increasingly used to connect in‑situ observations with remote‑sensing–relevant land‑surface processes. However, their practical adoption—particularly in heterogeneous urban environments—remains challenging due to complex software dependencies, fragmented preprocessing pipelines, and limited transparency in model configuration. These challenges are exacerbated when such models are accessed through low‑level implementations that are difficult to adapt, reproduce, or extend by domain scientists.

We present rSTEMMUS‑SCOPE, an open‑source R interface to the coupled STEMMUS‑SCOPE modelling framework, designed to apply good practices in scientific software development to a hybrid soil–canopy model that is frequently used by practitioners and researchers interested in ecohydrology, urban climate, and remote sensing. The interface lowers barriers for reproducible experimentation by providing a modular, script‑based workflow that integrates eddy‑covariance forcing, in‑situ soil measurements, vegetation parameters, and multilayer soil discretisation within a transparent R‑based environment that supports from data pre-processing to the visualization of the results.

From a software‑engineering perspective, rSTEMMUS‑SCOPE adopts a modular, script‑based architecture that separates data inputs, model settings, execution, and post‑processing. The package provides reproducible pipelines for preprocessing eddy‑covariance meteorological forcing, precipitation, vegetation parameters, and multilayer soil discretisation (>50 layers), enabling fully scripted end‑to‑end simulations within R. Version‑controlled configuration files, consistent function interfaces, and documented defaults are used to support transparency and extensibility, while example workflows and vignettes lower the entry barrier for users who are domain scientists rather than trained software developers. The design follows a “user‑turned‑developer” paradigm, allowing advanced users to adapt parameterisations and forcing strategies while preserving a stable core interface.

We demonstrate these design choices using an urban case study in a temperate green space in Berlin, where hourly simulations were performed for 2019–2020. Observations from an eddy‑covariance tower and in‑situ soil moisture sensors are used as a software stress test rather than as the primary scientific result. Volumetric soil water content at 60 cm depth was reproduced well (Kling–Gupta Efficiency = 0.82; r = 0.88; α = 1.01), while simulated evapotranspiration captured diurnal and seasonal dynamics (r ≈ 0.67), with systematic biases during low‑energy conditions. Sensitivity experiments illustrate how differences in input data sources and parameter choices propagate through the modelling workflow, highlighting the importance of transparent, reproducible pipelines for diagnosing model behaviour.

We conclude by discussing practical lessons learned in wrapping complex process‑based models in high‑level languages: trade‑offs between modularity and performance, documenting urban‑specific parameter choices without constraining expert use, and testing strategies when upstream physics models are computationally expensive. rSTEMMUS‑SCOPE demonstrates how applying robust software practices enables meaningful, reproducible results and supports early‑career researchers working at the interface of modelling, data, and urban environmental science.

Software availability

rSTEMMUS‑SCOPE (open source): https://github.com/EcoExtreML/rSTEMMUS_SCOPE