| Title: | R Package for Optimisation Simulations for Rainwater Management Simulations Performed with Calculation Engine Provided by Tandler |
|---|---|
| Description: | R Package for Optimisation Simulations for Rainwater Management Simulations Performed With Calculation Engine Provided by Tandler. |
| Authors: | Michael Rustler [aut, cre] (ORCID: <https://orcid.org/0000-0003-0647-7726>), RAINDROP [fnd], Kompetenzzentrum Wasser Berlin gGmbH (KWB) [cph] |
| Maintainer: | Michael Rustler <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.0.0.9000 |
| Built: | 2026-06-14 19:39:49 UTC |
| Source: | https://github.com/KWB-R/kwb.raindrop |
Computes (i) overflow event statistics from the element outflow time series and
(ii) water-balance components as percent shares for both element and
connected_area per scenario.
add_overflow_events_and_waterbalance( simulation_results, event_separation_hours = 4, canonical_variables = NULL )add_overflow_events_and_waterbalance( simulation_results, event_separation_hours = 4, canonical_variables = NULL )
simulation_results |
Named list of scenario results. Each entry is expected to contain:
|
event_separation_hours |
Numeric. Minimum time between two overflow events
(in hours). Defaults to |
canonical_variables |
Optional |
Water-balance percentages are computed with sign preserved (value / denom):
element denominator: WB_Regen + abs(WB_Oberflaechenablauf_Verschaltungen)
connected_area denominator: WB_Regen (fallback to
abs(WB_Oberflaechenablauf_Verschaltungen) if WB_Regen is NA or 0)
Overflow events are derived from positive Oberflaechenablauf_Ueberlauf values
using kwb.event::hsEvents(). Assuming the overflow rate is in mm/h, event
sums (in mm) are obtained by integrating each sample over its local
time step (time[i+1] - time[i]; the last sample inherits the previous
step). A warning is emitted if the time step is non-uniform, and
sum_overflows is returned as NA if it cannot be determined (single
sample).
Missing components are tolerated: scenarios whose entry in simulation_results
is NULL (or which lack any of element, element$water_balance,
connected_area, connected_area$water_balance or element$rates) still
produce a row of the output tibble. The four "headline" columns (s_name,
n_overflows, median_duration_overflows_hours, sum_overflows) are
always present and filled with NA where they cannot be computed.
For the element.*_ and connectedarea.*_ water-balance columns: if one
side is missing in a given scenario but the other side has data, a stub of
NA-filled columns is fabricated for the missing side by mirroring the
populated side's variable names. This preserves the table's column
structure when, for example, every run disables roof ET (so the engine
skips writing Dach.h5 and every scenario has connected_area = NULL):
the connectedarea.*_ columns are kept and filled with NA, instead of
being dropped from the output entirely. The mirror is a best-effort hint
for the user, not a guarantee that the names match what a populated
connected_area would have produced.
A tibble with one row per scenario containing:
s_name
n_overflows
median_duration_overflows_hours
sum_overflows
water-balance percentage columns for element.*_ and connectedarea.*_
## Not run: out <- add_overflow_events_and_waterbalance(simulation_results) out <- add_overflow_events_and_waterbalance( simulation_results, event_separation_hours = 6 ) ## End(Not run)## Not run: out <- add_overflow_events_and_waterbalance(simulation_results) out <- add_overflow_events_and_waterbalance( simulation_results, event_separation_hours = 6 ) ## End(Not run)
Given a parameter grid that drives the simulation, attach a per-scenario
breakdown of construction costs plus a cost_total column suitable for
filtering / sorting in the results datatable.
compute_costs( param_grid, storage_type = c("infiltration_box", "gravel_trench"), cost_rates = default_cost_rates() )compute_costs( param_grid, storage_type = c("infiltration_box", "gravel_trench"), cost_rates = default_cost_rates() )
param_grid |
|
storage_type |
|
cost_rates |
|
Required columns in param_grid:
mulde_area — element footprint area in m²
mulde_height — surface depression depth in mm
filter_height — soil-filter layer thickness in mm
storage_height — storage layer thickness in mm
Optional column storage_type (character: "infiltration_box" or
"gravel_trench") selects the per-scenario storage rate. If absent, the
value of the storage_type argument is used for every row.
Cost formulas (Leimgruber, 2026-03-27):
cost_excavation = mulde_area * (mulde_h + filter_h + storage_h)/1000 * 70 cost_profiling = mulde_area * 10 cost_filter = mulde_area * filter_h/1000 * 200 cost_storage = mulde_area * storage_h/1000 * <350 | 50> cost_total = sum of the four above
The input param_grid with the columns storage_type,
cost_excavation, cost_profiling, cost_filter,
cost_storage, cost_total (all in EUR) appended.
grid <- tibble::tibble( scenario_name = c("s00001", "s00002"), mulde_area = c(50, 50), mulde_height = c(300, 300), filter_height = c(300, 300), storage_height = c(600, 600) ) # Infiltration box (default) compute_costs(grid) # Gravel trench compute_costs(grid, storage_type = "gravel_trench") # Per-scenario storage type compute_costs(dplyr::mutate(grid, storage_type = c("infiltration_box", "gravel_trench")))grid <- tibble::tibble( scenario_name = c("s00001", "s00002"), mulde_area = c(50, 50), mulde_height = c(300, 300), filter_height = c(300, 300), storage_height = c(600, 600) ) # Infiltration box (default) compute_costs(grid) # Gravel trench compute_costs(grid, storage_type = "gravel_trench") # Per-scenario storage type compute_costs(dplyr::mutate(grid, storage_type = c("infiltration_box", "gravel_trench")))
Returns the list of water-balance scalar names the Tandler
"Regenwasserbewirtschaftung" engine writes into the Wasserbilanz
group of each result HDF5 (without the element. / connectedarea.
prefix and without the trailing _ that
add_overflow_events_and_waterbalance() appends when building the
output columns). Pass this to that function's canonical_variables
argument to keep the expected water-balance column structure visible
in the rendered datatable even when every scenario in a batch is
NULL (e.g. the engine returns Status 1 for every input and writes
no result HDF5).
default_canonical_wb_variables()default_canonical_wb_variables()
A character() vector of variable names.
Values observed in the May 2026 432-row Wien sweep (Michael Rustler)
and referenced explicitly by plot_wb_tradeoff_overflows().
default_canonical_wb_variables()default_canonical_wb_variables()
Returns the default Austrian unit-cost rates used by compute_costs().
Rates were provided by Johannes Leimgruber (OeStaP) on 2026-03-27 for the
RAINDROP cost-optimisation work.
default_cost_rates()default_cost_rates()
A named list of rates in EUR per m² or m³:
excavation_eur_per_m3, profiling_eur_per_m2,
filter_eur_per_m3, infiltration_box_eur_per_m3,
gravel_trench_eur_per_m3.
Aushub (excavation, incl. loading + transport): 70 EUR/m³
Profilierung und Begrünung (profiling + greening): 10 EUR/m²
Bodenfilter (soil filter, incl. installation): 200 EUR/m³
Sickerbox (infiltration box, incl. installation): 350 EUR/m³
Schotterrigol (gravel trench, incl. installation): 50 EUR/m³
Fetches the Windows executable from the corresponding GitHub Release of
the companion KWB-R/kwb.raindrop.binaries repository and caches it
under a per-version sub-directory of the user cache. Subsequent calls
are no-ops once the file is present.
download_engine( version = default_engine_version(), cache_dir = tools::R_user_dir("kwb.raindrop", "cache"), force = FALSE )download_engine( version = default_engine_version(), cache_dir = tools::R_user_dir("kwb.raindrop", "cache"), force = FALSE )
version |
|
cache_dir |
|
force |
|
Releases in KWB-R/kwb.raindrop.binaries follow the tag scheme
engine-<version> and contain a single asset named
Regenwasserbewirtschaftung.exe (the version is encoded in the
tag, not in the filename, so multiple engine versions can coexist
side-by-side in the cache).
The executable is a Windows binary; on non-Windows platforms the file is
still downloaded but cannot be executed directly. The function does not
validate the download with a checksum — pin a specific version to
guarantee reproducibility.
character(1) — absolute path to the cached .exe.
## Not run: exe <- download_engine() exe <- download_engine("2026-02-24") ## End(Not run)## Not run: exe <- download_engine() exe <- download_engine("2026-02-24") ## End(Not run)
Identifies rows that differ from a reference in exactly one parameter.
You may pass param_cols explicitly, or let the function infer them by
excluding id_col, exclude_cols, and any columns matching
exclude_cols_regex (default excludes result columns like h_*).
find_single_param_variations( data, ref_scenario = "s00001", id_col = "scenario_name", param_cols = NULL, exclude_cols = NULL, exclude_cols_regex = "^h_", tol = 1e-09, quiet = FALSE, include_reference = c("per_param", "none") )find_single_param_variations( data, ref_scenario = "s00001", id_col = "scenario_name", param_cols = NULL, exclude_cols = NULL, exclude_cols_regex = "^h_", tol = 1e-09, quiet = FALSE, include_reference = c("per_param", "none") )
data |
A data frame with scenarios. |
ref_scenario |
Reference scenario ID (default |
id_col |
Name of the scenario ID column (default |
param_cols |
Optional character vector of parameter columns. If |
exclude_cols |
Character vector to exclude from parameter detection. |
exclude_cols_regex |
Regex to auto-exclude non-parameter columns (default |
tol |
Numeric tolerance for numeric comparisons (default |
quiet |
Logical; print diagnostics if |
include_reference |
|
A data frame with columns: id_col, param_name, param_value,
is_reference. Attributes: "param_cols", "ref_row", "diff_mat", "n_diff".
Reads per-run result files (HDF5) for both the measure element and the connected area results and returns a named list (one entry per simulation).
get_simulation_results_all(paths, path_list, simulation_names, debug = TRUE)get_simulation_results_all(paths, path_list, simulation_names, debug = TRUE)
paths |
A list of path definitions. Used for messaging and expected to
contain |
path_list |
A list passed to |
simulation_names |
Character vector of simulation run identifiers
(e.g. |
debug |
print debug messages (default: TRUE) |
For each simulation name (e.g. "s00001"), the function resolves the run
directory via kwb.utils::resolve(path_list, dir_target = s_name) and
then loads standard result groups from two HDF5 files:
element: Metainfo, Raten, Wasserbilanz, Zustandsvariablen
connected_area: Metainfo, Raten, Wasserbilanz, Zustandsvariablen
If either of the expected HDF5 files is missing for a run, the corresponding
list entry will be NULL.
The function uses hdf5r::H5File$new(..., mode = "r") to open the files.
The HDF5 handles are not explicitly closed; depending on your workflow, you
may want to close them (see hdf5r::H5File$close_all() / $close()).
A named list with one entry per simulation_names. Each entry is
either NULL (missing files) or a nested list:
Data.frame/list of scalar metadata (from Metainfo).
Time series table (from Raten).
Scalars table (from Wasserbilanz).
Time series table (from Zustandsvariablen).
Same structure as element, read from the area HDF5.
resolve,
read_hdf5_scalars,
read_hdf5_timeseries
Reads per-run result files (HDF5) for both the measure element and the connected area results and returns a named list (one entry per simulation).
get_simulation_results_optim(paths, path_list, simulation_names, debug = TRUE)get_simulation_results_optim(paths, path_list, simulation_names, debug = TRUE)
paths |
A list of path definitions. Used for messaging and expected to
contain |
path_list |
A list passed to |
simulation_names |
Character vector of simulation run identifiers
(e.g. |
debug |
print debug messages (default: TRUE) |
For each simulation name (e.g. "s00001"), the function resolves the run
directory via kwb.utils::resolve(path_list, dir_target = s_name) and
then loads standard result groups from two HDF5 files:
element: Metainfo, Raten, Wasserbilanz, Zustandsvariablen
connected_area: Metainfo, Raten, Wasserbilanz, Zustandsvariablen
If the element HDF5 is missing the entry is NULL; if only the
connected-area HDF5 is missing, the entry is a list with the
element side populated and connected_area = NULL.
HDF5 handles are closed on exit via on.exit(...$close_all()).
The function uses hdf5r::H5File$new(..., mode = "r") to open the files
and registers an on.exit(...$close_all()) so handles are released even
when the iteration body errors out.
A named list with one entry per simulation_names. Each entry is
either NULL (element HDF5 missing) or a nested list:
Data.frame/list of scalar metadata (from Metainfo).
Time series table (from Raten).
Scalars table (from Wasserbilanz).
Time series table (from Zustandsvariablen).
Same structure as element, read from the
connected-area HDF5, or NULL if that file is missing for the run.
resolve,
read_hdf5_scalars,
read_hdf5_timeseries
Parallel variant of get_simulation_results_optim() using
future.apply::future_lapply() including optional progress reporting
via progressr.
get_simulation_results_optim_parallel( paths, path_list, simulation_names, debug = TRUE, workers = NULL, show_progress = TRUE, future_seed = TRUE, progress_handler = progressr::handler_txtprogressbar )get_simulation_results_optim_parallel( paths, path_list, simulation_names, debug = TRUE, workers = NULL, show_progress = TRUE, future_seed = TRUE, progress_handler = progressr::handler_txtprogressbar )
paths |
A list of path definitions. Used for messaging and expected to
contain |
path_list |
A list passed to |
simulation_names |
Character vector of simulation run identifiers
(e.g. |
debug |
print debug messages (default: TRUE) |
workers |
Optional number of parallel workers. If not NULL,
a temporary |
show_progress |
Logical (default TRUE). |
future_seed |
Passed to |
progress_handler |
A progressr handler function (default:
|
Named list (see get_simulation_results_optim). As with
the non-parallel sibling, the entry for a run is NULL only when the
element HDF5 is missing; a missing connected-area HDF5 yields a partial
result with connected_area = NULL.
Creates missing groups along the path and then creates the dataset. Designed for RAINDROP input files where missing scalar parameters can crash the model definition reader.
h5_ensure_dataset(h5, path, value, dtype = NULL, dims = NULL)h5_ensure_dataset(h5, path, value, dtype = NULL, dims = NULL)
h5 |
Open |
path |
Absolute dataset path (e.g. "/Berechnungsparameter/Zeitschritt_Verschaltungen"). |
value |
Initial value to write after creation (scalar, vector, matrix, or 2-col TS). |
dtype |
Optional. Either an |
dims |
Optional integer vector. If NULL, inferred from |
Invisibly TRUE
Creates missing groups and datasets for all names(values). Datasets are created with dtype/dims inferred from the corresponding value. No values are written here.
h5_ensure_datasets_from_values( h5, values, ts_cols = c("time", "value"), ts_layout = c("2xN", "Nx2"), ts_dtype = "double", strict = TRUE )h5_ensure_datasets_from_values( h5, values, ts_cols = c("time", "value"), ts_layout = c("2xN", "Nx2"), ts_dtype = "double", strict = TRUE )
h5 |
Open hdf5r::H5File (mode "a" or "r+"). |
values |
Named list; names are dataset paths (leading // allowed). |
ts_cols |
Character(2). Column names for TS (default time/value). |
ts_layout |
One of "2xN" or "Nx2". For RAINDROP typically "2xN" in HDF5. |
ts_dtype |
Either an H5T object or a string ("double","integer","logical","float"). |
strict |
Stop if creation fails. |
Invisibly, the character vector of created dataset paths.
Read values of all (or selected) datasets
h5_read_values( h5, paths = NULL, simplify_scalars = TRUE, timeseries_as_tibble = TRUE, ts_names = c("time", "value") )h5_read_values( h5, paths = NULL, simplify_scalars = TRUE, timeseries_as_tibble = TRUE, ts_names = c("time", "value") )
h5 |
An open |
paths |
character vector; if NULL read all. |
simplify_scalars |
logical: simplify scalar datasets to length-1 atoms. |
timeseries_as_tibble |
logical: convert 2xN / Nx2 arrays to tibble(time,value). |
ts_names |
character(2): names for time/value columns. |
Named list.
Summarizes for each path:
current dataset dims/maxdims (HDF5 order)
intended value shape (R order)
intended write shape (HDF5 order; for TS always 2xN)
decision: SKIP / WRITE / RESIZE / NEED_RECREATE / ERROR
h5_validate_write(h5, values, ts_cols = c("time", "value"))h5_validate_write(h5, values, ts_cols = c("time", "value"))
h5 |
An open |
values |
Named list of values to write (names are HDF5 paths). |
ts_cols |
Character(2). Column names for TS (default time/value). |
Notes:
2-column data.frames/tibbles are treated as Nx2 in R and mapped to 2xN in HDF5.
Many RAINDROP files store time series as HDF5 dims 2xN (appearing as Nx2 in R).
tibble
Scalars: write with required args (args=list() or args=1L fallback).
2-col TS (data.frame/tibble): expects Nx2 in R; writes as 2xN in HDF5 (RAINDROP style), using explicit hyperslab args=list(1:2, 1:N) to avoid empty selections.
If TS length changes and dataset maxdims blocks resize, the dataset is deleted via parent$link_delete(name) and recreated with dims=2xN (fixed), then written. (No maxdims argument used; compatible with your create_dataset signature.)
h5_write_values( h5, values, resize = TRUE, strict = TRUE, ts_cols = c("time", "value"), scalar_strategy = c("error", "first", "collapse"), collapse_sep = ";", ts_dtype = "double", verbose = FALSE )h5_write_values( h5, values, resize = TRUE, strict = TRUE, ts_cols = c("time", "value"), scalar_strategy = c("error", "first", "collapse"), collapse_sep = ";", ts_dtype = "double", verbose = FALSE )
h5 |
Open hdf5r::H5File. |
values |
Named list; names are dataset paths (leading // allowed). |
resize |
Logical. If TRUE tries set_extent() where possible. |
strict |
Logical. If TRUE stop on first error else warn and continue. |
ts_cols |
Character(2). Column names for TS (default time/value). |
scalar_strategy |
"error"|"first"|"collapse". |
collapse_sep |
Separator for collapse. |
ts_dtype |
Either an H5T object or one of "double","float","integer","logical". |
verbose |
Logical. |
Invisibly, written paths.
List all datasets (recursive)
list_h5_datasets(h5)list_h5_datasets(h5)
h5 |
An open |
A tibble with columns: path, obj_type, dims, maxdims.
Uses find_single_param_variations() (by default excluding ^h_ columns
from parameter detection) and plots absolute or percentage deviations of the
chosen response. The title shows the reference value in mm.
plot_hpond_vs_ref( data, response, ref_scenario = "s00001", diff = c("abs", "pct"), param_cols = NULL, exclude_cols = NULL, exclude_cols_regex = "^h_", tol = 1e-09, quiet = FALSE )plot_hpond_vs_ref( data, response, ref_scenario = "s00001", diff = c("abs", "pct"), param_cols = NULL, exclude_cols = NULL, exclude_cols_regex = "^h_", tol = 1e-09, quiet = FALSE )
data |
Data frame with at least |
response |
Character; the response column to plot (e.g. |
ref_scenario |
Reference scenario ID (default |
diff |
|
param_cols |
Optional explicit parameter columns (recommended if you prefilter). |
exclude_cols |
Extra columns to exclude from parameter detection. |
exclude_cols_regex |
Regex to auto-exclude non-parameter columns (default |
tol |
Numeric tolerance passed through to |
quiet |
Logical; diagnostics if |
A ggplot object.
Creates a facetted overview plot showing the distribution of an outcome
(for example n_overflows) across the tested levels of multiple varied
parameters. Parameters are sorted by a simple effect-size proxy: the range of
median outcome values across parameter levels.
plot_main_effects( df, y = "n_overflows", params, max_levels = 25, ylim_lower = 0, lang = c("de", "en") )plot_main_effects( df, y = "n_overflows", params, max_levels = 25, ylim_lower = 0, lang = c("de", "en") )
df |
A data.frame or tibble containing the outcome column |
y |
Character scalar. Name of the outcome column to plot on the y-axis.
Defaults to |
params |
Character vector of parameter column names in |
max_levels |
Integer. Parameters with more than |
ylim_lower |
Numeric scalar or |
lang |
Character. Plot language: |
The function is intended for optimisation or sensitivity grids with many parameters, where a single 2D scatter plot is not informative.
The plot language can be switched via lang = "de" or
lang = "en". This affects the title, y-axis label, and selected
parameter labels.
A ggplot object with facetted violin, boxplot, and jitter layers.
Visualises model results in a 2D design space (by default mulde_area
vs. mulde_height) and highlights valid solutions (by default
n_overflows <= valid_max). The plot is prepared for direct use with
plotly::ggplotly(..., tooltip = "text") by mapping an HTML tooltip via
aes(text = ...) that lists all other varied parameters from
param_grid, excluding x and y.
plot_valid_design_space( param_grid, sim_results, id_col = "scenario_name", overflow_col = "n_overflows", valid_max = 1, x = "mulde_area", y = "mulde_height", max_levels = 50, alpha_invalid = 0.12, size = 2.4, digits = 4, drop_overflow_gt_valid_max = FALSE, jitter = FALSE, jitter_width = NULL, jitter_height = NULL, jitter_factor = 0.005, alpha_mode = c("none", "duplicates"), alpha_min = 0.2, alpha_max = 1, keep_param_grid_limits = TRUE, lang = c("de", "en"), title = NULL, subtitle = NULL, legend_position = "top" )plot_valid_design_space( param_grid, sim_results, id_col = "scenario_name", overflow_col = "n_overflows", valid_max = 1, x = "mulde_area", y = "mulde_height", max_levels = 50, alpha_invalid = 0.12, size = 2.4, digits = 4, drop_overflow_gt_valid_max = FALSE, jitter = FALSE, jitter_width = NULL, jitter_height = NULL, jitter_factor = 0.005, alpha_mode = c("none", "duplicates"), alpha_min = 0.2, alpha_max = 1, keep_param_grid_limits = TRUE, lang = c("de", "en"), title = NULL, subtitle = NULL, legend_position = "top" )
param_grid |
A data.frame/tibble containing the scenario id
( |
sim_results |
A data.frame/tibble containing the scenario id
( |
id_col |
Character. Join key (scenario id), default
|
overflow_col |
Character. Overflow outcome column, default
|
valid_max |
Numeric. Validity threshold:
|
x |
Character. Name of the x-axis column, default
|
y |
Character. Name of the y-axis column, default
|
max_levels |
Integer. Parameter columns with more than
|
alpha_invalid |
Numeric. Extra alpha multiplier for invalid solutions (background layer). |
size |
Numeric. Base point size. |
digits |
Integer. Significant digits for numeric tooltip values. |
drop_overflow_gt_valid_max |
Logical. If |
jitter |
Logical. If |
jitter_width |
Numeric or |
jitter_height |
Numeric or |
jitter_factor |
Numeric. Factor used to derive default jitter width/height from x/y ranges. Default 0.005. |
alpha_mode |
Character. Either |
alpha_min |
Numeric. Minimum alpha used when
|
alpha_max |
Numeric. Maximum alpha used when
|
keep_param_grid_limits |
Logical. If |
lang |
Character. Plot language: |
title |
Character or |
subtitle |
Character or |
legend_position |
Character. Legend position, e.g. |
Varied parameters are detected automatically as columns in param_grid
with more than one distinct value. Optionally, scenarios with
overflow_col > valid_max can be removed entirely
(drop_overflow_gt_valid_max = TRUE). To help identify multiple
scenarios that share identical x/y coordinates but differ in
other parameters, optional jitter and/or variable transparency can be
applied.
Discrete color mapping (threshold-style):
dark green at n_overflows = 0
a discrete palette from dark green to yellow-green for integer
levels 1..(valid_max-1)
orange at n_overflows = valid_max
red for n_overflows > valid_max, shown as level
">valid_max"
The plot language can be switched via lang = "de" or
lang = "en". This affects title, subtitle, legend title, tooltip
labels, and selected axis labels.
A ggplot object. Tooltip text is mapped via aes(text = ...).
Creates a scatter plot from optimisation results with element infiltration on the x-axis and element evapotranspiration on the y-axis.
plot_wb_tradeoff_overflows( simulation_results_optimisation, param_grid, x = 1, filter_n_gtx = FALSE, use_jitter = TRUE, jitter_width = 0.15, jitter_height = 0.15, jitter_seed = 1L, digits = 2L, digits_params = 4L, lang = c("de", "en"), title = NULL, lab_x = NULL, lab_y = NULL, legend_position = "top" )plot_wb_tradeoff_overflows( simulation_results_optimisation, param_grid, x = 1, filter_n_gtx = FALSE, use_jitter = TRUE, jitter_width = 0.15, jitter_height = 0.15, jitter_seed = 1L, digits = 2L, digits_params = 4L, lang = c("de", "en"), title = NULL, lab_x = NULL, lab_y = NULL, legend_position = "top" )
simulation_results_optimisation |
Data frame with simulation results.
Required columns are |
param_grid |
Data frame with parameter grid. Must contain
|
x |
Numeric, typically integer. Threshold for overflow coloring. Values
greater than or equal to |
filter_n_gtx |
Logical. If |
use_jitter |
Logical. If |
jitter_width, jitter_height
|
Numeric. Jitter strength in x- and y-
direction, only used if |
jitter_seed |
Integer. Seed for reproducible jitter. |
digits |
Integer. Number of digits used for rounding water balance values in the tooltip. |
digits_params |
Integer. Number of digits used for rounding numeric parameter values in the tooltip. |
lang |
Character. Plot language: |
title |
Character or |
lab_x |
Character or |
lab_y |
Character or |
legend_position |
Character. Legend position, e.g. |
Coloring is discrete based on n_overflows and a threshold
x:
dark green for n_overflows = 0
a discrete palette from dark green to yellow-green for integer
levels 1..(x-1)
red for n_overflows >= x, shown as category
">=x"
The plot language can be switched via lang = "de" or
lang = "en". This affects title, axis labels, legend title, and
tooltip labels unless custom labels are supplied explicitly.
Tooltip text additionally includes all parameters from param_grid that
vary across scenarios, excluding scenario_name.
A ggplot object.
Reads an HDF5 file that contains surface-water connections (formerly
"Verschaltungen"), e.g. a file like s78853_Verschaltungen.h5. The file is
expected to have:
a root-level scalar dataset "Anzahl Verschaltungen", and
one group per connection ("0", "1", ...) that contains
scalar metadata (e.g. von_Layer, von_Massnahmenelement,
nach_Layer, nach_Massnahmenelement) and
time-series datasets stored as 2×N matrices
(e.g. Qtatsaechlich, delta_h_pond_*, delta_theta_*).
Scalar metadata are returned
als breite Tabelle (meta),
als lange Tabelle (scalars) und
pro Verbindung in einer Unterliste (connections$group_0, ...).
Time series werden in Long-Format zurückgegeben und mit den Metadaten verknüpft.
read_hdf5_connections(file)read_hdf5_connections(file)
file |
An |
A named list with components:
integer(1). Value of the root dataset
"Anzahl Verschaltungen" (or NA_integer_ if not present).
A tibble with one row per connection:
connection_id, from_layer, from_element, to_layer, to_element.
A tibble with long-format time series for all
connections:
connection_id, variable, time, value,
from_layer, from_element, to_layer, to_element.
A tibble with all scalar datasets per connection in long
format:
connection_id, variable, value (list), type.
A named list of per-connection sublists:
connections$group_0, connections$group_1, ...; each containing
connection_id, meta, timeseries, scalars für genau diese
Verbindung.
## Not run: library(hdf5r) f <- H5File$new(paths$path_verschaltungen_hdf5, mode = "r") conn <- read_hdf5_connections(f) conn$n_connections conn$meta conn$timeseries # Unterliste für die erste Verbindung: conn$connections$group_0$meta conn$connections$group_0$timeseries ## End(Not run)## Not run: library(hdf5r) f <- H5File$new(paths$path_verschaltungen_hdf5, mode = "r") conn <- read_hdf5_connections(f) conn$n_connections conn$meta conn$timeseries # Unterliste für die erste Verbindung: conn$connections$group_0$meta conn$connections$group_0$timeseries ## End(Not run)
Reads all scalar datasets contained in an HDF5 group and returns them as a tibble. By default, only numeric / integer scalars are returned. If non-numeric scalars (e.g. strings) are present, they can either be dropped with a warning or kept in a list-column.
read_hdf5_scalars(group, numeric_only = TRUE)read_hdf5_scalars(group, numeric_only = TRUE)
group |
An |
numeric_only |
Logical (default: |
If numeric_only = TRUE:
A tibble with columns
character. Dataset name within the group.
numeric. Scalar value read from the dataset.
If numeric_only = FALSE:
A tibble with columns
character. Dataset name within the group.
list. Scalar values (numeric, integer, character, ...).
character. First class of each value (e.g. "numeric", "character").
## Not run: # Wasserbilanz: nur numerische Skalare wb_tbl <- read_hdf5_scalars(res_hdf5_element[["Wasserbilanz"]]) # Metainfo: gemischte Typen (Integer + String) meta_tbl <- read_hdf5_scalars(res_hdf5_element[["Metainfo"]], numeric_only = FALSE) ## End(Not run)## Not run: # Wasserbilanz: nur numerische Skalare wb_tbl <- read_hdf5_scalars(res_hdf5_element[["Wasserbilanz"]]) # Metainfo: gemischte Typen (Integer + String) meta_tbl <- read_hdf5_scalars(res_hdf5_element[["Metainfo"]], numeric_only = FALSE) ## End(Not run)
Reads all datasets in an HDF5 group and returns a long tibble with columns: variable, time, value.
read_hdf5_timeseries( ts_groupvariable, deeper_layers_pattern = "deeperLayers|deeper_layers" )read_hdf5_timeseries( ts_groupvariable, deeper_layers_pattern = "deeperLayers|deeper_layers" )
ts_groupvariable |
|
deeper_layers_pattern |
regex to detect deeper-layers datasets |
Supported dataset layouts:
k x N (rows): [1, ] = time, [2..k, ] = values (series)
N x k (cols): [, 1] = time, [, 2..k] = values (series)
Special handling for names containing "deeperLayers"/"deeper_layers":
The value series represent layers below layer 1.
Output variable names get suffixed with the layer-id:
If the dataset contains only time (no value series), it returns 0 rows.
tibble::tibble(variable, time, value)
Reads the RAINDROP error protocol HDF5 (typically Fehlerprotokoll.h5)
for a set of simulation runs and returns a tibble with one row per run and a
nested tibble column containing all errors found in the file.
read_raindrop_errors(simulation_names, path_list, debug = FALSE)read_raindrop_errors(simulation_names, path_list, debug = FALSE)
simulation_names |
Character vector of simulation run names (e.g. |
path_list |
A path list object passed to |
debug |
Logical. If |
The error HDF5 usually contains:
/AnzahlFehler (scalar integer)
groups /0, /1, ... each containing datasets such as
Fehlerbeschreibung, Layer1, Layer2,
Massnahmenelement1, Massnahmenelement2
Note: In hdf5r, HDF5 group names must be addressed as character strings.
So group 0 must be accessed as h5[["0"]] (not h5[[0]]).
A tibble with columns:
id Integer simulation id (parsed from simulation_names).
scenario_name The simulation name (e.g. "s00001").
path File path to the error HDF5.
file_exists Logical.
number_of_errors Scalar integer or NA.
errors Nested tibble (list-column) with per-error rows:
error_index, Fehlerbeschreibung, Layer1, Layer2,
Massnahmenelement1, Massnahmenelement2
## Not run: errors_df <- read_raindrop_errors(simulation_names, path_list) # flatten all errors: all_errors <- tidyr::unnest(errors_df, errors) ## End(Not run)## Not run: errors_df <- read_raindrop_errors(simulation_names, path_list) # flatten all errors: all_errors <- tidyr::unnest(errors_df, errors) ## End(Not run)
Builds and runs a system command of the form "<path_exe> <path_input>",
after normalising both paths to absolute paths. Progress and (optionally)
command output are wrapped with kwb.utils::catAndRun() for neat logging.
run_model(path_exe, path_input, print_output = FALSE, debug = TRUE, ...)run_model(path_exe, path_input, print_output = FALSE, debug = TRUE, ...)
path_exe |
|
path_input |
|
print_output |
|
debug |
|
... |
Additional arguments passed to |
Both path_exe and path_input are converted to absolute, normalised
paths via fs::path_abs() and base::normalizePath(). The command is
executed with base::shell(), which on Windows invokes the system shell.
On non-Windows platforms, prefer base::system() if you need full POSIX semantics.
If print_output = FALSE, a character vector containing the captured
standard output of the command.
If print_output = TRUE, the (invisible) integer exit status returned by
shell() (0 indicates success).
Executes an external program that may read/write files depending on the model. Ensure you trust the executable and paths provided.
base::shell(), fs::path_abs(), kwb.utils::catAndRun()
## Not run: # Example: run a hypothetical model with an input file exe <- "C:/path/to/model.exe" input <- "C:/path/to/input.h5" # Capture output as character vector out <- run_model(exe, input, print_output = FALSE) # Stream output and get exit status status <- run_model(exe, input, print_output = TRUE) ## End(Not run)## Not run: # Example: run a hypothetical model with an input file exe <- "C:/path/to/model.exe" input <- "C:/path/to/input.h5" # Capture output as character vector out <- run_model(exe, input, print_output = FALSE) # Stream output and get exit status status <- run_model(exe, input, print_output = TRUE) ## End(Not run)
Executes scenarios by applying run_one_scenario to each element of
indices. Supports parallel execution via future.apply and
sequential execution for debugging. Optionally shows progress via
progressr.
run_scenarios( indices, run_one_scenario, timestep_hours, debug = FALSE, ..., parallel = TRUE, workers = parallel::detectCores(), show_progress = TRUE, progress_handler = "txtprogressbar" )run_scenarios( indices, run_one_scenario, timestep_hours, debug = FALSE, ..., parallel = TRUE, workers = parallel::detectCores(), show_progress = TRUE, progress_handler = "txtprogressbar" )
indices |
Vector. Scenario identifiers to iterate over (often integer row indices). |
run_one_scenario |
Function. Worker function with signature
|
timestep_hours |
Numeric. Time step (hours) forwarded to
|
debug |
Logical. Debug flag forwarded to |
... |
Additional arguments forwarded to |
parallel |
Logical. If |
workers |
Integer. Number of workers when |
show_progress |
Logical. If |
progress_handler |
Character. Progress handler key. One of
|
A list with one element per indices entry containing the
return values of run_one_scenario.