Author: Thomas Piernicke, GFZ Helmholtz Centre for Geosciences
Date: 2026-03-12

# WaterBalanceR

#### Thomas Piernicke, GFZ Helmholtz Centre for Geosciences

#### 2026-03-12

## 1. Introduction

`WaterBalanceR` provides a modular and reproducible workflow to compute the daily soil-water balance for agricultural areas.
It integrates meteorological, satellite and irrigation data sources and produces ready-to-use outputs such as GeoTIFFs, shapefiles and `.RData` summaries.

This vignette demonstrates the complete modelling workflow using the example dataset included in the package.

## 2. Setup and example data

    library(WaterBalanceR)

All required sample data are available inside the package directory:

    mypath <- system.file("sample_data", package = "WaterBalanceR")

    shape_site <- file.path(mypath, "Shapefile/sample_2023.shp")
    et0_file   <- file.path(mypath, "DWD_ET0_2023.csv")
    precip_dir <- file.path(mypath, "Radolan_2023_processed_daily")
    irrig_file <- file.path(mypath, "Shapefile/Buffer_36m_all_interp.shp")

## 3. Running the water balance model

The core function `calcWB()` performs the daily water balance simulation for a given site and year.

    test_wb <- WaterBalanceR::calcWB(
      mypath = mypath,
      shape_site = shape_site,
      target_res = 10,
      last_NDVI_0 = 132,
      ET_ref = read.csv(et0_file),
      ET_ref_dl = "DWD",
      path_WR_precip = precip_dir,
      precip_source = "radolan",
      irrig_sf = irrig_file,
      irrigation_efficiency = 1.0,
      output_year = 2023,
      save_shape = TRUE,
      save_geotiff = TRUE,
      save_RDATA = TRUE
    )

### Expected output

When executed, this call: - Loads and crops daily precipitation and NDVI rasters to the AOI.
- Computes daily evapotranspiration and irrigation contributions.
- Produces:
- GeoTIFF maps of water balance components for each day.
- Shapefiles of aggregated zones.
- `.RData` files with cumulative summaries.

Console output typically includes progress logs:

    1. Loading TIFF files...
    2. Cropping and resampling...
    3. Aggregating to target resolution...
    4. Computing daily balance...
    Model run completed.

## 4. Visualizing results

Once the water balance model is complete, plots can be generated with `calcWBplots()`:

    buffer20 <- file.path(mypath, "Shapefile/Buffer_5_WB.shp")

    WaterBalanceR::calcWBplots(
      source_path = file.path(
        mypath,
        "radolan_1_132_10",
        "WBR_radolan_1_132_10.RData"
      ),
      plant_doy = 109,
      buffer20 = buffer20,
      shape_site = shape_site
    )

### Output description

This produces time-series plots and raster maps of: - Daily and cumulative precipitation.
- Reference evapotranspiration (ET₀) and actual ET.
- Irrigation inputs and water deficit.
- Summary figures saved as `.jpg` and `.pdf`.

## 5. Output structure

After a successful run, the output folder will typically look like:

    sample_data/
     ├── radolan_1_132_10/
     │    ├── WBR_radolan_1_132_10.RData
     │    ├── ET0_2023_doy_masked_132.tif
     │    ├── Niederschlag_2023_doy_masked_132.tif
     │    ├── WaterBalance_2023_doy_masked_132.tif
     │    └── Plots/
     │         ├── WB_daily_109.jpg
     │         ├── ET_cumulative_2023.pdf
     │         └── NDVI_series_2023.jpg

Each subfolder corresponds to a unique configuration of
`precip_source`, `irrigation_efficiency`, `last_NDVI_0`, and `target_res`.

## 6. Reproducibility note

All example data used in this vignette are included in the package installation.
They can be accessed programmatically using:

    system.file("sample_data", package = "WaterBalanceR")

This ensures full reproducibility of the workflow on any system.

## 7. Session info

    sessionInfo()
    #> R version 4.4.2 (2024-10-31 ucrt)
    #> Platform: x86_64-w64-mingw32/x64
    #> Running under: Windows 11 x64 (build 26200)
    #>
    #> Matrix products: default
    #>
    #>
    #> locale:
    #> [1] LC_COLLATE=C                    LC_CTYPE=German_Germany.utf8
    #> [3] LC_MONETARY=German_Germany.utf8 LC_NUMERIC=C
    #> [5] LC_TIME=German_Germany.utf8
    #>
    #> time zone: Europe/Berlin
    #> tzcode source: internal
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] WaterBalanceR_0.1.21
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] digest_0.6.37     R6_2.6.1          fastmap_1.2.0     xfun_0.52
    #>  [5] magrittr_2.0.4    cachem_1.1.0      knitr_1.50        RCurl_1.98-1.17
    #>  [9] htmltools_0.5.8.1 rmarkdown_2.30    lifecycle_1.0.4   bitops_1.0-9
    #> [13] cli_3.6.5         sass_0.4.9        jquerylib_0.1.4   compiler_4.4.2
    #> [17] rstudioapi_0.17.1 tools_4.4.2       evaluate_1.0.5    bslib_0.9.0
    #> [21] rlang_1.1.5       jsonlite_1.9.1