In dof1985/cwatm4r: What the Package Does (One Line, Title Case)

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Introduction

The Community Water Model (CWatM) allows the assessment of water supply and human and environmental water demands at both global and regional levels. The model was developed by the Water Research Group in the International Institute for Applied System Analysis (IIASA).

`cwatm4r` provides an interface to set up and run hydrological simulations using CWatM. It also has data preparation and post-processing capacities.

Download & Install CWatM

Future development

Getting started

The settings file allows the user to control CWatM's modules and change its behaviour. `cwatm4r` provides tools to explore, modify and export the settings file from within `R` or via an MS Excel spreadsheet. wzxhzdk:1

Explore the settings file

The settings file is split into different sections which cwatm4r refer to as domains. The getSettingsDomains() function print a vecotr with all domain names.

getSettingsDomains()

The users can explore the settings of each domain by using the getSettingsTable() function.
For example, the following call explores the settings of the FILE_PATHS section of the default settings file. The output from this function is a data.frame with 3 columns defining: the model's variable, its value, and in some cases additional information as a comment. The FILE_PATHS domain specify the path to the model files, inputs, and outputs.

getSettingsTable(domain = "FILE_PATHS") %>% head(3)

Running CWatM for the first time

The easiest way for an initial set up of CWatM settings is by using a spreadsheet. The settings_list2spreadsheet() function creates a default settings spreadsheet in a user defined folder.

# define the path to the model files
out_settings <- "./my_cwatm_simulations/settings.xlsx"

# export the default settings file to "./cwatm_model/cwatm_settigns/cwatm_settings.xlsx"
settings_list2spreadsheet(output_path = out_settings) 

The default behaviour is to use a pre-saved template to generte the settings file, but the user can use an existing `settings.ini` file as a template instead, by converting it into a named `list` with the `settings_ini2list()` function. wzxhzdk:5

The `settings.xlsx` provides a convinient way to define all model's parameters at once. However, CWatM still requires an `.ini` settings' file. The `settings_spreadsheet2ini()` allows the user to convert a settings spreadsheet to an `.ini` file. wzxhzdk:6

Now all is set for a first CWatM run. The user can call the model with the `call_cwatm()`.

call_cwatm(settingsfile = "./my_cwatm_simulations/settings.ini") 

The user pass optional arguments to the `system()` function using the `...` argument. For example, as a default behaviour, CWatM runs quietly within `R`. Using `intern = TRUE` changes this behabiour, so the command-line outputs are captured and printes as an `R` character vector. For additional options see `?system`.

# This model will run loudly
call_cwatm(settingsfile = "./my_cwatm_simulations/settings.ini", intern = TRUE) 

The user can also skip the `settings_spreadsheet2ini()` step and run the model using the settings spreadsheet. In this case, the `call_cwatm()` function will create a settings file using the combination of the spreadsheet file name and a unique date-time identifier (E.g., cwatm_settings_20212904102753.ini) as a naming convention.

call_cwatm(settingsfile = "./cwatm_model/cwatm_settigns/cwatm_settings.xlsx")

Modyfing the settings file from within R

1. What is a changeset?
2. Create your first changeset
3. Create your first changeset
4. From a changeset to a new settings file
5. Use a loop to create multiple settings files

END OF VIGNETTE

dof1985/cwatm4r documentation built on Nov. 8, 2022, 7:30 p.m.