WaterBalanceR

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.19
#> 
#> 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