# WaterBalanceR Data Sources

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

#### 2025-12-15

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