In mkoohafkan/RAStestR: Functions for testing RAS outputs

knitr::opts_chunk$set(eval = FALSE)

Introduction

RAStestR provides tools for producing RAS sediment model validation reports. The most common use case is to verify that outputs of a particular unsteady or quasi-unsteady sediment transport model are consistent across RAS versions, or to compare the effects of model simplification (e.g. converting a fully-unsteady model to a quasi-unsteady model).

Generating a RAStestR report

The function generate_report can be used to create reports from the sediment output data file. The general the workflow is:

1. Create two copies of the project folder.
2. Run the project in the first folder with the current or base version of HEC-RAS.
3. Run the project in the second folder with the new version of HEC-RAS.
4. Decide which output tables you want to analyze, and which stations, time stamps and/or grain size classes to analyze.
5. Call generate_report from R and produce a pdf or html report.

Use case 1: comparing RAS version outputs of a simple model

Consider the quasi-unsteady model "Simple Sediment Transport Example" provided in the HEC-RAS example projects download. Imagine that we want to verify that the outputs generated by HEC-RAS version 5.03 are the same as those generated by version 5.0. First, we make two copies of the project folder and label them appropriately, e.g. C:/example/RAS_50 and C:/example/RAS_503. Follow the steps below to generate a report.

Run the models

First, start RAS 5.0 and run the model in the RAS_50 folder, which will produce the output file C:/example/RAS_50/MBex.p04.hdf. Next, start RAS 5.03 and run the model in the RAS_503 folder, which will produce the file C:/example/RAS_503/MBex.p04.hdf.

Decide which tables to analyze

In most cases you will already have some idea of what tables you want to analyze, based on what functionality you are trying to test or if you are trying to hunt down a specific bug. For this example, we will choose to look at Water Surface, Invert Elevation, and Long. Cum Mass Change outputs. Note that Long. Cum Mass Change tables are produced for every grain size class; however, this example specifies only one grain size class. We will look at all stations and time stamps for the first two tables, but will restrict our investigation od the third table to total mass on 01JUL1975 23:45:36.

Generate the report

The R code below can be used to generate the report described in the previous section. Note the following items:

• In the HDF output file, grain size classes are assigned numeric indices, with the total mass table having no index. The table "Long. Cum Mass Change" refers to the total longitudinal cumulative mass change, while e.g. "Long. Cum Mass Change 1" refers to the first grain size class. To generate a report using the total mass, we specify which.grains = "" in the sediment.options argument.
• Time stamps, stations and grain classes must be specified as character values.
• The table labels are not case sensitive, but they are punctuation sensitive. The table "Long. Cum Mass Change" is recognized, but "Long Cum Mass Change" is not.

library(RAStestR)

base.file = "C:/example/RAS_50/MBex.p04.hdf"
base.label = "RAS 5.0"

new.file = "C:/example/RAS_503/MBex.p04.hdf"
new.label = "RAS 5.03"

tables = c("Water Surface", "Invert Elevation", "Long. Cum Mass Change")
sediment.options = list(which.times = "01JUL1975 23:45:36", which.grains = "")

generate_report(base.file, new.file, "quasi", "quasi", base.label, new.label,
  sediment.opts = sediment.options)

Use case 2: Sensitivity analysis of time step

Another common scenario is evaluating the impact of temporal discretization. This use case would proceed in the same manner as the previous section, except that the user can simply create a second plan in the HEC-RAS model rather than needing to copy the entire project folder.

Use case 3: Conversion from quasi-unsteady to fully-unsteady

The package can also be used to test differences in model output following a conversion from a quasi-unsteady model to a fully-unsteady model. The most important difference is that the user must ensure that the output time series of the quasi-unsteady model and fully-unsteady model match. Provided this is done, the comparison can proceed as in the previous section, specifying a run type of "unsteady" or "quasi" where appropriate.

Using RAStestR interactively

RAStestR can also be used interactively to import data from the sediment data file and compute differences and RMSE. The two functions read_standard and read_sediment can be used to pull sediment data into R. The functions diff_standard and diff_sediment are used to compute absolute differences in output values between two tables, and the function rmse_table can be used to compute RMSE. Table-sepcific helper functions are also provided to streamline the process by assuming certain input and output structures. For example, to generate the RMSE values for Water Surface at each station one can do:

d1 = read_water_surface(base.file, "quasi")
d2 = read_water_surface(new.file, "quasi")
d.diff = diff_water_surface(d1, d2)
rmse_water_surface(d.diff, "Station")

Exporting data from RAStestR

For users who are not familiar with R, manipulating data with RAStestR can be daunting. This document describes how to export data from RAStestR to other programs like Microsoft Excel.

By default, RAStestR maintains data according to the format in the HDF files, i.e. each station gets its own column. This format is often referred to as "wide table" format. However, this may not be a useful format when working with data in Excel. For example, it may be easier to plot a longitudinal cumulative mass change curve if the station IDs are in one column and the actual data is in a second column. Tables in this format are referred to as key-value format or "long table" format. RAStestR provides the functions to_longtable and to_widetable for converting between long table and wide table formats.

Example 1: export water surface data to Excel

Using the HDF files described in the previous section, this example shows how to export water surface data in long format to Excel. The function data_to_clipboard copies the RAStestR data to the clipboard, at which point the data can be pasted directly into Excel:

# read in the water surface data
d = read_water_surface(base.file, "quasi")
# convert the data to long table format
ld = to_longtable(d, data.col = "WSE", station.col = "station")
# write data to clipboard for pasting into Excel
data_to_clipboard(ld)

Note that the data is written to the clipboard in comma-seperated value format.

Example 2: export water surface data from two runs

A user may want to plot the results from multiple runs as separate series on the same plot in Excel. While you could export multiple runs to Excel individually and manually line them up in Excel, RAStestR provides the function combine_data to merge the results of multiple runs into a single data table. You can combine this with the functions to_longtable and to_widetable to export data in a format that can be immediately plotted:

# read in the water surface data from a "base" run
d1 = read_water_surface(base.file, "quasi")
# read in the water surface data from a "new" run
d2 = read_water_surface(new.file, "quasi")
# convert the data to long table format
ld1 = to_longtable(d1, data.col = "WSE", station.col = "station")
ld2 = to_longtable(d2, data.col = "WSE", station.col = "station")
# combine the data using useful names
d = combine_data(base = ld1, new = ld2, label = "run")
# convert to wide table format with columns being the different runs
wd = to_widetable(d, key.col = "run", value.col = "WSE")
# write data to clipboard for pasting into Excel
data_to_clipboard(wd)

This results in the station IDs in one column and the data from each run in seperate columns.

Example 3: Transposing data

You can also use to_longtable and to_widetable to reformat data in other ways. For example, perhaps you want to transpose the data so that each column is a seperate time and stations are in rows:

d = read_water_surface(base.file, "quasi")
# convert the data to long table format
ld = to_longtable(d, data.col = "WSE", station.col = "station")
wd = to_widetable(ld, key.col = "Time", value.col = "WSE")
# write data to clipboard for pasting into Excel
data_to_clipboard(wd)

Alternatively, you may want to combine multiple variables from the same run and plot them as series on the same plot:

d.wse = read_water_surface(base.file, "quasi")
d.ie = read_invert_elevation(base.file, "quasi")
# convert the data to long table format
ld.wse = to_longtable(d.wse, data.col = "value", station.col = "station")
ld.ie = to_longtable(d.ie, data.col = "value", station.col = "station")
# combine the data using useful names
d = combine_data(WSE = ld.wse, INVERT = ld.ie, label = "variable")
# convert to wide table format with columns being the different data
wd = to_widetable(d, key.col = "variable", value.col = "value")
# write data to clipboard for pasting into Excel
data_to_clipboard(wd)

Which results in a data table with water surface elevation in one column and invert elevation in another column.

The data transposing functions can also be used to map individual grain classes to seperate columns:

d = read_mass_in(base.file, "quasi", which.times = "01JUL1975 23:45:36")
# convert the data to long table format
ld = to_longtable(d, data.col = "massin", station.col = "station")
# convert to wide table format with columns as grain classes
wd = to_widetable(ld, key.col = "GrainClass, value.col = "massin")
# write data to clipboard for pasting into Excel
data_to_clipboard(wd)

Which results in a data table with each grain class in a separate column. Note that this can get messy if you have multiple times and multiple stations.

mkoohafkan/RAStestR documentation built on July 14, 2019, 11:41 p.m.