Skip to contents

Add overflow-event metrics and water-balance shares (percent) to simulation results

Source: R/add_overflow_events_and_waterbalance.R
add_overflow_events_and_waterbalance.Rd

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.

Usage

add_overflow_events_and_waterbalance(
  simulation_results,
  event_separation_hours = 4
)

Arguments

simulation_results

Named list of scenario results. Each entry is expected to contain:

  • element$water_balance with columns variable, value

  • connected_area$water_balance with columns variable, value

  • element$rates with columns time, variable, value

event_separation_hours

Numeric. Minimum time between two overflow events (in hours). Defaults to 4.

Value

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.*_

Details

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. The element.*_ and connectedarea.*_ water-balance columns follow dplyr::bind_rows() semantics: a column is added to the output as soon as at least one scenario contributes it, with NA for the rows that don't. If every scenario in simulation_results lacks a side (e.g. every run disables roof ET, so no scenario contributes any connectedarea.*_), that side's columns are absent from the output entirely. Downstream code that addresses those columns by name should therefore check for their presence rather than assume they exist.

Examples

if (FALSE) { # \dontrun{
out <- add_overflow_events_and_waterbalance(simulation_results)
out <- add_overflow_events_and_waterbalance(
  simulation_results,
  event_separation_hours = 6
)
} # }