| Title: | R Implementation of Water Balance Model Abimo |
|---|---|
| Description: | The code in this package has been transferred from the C++ code of ABIMO 3.3: Water Balance Model for Urban Areas (https://github.com/KWB-R/abimo/). |
| Authors: | Hauke Sonnenberg [aut, cre] (ORCID: <https://orcid.org/0000-0001-9134-2871>), Francesco Del Punta [aut], Kompetenzzentrum Wasser Berlin gGmbH (KWB) [cph] |
| Maintainer: | Hauke Sonnenberg <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 2.1.0 |
| Built: | 2026-05-24 07:45:12 UTC |
| Source: | https://github.com/KWB-R/kwb.rabimo |
Calculate the deviation from the natural water balance (delta-W) given
R-Abimo results as returned by run_rabimo.
calculate_delta_w( natural, urban, columns_water_balance = c("runoff", "infiltr", "evapor"), column_code = "code", digits = 1L )calculate_delta_w( natural, urban, columns_water_balance = c("runoff", "infiltr", "evapor"), column_code = "code", digits = 1L )
natural |
R-Abimo results for the "natural" scenario |
urban |
R-Abimo results for the "urban" scenario |
columns_water_balance |
names of columns in |
column_code |
name of column in |
digits |
integer indicating the number of decimal places in the result |
a data frame with the area codes in column code and the
delta-W values in column delta_w
Crop a box out of a shape
crop_box(x, xoffset = 0.45, yoffset = 0.45, xscale = 0.1, yscale = 0.1)crop_box(x, xoffset = 0.45, yoffset = 0.45, xscale = 0.1, yscale = 0.1)
x |
sf object |
xoffset |
x-offset as fraction of original width (0..1) |
yoffset |
y-offset as fraction of original height (0..1) |
xscale |
new width as fraction of original width (0..1) |
yscale |
new height as fraction of original height (0..1) |
Three scenarios are possible:
undeveloped: all paved or constructed areas are set to 0%. No connection to the sewer.
forested: like undeveloped, but the land type is declared to be "forested".
horticultural: like undeveloped, but the land type is declared to be "horticultural".
data_to_natural(data, type = "undeveloped", veg_class = 50)data_to_natural(data, type = "undeveloped", veg_class = 50)
data |
the input data in R-Abimo format |
type |
a character object containing the name of natural scenario. Defaults to "undeveloped" |
veg_class |
vegetation class to assign to each row in |
a dataframe with R-Abimo input data for the chosen natural scenario
Define a list of settings that control how the main function
run_rabimo should behave.
define_controls( check = TRUE, use_abimo_bagrov_solver = TRUE, reproduce_abimo_error = FALSE, output_format = "rabimo", intermediates = FALSE )define_controls( check = TRUE, use_abimo_bagrov_solver = TRUE, reproduce_abimo_error = FALSE, output_format = "rabimo", intermediates = FALSE )
check |
logical indicating whether the check functions are executed.
Default: |
use_abimo_bagrov_solver |
logical indicating whether or not to use the
(fast!) algorithm implemented in Abimo to solve the Bagrov equations.
Default: |
reproduce_abimo_error |
logical indicating whether or not to reproduce
the error that is contained in Abimo (missing area fraction factor).
Default: |
output_format |
one of "abimo" (upper case columns: CODE, R, ROW, RI, RVOL, ROWVOL, RIVOL, FLAECHE, VERDUNSTUN), "rabimo" (lower case columns: code, surface_runoff, infiltration, evaporation). |
intermediates |
logical indicating whether the intermediate results are
returned as attributes. Default: |
list with the arguments of this function as list elements
inputs <- kwb.rabimo::rabimo_inputs_2020 test_data <- inputs$data[sample(seq_len(nrow(inputs$data)), size = 1000L), ] controls_default <- define_controls() controls_no_check <- define_controls(check = FALSE) controls_no_solver <- define_controls(use_abimo_bagrov_solver = FALSE) system.time(result_default <- kwb.rabimo::run_rabimo( test_data, inputs$config, controls_default )) system.time(result_no_check <- kwb.rabimo::run_rabimo( test_data, inputs$config, controls_no_check )) identical(result_default, result_no_check) ## Not run: system.time(result_no_solver <- kwb.rabimo::run_rabimo( test_data, inputs$config, controls_no_solver )) ## End(Not run)inputs <- kwb.rabimo::rabimo_inputs_2020 test_data <- inputs$data[sample(seq_len(nrow(inputs$data)), size = 1000L), ] controls_default <- define_controls() controls_no_check <- define_controls(check = FALSE) controls_no_solver <- define_controls(use_abimo_bagrov_solver = FALSE) system.time(result_default <- kwb.rabimo::run_rabimo( test_data, inputs$config, controls_default )) system.time(result_no_check <- kwb.rabimo::run_rabimo( test_data, inputs$config, controls_no_check )) identical(result_default, result_no_check) ## Not run: system.time(result_no_solver <- kwb.rabimo::run_rabimo( test_data, inputs$config, controls_no_solver )) ## End(Not run)
All default values can be overridden by entering new key-value pairs.
generate_rabimo_area(code, ..., column_info = read_column_info())generate_rabimo_area(code, ..., column_info = read_column_info())
code |
identifier of area |
... |
key = value pairs overriding the default column values |
column_info |
data frame as returned by |
Get Mean/Max Statistics on Measures
get_measure_stats(blocks, reference_system = 2)get_measure_stats(blocks, reference_system = 2)
blocks |
data frame similar to |
reference_system |
indicator for the "reference system" in which the returned values are to be given. 1: all values refer to percentages of specific areas (green roof: roof area, unsealed: total area, to_swale: sealed area); 2: all values refer to percentages of the total area. The default is 2. |
list with elements "mean" and "max" each of which is a list with one element per measure
Provide variables that are relevant to calculate the actual evaporation for unsealed areas
get_soil_properties( land_type, veg_class, depth_to_water_table, field_capacity_30, field_capacity_150, dbg = FALSE )get_soil_properties( land_type, veg_class, depth_to_water_table, field_capacity_30, field_capacity_150, dbg = FALSE )
land_type |
land_type string, one of "vegetationless", "waterbody", "horticultural", "urban", "forested" |
veg_class |
vegetation class |
depth_to_water_table |
depth to water table |
field_capacity_30 |
field capacity in 30 cm depth |
field_capacity_150 |
field capacity in 150 cm depth |
dbg |
logical indicating whether or not to show debug messages |
Data frame and configuration object that are required by the R-Abimo main
function run_rabimo.
rabimo_inputs_2020rabimo_inputs_2020
rabimo_inputs_2020A list containing two elements:
dataa data frame with the input data to R-Abimo (see below)
configa list of model parameters (see below)
rabimo_inputs_2020$dataA data.frame with 58531 observations of 33 variables:
codeUnique block area identifier (character)
prec_yrLong-term average of annual precipitation in mm (integer)
prec_sLong-term average of annual precipitation within summer months (May to October) in mm (integer)
epot_yrLong-term average of annual potential evapotranspiration in mm (integer)
epot_sLong-term average of annual potential evapotranspiration within summer months (May to October) in mm (integer)
districtNumber of Berlin "Bezirk" (district) in which the block area is located (character). This column is Berlin-specific and optional, i.e. not required by the model.
total_areaTotal block area in square metres (numeric)
main_fracFraction of the total area that is NOT considered as "road" area (numeric value between 0.0 and 1.0). This value should be 0.0 if roads are modelled separately, i.e. as block areas on their own.
roofFraction of the total area that is considered as "roof" area (numeric value between 0.0 and 1.0)
green_roofFraction of the roof area that belongs to green roofs (numeric value between 0.0 and 1.0). A value of 1.0 means that all roofs in the block area are green roofs.
swg_roofFraction of the roof area that is connected to the drainage system (numeric value between 0.0 and 1.0)
pvdFraction of the total block area that is paved (numeric value between 0.0 and 1.0)
swg_pvdFraction of the paved area that is connected to the drainage system (numeric value between 0.0 and 1.0)
srf1_pvdFraction of the paved area that belongs to surface class 1 (numeric value between 0.0 and 1.0, see note 1 below)
srf2_pvdFraction of the paved area that belongs to surface class 2 (numeric value between 0.0 and 1.0, see note 1 below)
srf3_pvdFraction of the paved area that belongs to surface class 3 (numeric value between 0.0 and 1.0, see note 1 below)
srf4_pvdFraction of the paved area that belongs to surface class 4 (numeric value between 0.0 and 1.0, see note 1 below)
srf5_pvdFraction of the paved area that belongs to surface class 5 (numeric value between 0.0 and 1.0, see note 1 below)
road_fracFraction of the total area that is considered as "road" area (numeric value between 0.0 and 1.0)
pvd_rFraction of road area (within the block area) that is paved (numeric, see note 2 below)
swg_pvd_rFraction of paved road area (within the block area) that is connected to the drainage system (numeric, see note 2 below))
srf1_pvd_rFraction of paved road area (within the block area) that belongs to surface class 1 (numeric, see note 2 below))
srf2_pvd_rFraction of paved road area (within the block area) that belongs to surface class 2 (numeric, see note 2 below))
srf3_pvd_rFraction of paved road area (within the block area) that belongs to surface class 3 (numeric, see note 2 below))
srf4_pvd_rFraction of paved road area (within the block area) that belongs to surface class 4 (numeric, see note 2 below))
to_swaleFraction of sealed area (roof area + paved area) that is connected to an infiltration swale (numeric)
gw_distDistance between groundwater table and surface in metres (numeric)
ufc30field capacity in 30 cm depth (numeric)
ufc150field capacity in 150 cm depth (numeric)
land_typeland type, one of forested, horticultural, urban, vegetationless, waterbody (character)
veg_classvegetation class (numeric values each being one of 0, 1, 10, 25, 30, 35, 40, 45, 50, 55). Each combination of block and land use type is assigned to a distinct vegetation class value.
irrigationirrigation in mm per year (integer)
block_typeBlock type identifier of the form "usage-type-id_block-type-id_usage-type-description_block-type-description" (character)
Note 1: The sum of surface class fractions srf1_pvd, srf2_pvd, srf3_pvd, srf4_pvd, srf5_pvd should be 1.0 within each block area. For the meaning of the five different surface classes in Berlin, see the table in the Details section below.
Note 2: The fields with suffix "_r" are all zero because rows are modelled as their own blocks. In an earlier version of the dataset, roads were modelled as parts of the block area.
rabimo_inputs_2020$configA list with 5 named elements:
runoff_factorsRunoff factors for roofs and five different surface
types, given as a vector of numeric with element names roof, surface1,
surface2, surface3, surface4, surface5. A runoff factor determines
the proportion of precipitation that, after subtraction of
evapotranspiration, becomes surface runoff from a paved area. The higher
the factor, the less permeable is the surface. See the table in the Details section below.
bagrov_valuesBagrov values to calculate evapotranspiration from
paved surfaces, given as a vector of numeric with element names roof,
green_roof, surface1, surface2, surface3, surface4, surface5.
The higher the Bagrov value, the more evapotranspiration is generated by
the model, see the table in the Details section below. For a description of the evapotranspiration model and for a
figure that shows the influence of the Bagrov values (n) on the
evapotranspiration (in German), see https://www.berlin.de/umweltatlas/wasser/wasserhaushalt/2001/methode/
result_digitsrelict of the original ABIMO model, not used in R-Abimo!
irrigation_to_zerorelict of the original ABIMO model, not used in R-Abimo!
swaleModel parameter(s) related to the 'swale' measure, given as a
vector of numeric with currently one value, named
swale_evaporation_factor. The swale evaporation factor determines which
fraction of the water going into a swale becomes evapotranspiration (the
rest becomes infiltration).
See the following table for the meaning of the surface classes and their Bagrov values and runoff factors used for Berlin.
| Surface Class | Surface Type | Bagrov Value | Runoff Factor |
| - | Roof surfaces | 0.05 | 1.00 |
| - | Extensive vegetated roofs | 0.65 | 1.00 |
| 1 | Asphalt, concrete, paving with joint sealing or concrete base, synthetic surfaces | 0.11 | 0.90 |
| 2 | Artificial stone and slab coverings (side length > 8 cm), concrete interlocking pavers, clinker, medium and large pavers | 0.11 | 0.70 |
| 3 | Small and mosaic pavers (side length < 8 cm) | 0.25 | 0.40 |
| 4 | Grass pavers, bound gravel surfaces, gravel lawns | 0.40 | 0.10 |
| 5 | Unknown type (average parameters) | 0.25 | 0.48 |
Data frame and configuration object that are required by the R-Abimo main
function run_rabimo.
The data have been provided by
Senate Department for Urban Development, Building and Housing
III D Spatial Data Infrastructure, Environmental Atlas.
rabimo_inputs_2025rabimo_inputs_2025
rabimo_inputs_2025A list containing two elements:
a data frame with the input data in R-Abimo format (see below)
a list object with configuration data (see below)
rabimo_inputs_2025$dataA data.frame with 58531 observations of 26 variables:
codeUnique block area identifier (character)
prec_yrLong-term average of annual precipitation in mm (integer)
prec_sLong-term average of annual precipitation within summer months (May to October) in mm (integer)
epot_yrLong-term average of annual potential evapotranspiration in mm (integer)
epot_sLong-term average of annual potential evapotranspiration within summer months (May to October) in mm (integer)
districtNumber of Berlin "Bezirk" (district) in which the block area is located (character). This column is Berlin-specific and optional, i.e. not required by the model.
total_areaTotal block area in square metres (numeric)
roofFraction of the total area that is considered as "roof" area (numeric value between 0.0 and 1.0)
green_roofFraction of the roof area that belongs to green roofs (numeric value between 0.0 and 1.0). A value of 1.0 means that all roofs in the block area are green roofs.
swg_roofFraction of the roof area that is connected to the drainage system (numeric value between 0.0 and 1.0)
pvdFraction of the total block area that is paved (numeric value between 0.0 and 1.0)
swg_pvdFraction of the paved area that is connected to the drainage system (numeric value between 0.0 and 1.0)
srf1_pvdFraction of the paved area that belongs to surface class 1 (numeric value between 0.0 and 1.0, see note 1 below)
srf2_pvdFraction of the paved area that belongs to surface class 2 (numeric value between 0.0 and 1.0, see note 1 below)
srf3_pvdFraction of the paved area that belongs to surface class 3 (numeric value between 0.0 and 1.0, see note 1 below)
srf4_pvdFraction of the paved area that belongs to surface class 4 (numeric value between 0.0 and 1.0, see note 1 below)
srf5_pvdFraction of the paved area that belongs to surface class 5 (numeric value between 0.0 and 1.0, see note 1 below)
to_swaleFraction of sealed area (roof area + paved area) that is connected to an infiltration swale (numeric value between 0.0 and 1.0)
gw_distDistance between groundwater table and surface in metres (numeric)
ufc30field capacity in 30 cm depth (numeric)
ufc150field capacity in 150 cm depth (numeric)
land_typeland type, one of forested, horticultural, urban, vegetationless, waterbody (character)
veg_classvegetation class index (numeric), derived from an analysis of tree volumes
irrigationirrigation in mm per year (integer)
block_typeBlock type identifier of the form "usage-type-id_block-type-id_usage-type-description_block-type-description" (character). This column is Berlin-specific and optional, i.e. not required by the model.
ShapeList structure containing geometry information on the different block areas. This column is optional. If provided, it will be appended to the model output so that model results can be plotted in the form of maps.
Note 1: The sum of surface class fractions srf1_pvd, srf2_pvd, srf3_pvd, srf4_pvd, srf5_pvd should be 1.0 within each block area. For the meaning of the five different surface classes in Berlin, see the table in the Details section below.
rabimo_inputs_2025$configA list with 3 named elements:
Runoff factors for roofs and five different surface
types, given as a vector of numeric with element names roof, surface1,
surface2, surface3, surface4, surface5. A runoff factor determines
the proportion of precipitation that, after subtraction of
evapotranspiration, becomes surface runoff from a paved area. The higher
the factor, the less permeable is the surface. See the table in the Details section below.
Bagrov values to calculate evapotranspiration from
paved surfaces, given as a vector of numeric with element names roof,
green_roof, surface1, surface2, surface3, surface4, surface5.
The higher the Bagrov value, the more evapotranspiration is generated by
the model, see the table in the Details section below. For a description of the evapotranspiration model and for a
figure that shows the influence of the Bagrov values (n) on the
evapotranspiration (in German), see https://www.berlin.de/umweltatlas/wasser/wasserhaushalt/2001/methode/
Model parameter(s) related to the 'swale' measure, given as a
vector of numeric with currently one value, named
swale_evaporation_factor. The swale evaporation factor determines which
fraction of the water going into a swale becomes evapotranspiration (the
rest becomes infiltration).
See the following table for the meaning of the surface classes and their Bagrov values and runoff factors used for Berlin.
| Surface Class | Surface Type | Bagrov Value | Runoff Factor |
| - | Roof surfaces | 0.05 | 1.00 |
| - | Extensive vegetated roofs | 0.65 | 1.00 |
| 1 | Asphalt, concrete, paving with joint sealing or concrete base, synthetic surfaces | 0.11 | 0.90 |
| 2 | Artificial stone and slab coverings (side length > 8 cm), concrete interlocking pavers, clinker, medium and large pavers | 0.11 | 0.70 |
| 3 | Small and mosaic pavers (side length < 8 cm) | 0.25 | 0.40 |
| 4 | Grass pavers, bound gravel surfaces, gravel lawns | 0.40 | 0.10 |
| 5 | Unknown type (average parameters) | 0.25 | 0.48 |
https://www.berlin.de/umweltatlas/en/general/contact/
https://gdi.berlin.de/services/wfs/ua_gruendaecher_2020?REQUEST=GetCapabilities&SERVICE=wfs
Provide Meta Information About Input Columns
read_column_info()read_column_info()
data frame with columns "rabimo_berlin", "abimo_berlin", "by_100", "meaning", "unit", "type", "data_type", "default"
Calculate Actual Evapotranspiration with Bagrov
real_evapo_transpiration( precipitation, potential_evaporation, bagrov_parameter, x_ratio = NULL, FUN_y_ratio = y_ratio_3, ... )real_evapo_transpiration( precipitation, potential_evaporation, bagrov_parameter, x_ratio = NULL, FUN_y_ratio = y_ratio_3, ... )
precipitation |
precipitation in mm |
potential_evaporation |
potential evaporation in mm |
bagrov_parameter |
Bagrov parameter (n-value) |
x_ratio |
optional. Instead of |
FUN_y_ratio |
function to be called to calculate the y_ratio(s) from the
given x_ratio(s). Default: |
... |
further arguments passed to |
estimated actual evapotranspiration in mm
Run R-Abimo, the R-implementation of Water Balance Model Abimo
run_rabimo(data, config, controls = define_controls(), silent = FALSE)run_rabimo(data, config, controls = define_controls(), silent = FALSE)
data |
data frame similar to
|
config |
configuration object (list) similar to
|
controls |
list of settings that control how the function should behave.
Use |
silent |
logical indicating whether to suppress console outputs,
the default is |
data frame with columns as returned by Abimo
# Get input data and config for Berlin (version 2020) inputs_2020 <- kwb.rabimo::rabimo_inputs_2020 # Randomly select 1000 blocks (to reduce runtime) data <- inputs_2020$data data <- data[sample(seq_len(nrow(data)), size = 1000L), ] # Run R-Abimo results_2020 <- kwb.rabimo::run_rabimo(data, inputs_2020$config) # Get input data and config for Berlin (version 2025) inputs_2025 <- kwb.rabimo::rabimo_inputs_2025 # Crop a box (to reduce runtime) data <- crop_box(inputs_2025$data) # Run R-Abimo results_2025 <- kwb.rabimo::run_rabimo(data, inputs_2025$config) plot(results_2025[, -1L])# Get input data and config for Berlin (version 2020) inputs_2020 <- kwb.rabimo::rabimo_inputs_2020 # Randomly select 1000 blocks (to reduce runtime) data <- inputs_2020$data data <- data[sample(seq_len(nrow(data)), size = 1000L), ] # Run R-Abimo results_2020 <- kwb.rabimo::run_rabimo(data, inputs_2020$config) # Get input data and config for Berlin (version 2025) inputs_2025 <- kwb.rabimo::rabimo_inputs_2025 # Crop a box (to reduce runtime) data <- crop_box(inputs_2025$data) # Run R-Abimo results_2025 <- kwb.rabimo::run_rabimo(data, inputs_2025$config) plot(results_2025[, -1L])
Distribute Rainwater Management Measures and run R-Abimo
run_rabimo_with_measures( blocks, measures, config = kwb.rabimo::rabimo_inputs_2020$config )run_rabimo_with_measures( blocks, measures, config = kwb.rabimo::rabimo_inputs_2020$config )
blocks |
data frame of selected blocks (same columns as in
|
measures |
list with elements |
config |
configuration object, default:
|
Test the API to main functions using the plumber package and swagger
test_plumber_api()test_plumber_api()
Plot Triangle of Three Fractions
triangle_of_fractions( fractions, fractions_2 = NULL, cols = c("blue", "red", "darkgreen") )triangle_of_fractions( fractions, fractions_2 = NULL, cols = c("blue", "red", "darkgreen") )
fractions |
numeric vector with three values having a sum of one. The names of the vector elements are used as labels |
fractions_2 |
optional. Similar to |
cols |
vector of length three giving the colour names |
# blue, red, green | left, right, bottom components <- c(runoff = 200, infiltration = 50, evaporation = 100) fractions <- components / sum(components) triangle_of_fractions(fractions) triangle_of_fractions(fractions, fractions_2 = c(0.1, 0.3, 0.6))# blue, red, green | left, right, bottom components <- c(runoff = 200, infiltration = 50, evaporation = 100) fractions <- components / sum(components) triangle_of_fractions(fractions) triangle_of_fractions(fractions, fractions_2 = c(0.1, 0.3, 0.6))