KWB-R · hsonne · Jul 21, 2025 · Jun 30, 2025 · Jul 1, 2025 · Jul 2, 2025
diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml
@@ -57,8 +57,13 @@ jobs:
           key: ${{ runner.os }}-r-${{ matrix.config.r }}-3-${{ hashFiles('depends.Rds') }}
           restore-keys: ${{ runner.os }}-r-${{ matrix.config.r }}-3-
 
+      - name: Install system dependencies on Linux
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get -y install cmake libssl-dev libgdal-dev gdal-bin libgeos-dev libproj-dev libsqlite3-dev libudunits2-dev
+
       - name: Install system dependencies
-        if: runner.os == 'Linux (no, skip this!)'
+        if: runner.os == 'Linux (no, skip!)'
         env:
           RHUB_PLATFORM: linux-x86_64-ubuntu-gcc
         run: |

diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,4 @@
 .Ruserdata
 docs
 kwb.rabimo.Rproj
+inst/doc
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: kwb.rabimo
 Title: R Implementation of Water Balance Model Abimo
-Version: 2.0.0
+Version: 2.1.0.9000
 Authors@R: c(
     person("Hauke", "Sonnenberg", , "hauke.sonnenberg@kompetenz-wasser.de", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0001-9134-2871")),
@@ -15,22 +15,26 @@ URL: https://github.com/KWB-R/kwb.rabimo
 BugReports: https://github.com/KWB-R/kwb.rabimo/issues
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 Suggests: 
     ggplot2,
     jsonlite,
+    knitr,
     plumber,
+    rmarkdown,
     testthat (>= 3.0.0)
 Imports: 
     dplyr,
     kwb.utils (>= 0.15.0),
     magrittr,
     parallel,
-    rlang
+    rlang,
+    sf
 Remotes: 
     github::kwb-r/kwb.utils
 Config/testthat/edition: 3
 Depends: 
     R (>= 3.5.0)
 LazyData: true
 LazyDataCompression: xz
+VignetteBuilder: knitr
diff --git a/NAMESPACE b/NAMESPACE
@@ -1,34 +1,41 @@
-# Generated by roxygen2: do not edit by hand
-
-export("%>%")
-export(calculate_delta_w)
-export(data_to_natural)
-export(define_controls)
-export(generate_rabimo_area)
-export(get_measure_stats)
-export(get_soil_properties)
-export(read_column_info)
-export(real_evapo_transpiration)
-export(run_rabimo)
-export(run_rabimo_with_measures)
-export(test_plumber_api)
-export(triangle_of_fractions)
-importFrom(kwb.utils,catAndRun)
-importFrom(kwb.utils,createAccessor)
-importFrom(kwb.utils,defaultIfNULL)
-importFrom(kwb.utils,getAttribute)
-importFrom(kwb.utils,printIf)
-importFrom(kwb.utils,renameAndSelect)
-importFrom(kwb.utils,renameColumns)
-importFrom(kwb.utils,selectColumns)
-importFrom(kwb.utils,selectElements)
-importFrom(kwb.utils,stopFormatted)
-importFrom(kwb.utils,stringList)
-importFrom(magrittr,"%>%")
-importFrom(parallel,detectCores)
-importFrom(parallel,makeCluster)
-importFrom(parallel,parLapply)
-importFrom(parallel,stopCluster)
-importFrom(rlang,.data)
-importFrom(stats,approx)
-importFrom(utils,globalVariables)
+# Generated by roxygen2: do not edit by hand
+
+export("%>%")
+export(calculate_delta_w)
+export(crop_box)
+export(data_to_natural)
+export(define_controls)
+export(generate_rabimo_area)
+export(get_measure_stats)
+export(get_soil_properties)
+export(read_column_info)
+export(real_evapo_transpiration)
+export(run_rabimo)
+export(run_rabimo_with_measures)
+export(test_plumber_api)
+export(triangle_of_fractions)
+importFrom(kwb.utils,catAndRun)
+importFrom(kwb.utils,createAccessor)
+importFrom(kwb.utils,defaultIfNULL)
+importFrom(kwb.utils,getAttribute)
+importFrom(kwb.utils,printIf)
+importFrom(kwb.utils,renameAndSelect)
+importFrom(kwb.utils,renameColumns)
+importFrom(kwb.utils,selectColumns)
+importFrom(kwb.utils,selectElements)
+importFrom(kwb.utils,stopFormatted)
+importFrom(kwb.utils,stringList)
+importFrom(magrittr,"%>%")
+importFrom(parallel,detectCores)
+importFrom(parallel,makeCluster)
+importFrom(parallel,parLapply)
+importFrom(parallel,stopCluster)
+importFrom(rlang,.data)
+importFrom(sf,st_as_sf)
+importFrom(sf,st_as_sfc)
+importFrom(sf,st_bbox)
+importFrom(sf,st_crop)
+importFrom(sf,st_drop_geometry)
+importFrom(sf,st_sfc)
+importFrom(stats,approx)
+importFrom(utils,globalVariables)
diff --git a/NEWS.md b/NEWS.md
@@ -1,3 +1,17 @@
+# kwb.rabimo 2.1.0 (2025-07-21)
+
+Contains a tutorial in the form of a vignette. To view the vignette, install
+the package with
+
+`remotes::install_github("kwb-r/kwb.rabimo@dev", build_vignettes = TRUE)`
+
+and open the vignette with
+
+`vignette("tutorial", package = "kwb.rabimo")`
+
+You can read the tutorial also on our GitHub page: 
+https://kwb-r.github.io/kwb.rabimo/articles/tutorial.html
+
 # kwb.rabimo 2.0.0 (2025-05-20)
 
 - contains new data for Berlin in which road areas do not belong to blocks 

diff --git a/R/calculate_delta_w.R b/R/calculate_delta_w.R
@@ -25,7 +25,9 @@ calculate_delta_w <- function(
 )
 {
   #kwb.utils::assignPackageObjects("kwb.rabimo")
-  #columns_water_balance = c("runoff", "infiltr", "evapor");column_code = "code"
+  #columns_water_balance=c("runoff","infiltr","evapor");column_code="code";digits=1L
+
+  urban <- remove_geo_column_if_required(urban)
 
   columns <- c(column_code, columns_water_balance)
   data_urban <- select_columns(urban, columns)
@@ -40,9 +42,22 @@ calculate_delta_w <- function(
   delta_ws <- rowSums(abs(joined_urban - joined_natural)) /
     rowSums(joined_natural) * 100 / 2
 
-  data.frame(
+  delta_w <- data.frame(
     code = joined[[column_code]],
     delta_w = unname(round(delta_ws, digits)),
     stringsAsFactors = FALSE
   )
+
+  if (is.null(geometry <- attr(urban, "geometry"))) {
+    delta_w
+  } else {
+    restore_geo_column_if_required(
+      delta_w,
+      # unfortunately, the [] selection removes the attribute "sf_column"
+      geometry = structure(
+        geometry[match(delta_w$code, urban$code)],
+        sf_column = attr(geometry, "sf_column")
+      )
+    )
+  }
 }
diff --git a/R/data_to_natural.R b/R/data_to_natural.R
@@ -25,6 +25,8 @@ data_to_natural <- function(data, type = "undeveloped", veg_class = 50)
   # data <- kwb.rabimo::rabimo_inputs_2020$data; type = "undeveloped"
   # data <- kwb.rabimo::rabimo_inputs_2025$data; type = "undeveloped"
 
+  data <- remove_geo_column_if_required(data)
+
   # Check whether data look as expected
   stop_on_invalid_data(data)
 
@@ -45,13 +47,18 @@ data_to_natural <- function(data, type = "undeveloped", veg_class = 50)
     } else if (type == "horticultural") {
       "horticultural"
     } else {
-      stop("please provide a known natural scenario type: undeveloped, horticultural or forested")
+      clean_stop(
+        'Please provide a known natural scenario type: "undeveloped", ',
+        '"horticultural" or "forested"'
+      )
     }
   }
 
-  check_or_convert_data_types(
+  data <- check_or_convert_data_types(
     data,
     types = get_expected_data_type(),
     convert = TRUE
   )
+
+  restore_geo_column_if_required(data)
 }
diff --git a/R/generate_rabimo_area.R b/R/generate_rabimo_area.R
@@ -1,6 +1,6 @@
 # generate_rabimo_area ---------------------------------------------------------
 
-#' Generate an area in R-ABIMO format with default values
+#' Generate an area in R-Abimo format with default values
 #'
 #' All default values can be overridden by entering new key-value pairs.
 #'

diff --git a/R/rabimo_inputs_2020.R b/R/rabimo_inputs_2020.R
@@ -17,7 +17,7 @@
 #'   \item{`prec_s`}{Long-term average of annual precipitation within summer months (May to October) in mm (integer)}
 #'   \item{`epot_yr`}{Long-term average of annual potential evapotranspiration in mm (integer)}
 #'   \item{`epot_s`}{Long-term average of annual potential evapotranspiration within summer months (May to October) in mm (integer)}
-#'   \item{`district`}{Number of Berlin "Bezirk" (district) in which the block area is located (character)}
+#'   \item{`district`}{Number 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.}
 #'   \item{`total_area`}{Total block area in square metres (numeric)}
 #'   \item{`main_frac`}{Fraction 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.}
 #'   \item{`roof`}{Fraction of the total area that is considered as "roof" area (numeric value between 0.0 and 1.0)}
@@ -47,7 +47,7 @@
 #'   \item{`block_type`}{Block 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`, `srf1_pvd`, `srf1_pvd`, `srf1_pvd`, `srf1_pvd` should be 1.0 within each block area.
+#' 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.
 #'
 #' 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.
 #'

diff --git a/R/rabimo_inputs_2025.R b/R/rabimo_inputs_2025.R
@@ -9,18 +9,18 @@
 #' @format ## `rabimo_inputs_2025`
 #' A list containing two elements:
 #' \describe{
-#'   \item{data}{a data frame with the input data in r-abimo format ...(number of vars)}
-#'   \item{config}{a list object with configuration data}
+#'   \item{data}{a data frame with the input data in R-Abimo format (see below)}
+#'   \item{config}{a list object with configuration data (see below)}
 #' }
 #' @format ## `rabimo_inputs_2025$data`
-#' A data.frame with 58531 observations of 25 variables:
+#' A data.frame with 58531 observations of 26 variables:
 #' \describe{
 #'   \item{`code`}{Unique block area identifier (character)}
 #'   \item{`prec_yr`}{Long-term average of annual precipitation in mm (integer)}
 #'   \item{`prec_s`}{Long-term average of annual precipitation within summer months (May to October) in mm (integer)}
 #'   \item{`epot_yr`}{Long-term average of annual potential evapotranspiration in mm (integer)}
 #'   \item{`epot_s`}{Long-term average of annual potential evapotranspiration within summer months (May to October) in mm (integer)}
-#'   \item{`district`}{Number of Berlin "Bezirk" (district) in which the block area is located (character)}
+#'   \item{`district`}{Number 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.}
 #'   \item{`total_area`}{Total block area in square metres (numeric)}
 #'   \item{`roof`}{Fraction of the total area that is considered as "roof" area (numeric value between 0.0 and 1.0)}
 #'   \item{`green_roof`}{Fraction 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.}
@@ -32,21 +32,40 @@
 #'   \item{`srf3_pvd`}{Fraction of the paved area that belongs to surface class 3 (numeric value between 0.0 and 1.0, see note 1 below)}
 #'   \item{`srf4_pvd`}{Fraction of the paved area that belongs to surface class 4 (numeric value between 0.0 and 1.0, see note 1 below)}
 #'   \item{`srf5_pvd`}{Fraction of the paved area that belongs to surface class 5 (numeric value between 0.0 and 1.0, see note 1 below)}
-#'   \item{`to_swale`}{Fraction of sealed area (roof area + paved area) that is connected to an infiltration swale (numeric)}
+#'   \item{`to_swale`}{Fraction of sealed area (roof area + paved area) that is connected to an infiltration swale (numeric value between 0.0 and 1.0)}
 #'   \item{`gw_dist`}{Distance between groundwater table and surface in metres (numeric)}
 #'   \item{`ufc30`}{field capacity in 30 cm depth (numeric)}
 #'   \item{`ufc150`}{field capacity in 150 cm depth (numeric)}
 #'   \item{`land_type`}{land type, one of `forested`, `horticultural`, `urban`, `vegetationless`, `waterbody` (character)}
-#'   \item{`veg_class`}{vegetation class index (numeric), derived from an analysis tree volumes}
+#'   \item{`veg_class`}{vegetation class index (numeric), derived from an analysis of tree volumes}
 #'   \item{`irrigation`}{irrigation in mm per year (integer)}
-#'   \item{`block_type`}{Block type identifier of the form "usage-type-id_block-type-id_usage-type-description_block-type-description" (character)}
+#'   \item{`block_type`}{Block 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.}
+#'   \item{`Shape`}{List 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.
+#' 
 #' @format ## `rabimo_inputs_2025$config`
 #' A list with 3 named elements:
 #' \describe{
-#'   \item{runoff_factors}{Runoff factors, vector of numeric with names `roof`, `surface1`, `surface2`, `surface3`, `surface4`, `surface5`}
-#'   \item{bagrov_values}{Bagrov values for sealed surfaces, vector of numeric with names `roof`, `green_roof`, `surface1`, `surface2`, `surface3`, `surface4`, `surface5`}
-#'   \item{swale}{Model parameter(s) related to the 'swale' measure, vector of numeric with currently one value, named `swale_evaporation_factor`}
+#'   \item{runoff_factors}{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.}
+#'   \item{bagrov_values}{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. 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 \url{https://www.berlin.de/umweltatlas/wasser/wasserhaushalt/2001/methode/}}
+#'   \item{swale}{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).}
 #' }
 #' @source <https://www.berlin.de/umweltatlas/en/general/contact/>
 #' @source <https://gdi.berlin.de/services/wfs/ua_gruendaecher_2020?REQUEST=GetCapabilities&SERVICE=wfs>