Using XG3 values to characterize and select locations

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.

Overview

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:

  • multiple successive years are available with both an LG3 and a HG3 value. We call such a multi-year series of an XG3 variable an XG3 series.
  • we restrict the concept of an XG3 series to the situations where the minimum series length is 5 years, and where years with missing data (for LG3 and/or HG3) must be single (gaps in a series can not be longer than 1 year). However the user is free to choose this, using the min_dur and max_gap arguments.
  • the last year of the XG3 series must be 2015 or later.

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 rows

With the argument list = TRUE you can also obtain intermediate test results. For further information, see the documentation of the selectlocs_xg3() function.

The basics: obtaining XG3 values

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 rows

Retrieving 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 rows

By 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 rows

Joining 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 rows

Processing XG3 values and selecting locations

You 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().