1. Introduction

This vignette describes the data acquisition and preprocessing functions included in the WaterBalanceR package.
They enable users to download, preprocess and combine meteorological, satellite and irrigation datasets used as inputs for the calcWB() waterbalance model.

All functions can be executed independently and each produces standardized outputs that fit seamlessly into the calcWB workflow.

2. Reference evapotranspiration (ET₀)

2.1 DownloadET0fromDWD()

Downloads daily FAO-56 reference evapotranspiration grids from the German Weather Service (DWD) and extracts the daily mean ET₀ for a given area of interest (AOI).

ET0 <- WaterBalanceR::DownloadET0fromDWD(
  target_path   = "path/to/output",
  test_site_shp = "path/to/shapefile/AOI.shp",
  target_year   = 2023,
  timeout       = 10000
)

Output - CSV file: DWD_ET0_<year>.csv containing daily ET₀ values.
- Temporary NetCDF files are deleted after processing.

2.2 DownloadET0fromArable()

Retrieves daily ET₀ data from an Arable account via the Arable API.
Requires valid login credentials.

ET0_arable <- WaterBalanceR::DownloadET0fromArable(
  arable_user = "username",
  arable_pass = "password",
  target_year = 2023,
  target_path = "path/to/output"
)

Output - CSV file Arable_ET0_<year>.csv with daily reference ET₀ data.
- Useful when DWD data are unavailable or when comparing multiple ET₀ sources.

3. Precipitation data

3.1 DownloadRadolanfromDWD()

Downloads and processes RADOLAN daily precipitation grids for Germany from the DWD open data portal.
Each day’s raster is cropped and masked to the given AOI.

WaterBalanceR::DownloadRadolanfromDWD(
  target_path   = "path/to/output",
  target_year   = 2023,
  test_site_shp = "path/to/AOI.shp",
  timeout       = 10000
)

Output - Folder Radolan_<year>_processed_daily/ containing daily precipitation GeoTIFFs.
- Ready to be used as input for calcWB() with precip_source = "radolan".

4. Irrigation data

4.1 DownloadRaindancer()

Connects to the Raindancer irrigation portal and downloads field-specific irrigation data for the selected period.

WaterBalanceR::DownloadRaindancer(
  user         = "raindancer_user",
  password     = "raindancer_pass",
  target_path  = "path/to/output",
  target_year  = 2023
)

Output - CSV files containing daily irrigation events and applied water volumes per field.
- Can be spatially joined with field shapefiles.

4.2 DownloadRaindancerCombineCharts()

Combines multiple Raindancer irrigation charts into a single continuous daily time series and interpolates missing values.

WaterBalanceR::DownloadRaindancerCombineCharts(
  input_folder = "path/to/Raindancer/charts/",
  output_file  = "path/to/output/combined_irrigation.csv"
)

Output - Combined irrigation time series as a CSV file.
- Ensures a continuous dataset for use in calcWB().

5. Satellite data

5.1 DownloadSentinel2()

Downloads Sentinel-2 surface reflectance data for the AOI and the target year.
The function automatically filters by cloud coverage and computes NDVI layers.

WaterBalanceR::DownloadSentinel2(
  target_path   = "path/to/output",
  shape_site = "path/to/AOI.shp",
  start_date = "2025-06-01"
  end_date = "2025-08-01"
  max_cld     = 10
)

Output - Folder Sentinel2_<year>/ containing preprocessed NDVI GeoTIFFs.
- Used by calcWB() to derive vegetation dynamics and crop growth stages.

6. Integration with the WaterBalanceR workflow

The functions described above act as data preparation steps.
Once executed, they populate a standardized local folder structure such as:

project_root/
 ├── DWD_ET0_2023.csv
 ├── Radolan_2023_processed_daily/
 ├── Raindancer_combined_irrigation.csv
 └── Sentinel2_2023/

These datasets can then be referenced directly when calling calcWB():

WaterBalanceR::calcWB(
  mypath          = "project_root",
  ET_ref          = read.csv("project_root/DWD_ET0_2023.csv"),
  path_WR_precip  = "project_root/Radolan_2023_processed_daily",
  irrig_sf        = "project_root/Shapefile/Buffer_36m_all_interp.shp",
  precip_source   = "radolan"
)

7. Reproducibility note

All examples in this vignette use placeholder paths.
For reproducible results, use the sample dataset provided with the package:

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

This ensures identical workflows and file structures across systems.

8. 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     
#> 
#> loaded via a namespace (and not attached):
#>  [1] digest_0.6.37     R6_2.6.1          fastmap_1.2.0     xfun_0.52        
#>  [5] cachem_1.1.0      knitr_1.50        htmltools_0.5.8.1 rmarkdown_2.30   
#>  [9] lifecycle_1.0.4   cli_3.6.5         sass_0.4.9        jquerylib_0.1.4  
#> [13] compiler_4.4.2    rstudioapi_0.17.1 tools_4.4.2       evaluate_1.0.5   
#> [17] bslib_0.9.0       rlang_1.1.5       jsonlite_1.9.1