General note: the below vignette contains frozen output of 12 Nov 2026. This makes it possible to build the package with vignettes without access to the Watina data warehouse.
XG3 is an umbrella for the three geohydrological variables LG3, HG3
and VG3, which are yearly statistics which can be calculated from series
of water level measurements (on condition that enough data are
available). More explanation on these variables is given by the
documentation of get_xg3().
Let’s suppose that we want to select locations (within an area,
i.e. after having used get_locs()) for which:
min_dur and max_gap arguments.We can store specific conditions in a data frame; the available
statistics are explained by the documentation of
eval_xg3_avail() and eval_xg3_series():
conditions_df <-
tribble(
~xg3_variable, ~statistic, ~criterion, ~direction,
"combined", "ser_lastyear", 2015, "min"
)
conditions_df %>%
kable()| xg3_variable | statistic | criterion | direction |
|---|---|---|---|
| combined | ser_lastyear | 2015 | min |
The other aspects (which XG3 types?, max_gap,
min_dur) are directly specified in the
selectlocs_xg3() function:
watina <- connect_watina()
get_locs(watina,
area_codes = "TOR",
loc_type = c("P", "S")
) %>%
get_xg3(watina, 1900) %>%
selectlocs_xg3(
xg3_type = c("L", "H"),
max_gap = 1,
min_dur = 5,
conditions = conditions_df
)
#> Dropped 24 locations in series evaluation because no XG3 series are available at those locations, for the requested XG3 variables: TORP013, TORP019, TORP023, TORP025, TORP026, TORP027, TORP032, TORP033, TORP034, TORS001, TORS002, TORS003, TORS004, TORS005, TORS006, TORS007, TORS008, TORS010, TORS011, TORS012, TORS013, TORS014, TORS015, TORS017
#> # A tibble: 28 × 1
#> loc_code
#> <chr>
#> 1 TORP001
#> 2 TORP002
#> 3 TORP003
#> 4 TORP004
#> 5 TORP005
#> 6 TORP006
#> 7 TORP007
#> 8 TORP009
#> 9 TORP010
#> 10 TORP011
#> # ℹ 18 more rows
#> # ℹ Use `print(n = ...)` to see more rowsWith the argument list = TRUE you can also obtain
intermediate test results. For further information, see the
documentation of the selectlocs_xg3() function.
The get_xg3() function in the above example retrieved
XG3 values, from given locations, as a lazy object (unless
collect = TRUE). A timeframe (in hydrological years) is
used to filter XG3 values in Watina (arguments startyear
and endyear). By default, the endyear argument
is set to the previous hydrological year. Here we only provide the
startyear:
mylocs <- get_locs(watina, area_codes = "KAL")
mylocs %>% get_xg3(watina, 2010)
#> # A query: ?? x 5
#> # Database: Microsoft SQL Server
#> loc_code hydroyear lg3_lcl hg3_lcl vg3_lcl
#> <chr> <int> <dbl> <dbl> <dbl>
#> 1 KALP011 2024 NA NA NA
#> 2 KALP011 2023 NA NA -0.4
#> 3 KALP011 2022 -0.82 -0.29 -0.6
#> 4 KALP011 2021 NA NA NA
#> 5 KALP012 2021 NA NA NA
#> 6 KALP012 2022 -1.79 -0.63 -0.83
#> 7 KALP012 2024 -1.09 -0.44 -0.5
#> 8 KALP012 2023 -1.43 -0.42 -0.65
#> 9 KALP013 2021 NA NA NA
#> 10 KALP013 2022 -1.67 0.18 0.01
#> # ℹ more rows
#> # ℹ Use `print(n = ...)` to see more rowsRetrieving the data locally:
mylocs %>% get_xg3(watina, 2010, collect = TRUE)
#> # A tibble: 383 × 5
#> loc_code hydroyear lg3_lcl hg3_lcl vg3_lcl
#> <chr> <int> <dbl> <dbl> <dbl>
#> 1 KALP011 2021 NA NA NA
#> 2 KALP011 2022 -0.82 -0.29 -0.6
#> 3 KALP011 2023 NA NA -0.4
#> 4 KALP011 2024 NA NA NA
#> 5 KALP012 2021 NA NA NA
#> 6 KALP012 2022 -1.79 -0.63 -0.83
#> 7 KALP012 2023 -1.43 -0.42 -0.65
#> 8 KALP012 2024 -1.09 -0.44 -0.5
#> 9 KALP012 2025 -1.69 -0.6 -0.7
#> 10 KALP013 2021 NA NA NA
#> # ℹ 373 more rows
#> # ℹ Use `print(n = ...)` to see more rowsBy default, the “local” vertical coordinate reference system (CRS) is
used to express water levels, but also the CRS Ostend height (EPSG 5710, also known as ‘TAW’ or ‘DNG’) is
available from the data warehouse by setting
vert_crs = "ostend".
mylocs %>% get_xg3(watina, 2010, vert_crs = "ostend")
#> # A query: ?? x 5
#> # Database: Microsoft SQL Server
#> loc_code hydroyear lg3_ost hg3_ost vg3_ost
#> <chr> <int> <dbl> <dbl> <dbl>
#> 1 KALP011 2021 NA NA NA
#> 2 KALP011 2022 18.3 18.8 18.5
#> 3 KALP011 2023 NA NA 18.8
#> 4 KALP011 2024 NA NA NA
#> 5 KALP012 2024 19.6 20.2 20.2
#> 6 KALP012 2021 NA NA NA
#> 7 KALP012 2022 18.9 20.0 19.8
#> 8 KALP012 2023 19.2 20.2 20.0
#> 9 KALP012 2025 19.0 20.1 20.0
#> 10 KALP013 2021 NA NA NA
#> # ℹ more rows
#> # ℹ Use `print(n = ...)` to see more rowsJoining results to mylocs:
mylocs %>%
get_xg3(watina, 2010) %>%
left_join(
mylocs %>%
select(-loc_wid),
.
) %>%
collect()
#> Joining with `by = join_by(loc_code)`
#> # A tibble: 490 × 20
#> loc_code area_code area_name x y loc_validitycode loc_validity
#> <chr> <chr> <chr> <dbl> <dbl> <chr> <chr>
#> 1 KALP011 KAL Kalmthouts… 155827 231840 VLD Gevalideerd
#> 2 KALP011 KAL Kalmthouts… 155827 231840 VLD Gevalideerd
#> 3 KALP011 KAL Kalmthouts… 155827 231840 VLD Gevalideerd
#> 4 KALP011 KAL Kalmthouts… 155827 231840 VLD Gevalideerd
#> 5 KALP012 KAL Kalmthouts… 155725 231631 VLD Gevalideerd
#> 6 KALP012 KAL Kalmthouts… 155725 231631 VLD Gevalideerd
#> 7 KALP012 KAL Kalmthouts… 155725 231631 VLD Gevalideerd
#> 8 KALP012 KAL Kalmthouts… 155725 231631 VLD Gevalideerd
#> 9 KALP012 KAL Kalmthouts… 155725 231631 VLD Gevalideerd
#> 10 KALP013 KAL Kalmthouts… 155857 231322 VLD Gevalideerd
#> # ℹ 480 more rows
#> # ℹ 13 more variables: loc_typecode <chr>, loc_typename <chr>,
#> # obswell_statecode <chr>, obswell_state <chr>, soilsurf_ost <dbl>,
#> # measuringref_ost <dbl>, tubelength <dbl>, filterlength <dbl>,
#> # filterdepth <dbl>, hydroyear <int>, lg3_lcl <dbl>, hg3_lcl <dbl>,
#> # vg3_lcl <dbl>
#> # ℹ Use `print(n = ...)` to see more rowsYou can characterize the locations of a dataset of XG3 values, using
the eval_xg3_avail() and eval_xg3_series()
functions. You are invited to read their documentation and try their
examples!
The selectlocs_xg3() function, of which we saw a
demonstration above, sits on top of these. It calls
eval_xg3_avail() and eval_xg3_series() by
itself, but alternatively the user can provide the result of those
functions as input to selectlocs_xg3().