paper.md

In hydrosolutions/riversCentralAsia: Accompanying R Package to Applied Modeling of Hydrological Systems in Central Asia Course

title: 'riversCentralAsia: An R package for hydrological modelling' tags: - R - hydrology - modelling - Central Asia date: "3 August 2022" output: pdf_document authors: - name: Beatrice Marti orcid: "0000-0003-2089-3478" equal-contrib: yes affiliation: 1 - name: Tobias Siegfried orcid: "0000-0002-2995-9253" equal-contrib: yes affiliation: 1 bibliography: paper.bib affiliations: - name: hydrosolutions GmbH, Zurich, Switzerland index: 1

Summary

The R package riversCentralAsia includes a set of tools to facilitate and automate data preparation for hydrological modelling. It thus contributes to more reproducible modeling workflows and makes hydrological modeling more accessible to students and to interested professional modelers.

The package has been developed within the frame of a master level course on applied hydrological modelling in Central Asia and is extensively used in the open-source book Modeling of Hydrological Systems in Semi-Arid Central Asia [@CAHAM:2022]. The workflows are further validated within the Horizon 2020 project HYDRO4U [@Hydro4u:2022].

While the package has been developed for the Central Asia region, most of the functions are generic and can be used for modelling projects anywhere in the world.

The most important functionalities of the package as well as the raw data that can be processed with the package are described in the the articles of the project documentation site{target="_blank"} but the examples in the course book Modeling of Hydrological Systems in Semi-Arid Central Asia{target="_blank"} demonstrate the full range of functions available and how touse them in a workflow.

Statement of need

Data preparation comes before hydrological modelling and is actually one of the biggest work chunks in the modelling process. This package includes a number of helper functions that can be connected to efficient workflows that automatize the data preparation process for hydrological modelling as shown in the figure below.

{ width=80% }

The data preparation step includes the delineation of river catchment boundaries and the derivation of hydrological response units (HRU) using gauge locations, the SRTM digital elevation model (DEM){target="_blank"} and glacier outlines from the Randolph Glacier Inventory (RGI){target="_blank"}.

Although the High Mountain region of Central Asia is generally perceived as a data scarce region, a number of gridded data products are available that form a fair basis for regional hydrological modelling at seasonal time scales. CHELSA v2.1{target="_blank"} is a weather data product at 1 km2 by 1km2 resolution. Glacier thinning{target="_blank"} and glacier ablation{target="_blank"} are data sets from open-access literature. Data on snow water equivalents is sourced from the High Mountain Asia Snow Reanalysis (HMASR) Product{target="_blank"}, river discharge is taken from the hydrological year books of the HydroMeteorological Institutes in Central Asia, and CMIP6 climate model results area available from Copernicus{target="_blank"}.

Hydrological modelling is done using the free hydrologic-hydraulic modelling software RS Minerve. Some alternative geoprocessing workflows are described in QGIS{target="_blank"}.

The riversCentralAsia package functionality includes:

• Efficient processing of present and future climate forcing, including hydro-meterological data from Central Asia (time series and re-analysis data) and down-scaling of ERA5 re-analysis data (a more advanced topic which is described in the course book)

• The preparation of GIS layers for automated model generation and chapter Geospatial data in the course book

• Volume area scaling of glaciers

• Post-processing of simulation results, e.g. extraction and visualisation of snow water equivalent or computation of flow duration curves

• I/O interface with the hydrologic-hydraulic modelling software that allows reading and writing of input and output files of the hydraulic-hydrological modelling software RS Minerve.

While here, we focus on the description of the individual functions, the strengths of the package comes to play mostly when the functions are connected to automatize the data preparation process. These workflows are extensively documented in the book Modeling of Hydrological Systems in Semi-Arid Central Asia.

Currently, a relatively complete dataset of the Chirchik River Basin with decadal and monthly data on discharge, precipitation and temperature is included.

Related packages

The hydraulic-hydrological modelling software RS MINERVE can be accessed through Common Language Runtime (CLR) directly from within R, thus the use of the RS MINERVE GUI can be avoided and multiple runs of large models can be speed up. The github repository RSMinerveR{target="_blank"} includes examples of how to use CLR commands to use the Visual Basic interface with RS MINERVE documented in the technical manual{target="_blank}. This functionality is recommended for advanced users of RS MINERVE only.

There are a number of existing R packages available that support data preparation and hydrological modelling [@slater_using_2019]. However, apart from riversCentralAsia, there is no R package to facilitate hydrological modelling specifically with RS MINERVE which is a powerful, accessible tool for water resources management in mountainous regions.

Installation

The package has many dependencies which will be installed alongside riversCentralAsia. To successfully install the package you need prior installations of the following packages: rlang, magrittr, stringr and purrr. Should the installation fail, test if you have the following dependencies installed.

find.package(c("rlang", "magrittr", "stringr", "purrr"))

If they are not yet available on your system, please install them using the following commands.

install.packages(c("rlang", "magrittr", "stringr", "purrr"))

All other dependencies are installed automatically.

Note that Mac users may have to install the binary version of the dependency package exactextractr manually (not the more recent source version).

Note that Windows users require a working installation of RTools to install packages from github.

You can install the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("hydrosolutions/riversCentralAsia")
library(riversCentralAsia)

We recommend testing of the riversCentralAsia package before using it to make sure all dependencies integrate with the riversCentralAsia package as they should. The following step-by-step instructions explain how to do this:

1. Go to the packages github repository, click the green code button and select download zip. This will download a zip folder with the package code to your Download folder.
2. Extract the package files to a location of your preference. More detailed instructions for this step: right-click on the zip folder and select “extract all”in the pop-up window. Select a location to extract the files to and wait for the process to finish.
3. Navigate into the riversCentralAsia folder to in which the freshly downloaded package data is stored and open the riversCentralAsia R project file. This will open the project in your R GUI.
4. In the R console, type devtools::test() and hit enter. The tests will run for about a minute. If the test return [ FAIL 0 | WARN 0 | SKIP 0 | PASS 86 ] at the end, all test were successful and the package will run without problems on your system. Should one of the tests fail, please make sure all the package dependencies are up to date. If the problem persists, please file an issue including the error message you get so we can look at the problem and hopefully solve it.
5. If you don’t need the source codes any more, you can safely delete the zip file and the folder with the extracted riversCentralAsia files.

Mentions

The package is used extensively in the course book Modeling of Hydrological Systems in Semi-Arid Central Asia [@CAHAM:2022].

The workflows presented in the course book, using the riversCentralAsia package, are further validated within the Horizon 2020 project HYDRO4U [@Hydro4u:2022] where future small hydro power potential is evaluated using hydrological modelling.

For advanced R & RS Minerve users, the package RSMinverveR [@RSMinerveR:2022] is recommended which allows the interfacing between R and RS Minerve (with examples based on the Visual Basic Script examples by CREALP).

Acknowledgement

The preparation of the course book and thus the preparation of the package was financially supported by the Swiss Agency for Development and Cooperation, the German Kazakh University in Almaty and hydrosolutions.

References

hydrosolutions/riversCentralAsia documentation built on Feb. 7, 2023, 4:50 p.m.