dycdtools

NEWS code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} dycdtools 0.4.4 removed hydroGOF package dependency dycdtools 0.4.3 check for OS.type in calib_assist function neutral colour y=x in plot_scatter function update readme to highlight example data explain how to save produced figures dycdtools 0.4.2 add date format check for plotting functions add more unit tests dycdtools 0.4.1 update calib.assist function format some functions script dycdtools 0.4.0 update some functions’ name plotting functions now return an object delete some unnecessary defaults update objective function and this function is now exported for use data frame allowed to provide parameter info add more unit tests dycdtools 0.3.1 update usage of “ggsave” and some function description. dycdtools 0.3.0 update contour plot function to allow customisation of the plotted period. dycdtools 0.2.0 parallel processing algorithm added to the calibration assistant function. dycdtools 0.1.0 First release

README code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} dycdtools Overview An R package for assisting calibration and visualising outputs of DYRESM-CAEDYM. In the dycdtools package, there are two main function categories: calibration assistant and post-processing. The calibration assistant function ( calib_assist ) carries out simulations with a large number of possible combinations of parameter values that users regard as potentially suitable for their model calibration, and calculates the values of nominated objective functions (i.e., statistical measures of goodness of fit) for each combination. Based on the calculated objective function values, users can determine the optimal set(s) of parameter values or narrow the ranges of possible parameter values. NOTE: the calib_assist function can only be run on Windows as it needs to call ‘shell’ to run DYRESM-CARDYM software executables. Four post-processing functions provide multiple ways to visualise DYRESM-CAEDYM outputs as follows: Function plot_cont displays a heat map of variable values with depth within the water column and over time. This visualisation is particularly suitable for displaying temporal and depth dynamics of a variable at one lake site. Function plot_prof shows vertical profiles of the simulation and corresponding observations, for all dates where observations are available. Function plot_ts plots simulated values and observations for a specified variable and depth over time. It can be used to compare temporal changes of a variable for simulations and observations at specific depths. Function plot_scatter shows observations against simulated values for corresponding time and depth, with a colour scale representing measured depths. It can be used to demonstrate visually the goodness of fit for a variable across the water column. For a detailed tutorial of how to use these functions, readers are referred to a peer-reviewed paper by the developers. IMPORTANT: It is highly recommended that first-time users of the package first run the package functions (particularly’calib_assist’) on the provided example data (see below the Application Section) to familiarise themselves. Installation To install the latest development version run the following code: # install devtools install.packages("devtools") # install dycdTools package devtools::install_github("SongyanYu/dycdtools") # Remove the package zip after installation unlink("dycdtools.zip") Application Below is a minimal case study example. The example data supporting the case study can be accessed via: https://doi.org/10.5281/zenodo.7431128 The calibration assistant function - calib_assist Assume that you want to calibrate three model parameters: wind stirring efficiency, vertical mixing coefficient, and light extinction coefficient and each parameter have 4 possible values. The calib_assis function can be used to call DYRESM-CAEDYM to run for all possible combinations (n = 64) of the three parameters’ values. For each model run, the objective function Nash-Sutcliffe Efficiency (NSE) coefficient is calculated for temperature simulations. library(dycdtools) calib_assist(cal.para = "calibration_data/Calibration_parameters.csv", combination = "all", model.var = c("TEMP"), obs.data = "calibration_data/Obs_data_template.csv", objective.function = c("NSE"), start.date = "2002-01-23", end.date = "2016-12-31", dycd.wd = "calibration_data/DYRESM_CAEDYM_Lake-Okareka/", dycd.output = "calibration_data/DYRESM_CAEDYM_Lake-Okareka/DYsim.nc", file.name = "calibration_data/Calibration_outputs.csv", write.out = TRUE, parallel = TRUE, verbose = TRUE) Visualise calibration results Use a heatmap to visualise the calculated NSE values for all 64 model runs. # Read in model calibration results calibration <- read.csv("calibration_data/Calibration_outputs.csv") # Heat map library(ggplot2) ggplot(calibration, aes(x = wse,y = vmc,fill = NSE.TEMP)) + geom_tile() + scale_fill_distiller(palette = "PuBu", direction = 1) + facet_wrap(~lec, scales = "free") + xlab("Wind stirring efficiency") + ylab("Vertical mixing coefficient") + labs(title = "Light extinction coefficient", fill = "NSE") + theme_bw() + theme(plot.title = element_text(size = 11, hjust = 0.5)) Post-processing functions Based on the 64 model runs, you can select a particular parameter value combination that generate the best performance (measured by NSE) and rerun DYRESM-CAEDYM for that particular parameter values. After that, you can use the post-processing functions in the dycdtools package to visualise the outputs of the calibrated model. # Extract temperature simulations var.values <- ext_output(dycd.output = "DYCD_Okareka/DYsim.nc", var.extract = c("TEMP")) # Interpolation of temperature across water column at an interval of 0.5 m temp.interpolated < -interpol(layerHeights = var.values$dyresmLAYER_HTS_Var, var = var.values$dyresmTEMPTURE_Var, min.dept = 0, max.dept = 33, by.value = 0.5) # Read in observed water quality data library(lubridate) obs.okareka <- read.csv("plotting_data/Obs_data_template.csv") obs.okareka$Date <- as.Date(obs.okareka$Date,format="%d/%m/%Y") # subset observed data to remain temperature observations obs.temp <- obs.okareka[, c('Date','Depth','TEMP')] # Contour plot plot_cont_com(sim = temp.interpolated, obs = obs.temp, plot.start = "2002-01-23", plot.end = "2006-12-31", sim.start = "2002-01-23", sim.end = "2016-12-31" legend.title = "T\n(\u00B0C)", min.depth = 0, max.depth = 33, by.value = 0.5, nlevels = 20) # Profile plot plot_prof(sim = temp.interpolated, obs = obs.temp, sim.start = "2002-01-23", sim.end = "2016-12-31", plot.start = "2002-01-23", plot.end = "2002-12-31", min.depth = 0, max.depth = 33, by.value = 0.5, xlabel = "Temperature \u00B0C") # Time series plot plot_ts(sim = temp.interpolated, obs = obs.temp, target.depth = c(1, 14, 30), sim.start = "2002-01-23", sim.end = "2016-12-31", plot.start = "2002-01-23", plot.end = "2012-12-31", min.depth = 0, max.depth = 33, by.value = 0.5, ylabel = "Temperature \u00B0C") # Scatter plot plot_scatter(sim=temp.interpolated, obs=obs.temp, sim.start="2002-01-23", sim.end="2016-12-31", plot.start = "2002-01-23", plot.end="2012-12-31", min.depth = 0, max.depth = 33, by.value = 0.5) Developer contact Songyan (sunny) Yu: sunny.yu@griffith.edu.au

Help for package dycdtools const macros = { "\\R": "\\textsf{R}", "\\mbox": "\\text", "\\code": "\\texttt"}; function processMathHTML() { var l = document.getElementsByClassName('reqn'); for (let e of l) { katex.render(e.textContent, e, { throwOnError: false, macros }); } return; } Package {dycdtools} Contents calib_assist change_input_file delete_space ext_output hgt_to_dpt interpol objective_fun obs_temp output_name plot_cont plot_cont_comp plot_prof plot_scatter plot_ts run_iteration Title: Calibration Assistant and Post-Processing Tool for Aquatic Ecosystem Model DYRESM-CAEDYM Version: 0.4.4 Description: Dynamic Reservoir Simulation Model (DYRESM) and Computational Aquatic Ecosystem Dynamics Model (CAEDYM) model development, including assisting with calibrating selected model parameters and visualising model output through time series plot, profile plot, contour plot, and scatter plot. For more details, see Yu et al. (2023) https://journal.r-project.org/articles/RJ-2023-008/ . URL: https://github.com/SongyanYu/dycdtools License: MIT + file LICENSE Encoding: UTF-8 LazyData: true Imports: dplyr, ncdf4, tidyr, ggplot2, RColorBrewer, lubridate, R.utils, parallel RoxygenNote: 7.2.2 Depends: R (≥ 2.10) Suggests: testthat (≥ 3.0.0) Config/testthat/edition: 3 NeedsCompilation: no Packaged: 2024-09-08 22:11:46 UTC; s2974665 Author: Songyan Yu [aut, cre], Christopher McBride [ctb], Marieke Frassl [ctb] Maintainer: Songyan Yu <yusongyan1989@gmail.com> Repository: CRAN Date/Publication: 2024-09-11 14:50:02 UTC Assist calibration of DYRESM-CAEDYM model. Description This function carries out simulations with a large number of possible combinations of parameter values that users regard as potentially suitable for their model calibration, and calculates the values of nominated objective functions (i.e., statistical measures of goodness of fit) for each combination. Based on the calculated objective function values, users can determine the optimal set(s) of parameter values or narrow the ranges of possible parameter values. Usage calib_assist( cal.para, combination = "random", n, model.var, phyto.group = NA, obs.data, objective.function = c("NSE", "RMSE"), start.date, end.date, dycd.wd, dycd.output, file.name, verbose = TRUE, parallel = FALSE, n.cores = NULL, write.out = TRUE ) Arguments cal.para a data frame or a character string naming an external .csv file where below column names are mandatory: "Parameter" describing parameter names (abbreviation is allowed), "Min", "Max", and "Increment" describing the minimum and maximum parameter values and expected increment in the value range, "Input_file" and "Line_NO" listing in which configuration file at which line the parameter can be found. combination a vector of string character of how to pick up combinations of parameter values. "random" - the function randomly picks up a given number of combinations; "all" - the function tries all possible combinations of parameter values. n the number of random selections. Must be provided if combination = "random". model.var a vector of string character of modelled variables for calibration. the character should be from the 'var.name' column of 'data(output_name)'. Note that if model calibration needs to regard chlorophyll of multiple phytoplankton groups as a whole, model.var should use "CHLA" and individual phytoplankton group should be specified through the "phyto.group" argument. If phytoplankton groups are separately calibrated, simply list their character in this argument (model.var). phyto.group a vector of simulated phytoplankton groups, including CHLOR, FDIAT, NODUL, CYANO and CRYPT. obs.data a data frame or a character string naming a csv file of observed lake data. The observed lake data need to include below columns: 1) 'Date' in format of "%Y-%m-%d" 2) 'Depth' (integer) 3) Water quality variables (use string characters of model var as column names). see example data 'data(obs_temp)'. objective.function a vector of string character describing which objective function(s) to be used for calibration. Selected from the following five functions: "NSE": Nash-Sutcliffe efficiency coefficient, "RMSE": Root Mean Square Error, "MAE": Mean Absolute Error, "RAE": Relative Absolute Error, "Pearson": Pearson's r. start.date , end.date the beginning and end simulation dates for the intended DYRESM-CAEDYM calibration. The date format must be "%Y-%m-%d". The two dates should be consistent with model configurations. dycd.wd the directory where input files (including the bat file) to DYRESM-CAEDYM are stored. dycd.output a character string naming the output file of model simulation. file.name a character string naming a .csv file where the results of this function are written to. Needed if 'write.out' = TRUE. verbose if TRUE, model calibration information is printed. parallel if TRUE, the calibration process is run on multiple cores. n.cores When 'parallel' is TRUE, n.cores is the number of cores the calibration function will be run on. If not provided, the default value is the number of available cores on the computer -1. write.out if TRUE, model calibration results are saved in a file with a file name set by the "file.name" argument. Value a data frame of all tested values of parameters and corresponding values of the objective function(s). Note No executable examples are provided to illustrate the use of this function, as this function relies on the DYRESM-CAEDYM executables to work. Change parameter value of input files to DYRESM_CAEDYM model. Description Change parameter value of input files to DYRESM_CAEDYM model. Usage change_input_file(input_file, row_no, new_value) Arguments input_file vector of input format, such as "par","cfg". row_no the number of row where the variable of interest is in the input file. new_value the new value that will be assigned to the variable of interest. Value updated input_file with a new value to a parameter. Delete all whitespace until a non-whitespace character. Description Delete all whitespace until a non-whitespace character. Usage delete_space(extract_val) Arguments extract_val a vector. Extract outputs from a DYRESM-CAEDYM model run Description Extract simulation outputs from a DYRESM-CAEDYM model run. Usage ext_output(dycd.output, var.extract, verbose = FALSE) Arguments dycd.output a string of characters describing the file path to the output netcdf file of DYRESM-CAEDYM model. var.extract a vector of variables to be extracted from the output. Please refer to the var.name of data(output_name) for accepted variable name. Apart from the user nominated variables, simulation period and layer height data are also extracted. verbose if TRUE, the information about the extraction process is printed. Value a list of values of those variables of interest, as well as two compulsory variables (i.e. simulation period, layer height) Examples # extract simulated temperature values from DYRESM-CAEDYM simulation file var.values<-ext_output(dycd.output=system.file("extdata", "dysim.nc", package = "dycdtools"), var.extract=c("TEMP")) for(i in 1:length(var.values)){ expres<-paste0(names(var.values)[i],"<-data.frame(var.values[[",i,"]])") eval(parse(text=expres)) } convert from height to depth Description convert from height to depth Usage hgt_to_dpt(height) Arguments height a vector of height profile Interpolation of DYRESM-CAEDYM simulation results across a series of user-defined depths. Description The default simulation results of a water quality variable from DYRESM-CAEDYM are usually at irregular layer heights. This function convert it to a data frame with regular layer heights through interpolation. Usage interpol(layerHeights, var, min.depth, max.depth, by.value) Arguments layerHeights layer heights, outputs from a DYRESM-CAEDYM model run, and can be generated with the 'ext_output' function. var simulation results of a water quality variable and can also be generated with the 'ext_output' function. min.depth , max.depth , by.value minimum and ma