From 2ab61a334288363354e06c35fffd35473fe33b6a Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 21 Jan 2026 14:53:56 -0600 Subject: [PATCH 01/71] messing around with water use --- DESCRIPTION | 3 +- NAMESPACE | 1 + R/readNWISunit.R | 30 +---- R/read_waterdata_use.R | 138 +++++++++++++++++++++++ R/walk_pages.R | 3 +- man/readNWISuse.Rd | 26 ----- man/read_waterdata_use_data.Rd | 90 +++++++++++++++ tests/testthat/tests_userFriendly_fxns.R | 50 ++++---- vignettes/Status.Rmd | 7 +- vignettes/dataRetrieval.Rmd | 20 ++-- vignettes/tutorial.Rmd | 2 +- 11 files changed, 275 insertions(+), 95 deletions(-) create mode 100644 R/read_waterdata_use.R create mode 100644 man/read_waterdata_use_data.Rd diff --git a/DESCRIPTION b/DESCRIPTION index e61e5727c..9b9c653d5 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -55,7 +55,8 @@ Imports: jsonlite, httr2, whisker, - sf + sf, + data.table Suggests: covr, dplyr, diff --git a/NAMESPACE b/NAMESPACE index 11b2921a1..8f3a68cd4 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -57,6 +57,7 @@ export(read_waterdata_monitoring_location) export(read_waterdata_parameter_codes) export(read_waterdata_samples) export(read_waterdata_ts_meta) +export(read_waterdata_use_data) export(renameNWISColumns) export(setAccess) export(stateCd) diff --git a/R/readNWISunit.R b/R/readNWISunit.R index 387f08985..8083652f3 100644 --- a/R/readNWISunit.R +++ b/R/readNWISunit.R @@ -711,36 +711,18 @@ readNWISstat <- function(siteNumbers, parameterCd, startDate = "", endDate = "", #' County and state fields will be included as appropriate. #' #' @export -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # All data for a county -#' allegheny <- readNWISuse(stateCd = "Pennsylvania", countyCd = "Allegheny") -#' -#' # Data for an entire state for certain years -#' ohio <- readNWISuse(years = c(2000, 2005, 2010), stateCd = "OH", countyCd = NULL) -#' -#' # Data for an entire state, county by county -#' pr <- readNWISuse(years = c(2000, 2005, 2010), stateCd = "PR", countyCd = "ALL") -#' -#' # All national-scale data, transforming data frame to named columns from named rows -#' national <- readNWISuse(stateCd = NULL, countyCd = NULL, transform = TRUE) -#' -#' # Washington, DC data -#' dc <- readNWISuse(stateCd = "DC", countyCd = NULL) -#' -#' # data for multiple counties, with different input formatting -#' paData <- readNWISuse(stateCd = "42", countyCd = c("Allegheny County", "BUTLER", 1, "031")) -#' -#' # retrieving two specific categories for an entire state -#' ks <- readNWISuse(stateCd = "KS", countyCd = NULL, categories = c("IT", "LI")) -#' } readNWISuse <- function(stateCd, countyCd, years = "ALL", categories = "ALL", convertType = TRUE, transform = FALSE) { - message(new_nwis_message()) + + .Deprecated(new = "read_waterdata_use.", + package = "dataRetrieval", + msg = "NWIS servers are slated for decommission. Please migrate to read_waterdata_use.") + + countyID <- NULL countyCd <- countyCd[countyCd != ""] diff --git a/R/read_waterdata_use.R b/R/read_waterdata_use.R new file mode 100644 index 000000000..51fc7787c --- /dev/null +++ b/R/read_waterdata_use.R @@ -0,0 +1,138 @@ +#' Get USGS Daily Data +#' +#' @description USGS's National Water Availability Assessment Data Companion +#' (NWDC) offers web services that provide access to national-scale USGS +#' modeled water availability data underlying the National Water Availability +#' Assessment. More information at \url{https://water.usgs.gov/nwaa-data}. +#' +#' @export +#' @param model See model IDs on the NWDC data catalog page. +#' Options are : "wu-public-supply-wd", "wu-thermoelectric", "wu-irrigation-cu", +#' "wu-irrigation-wd", and "wu-public-supply-cu" +#' @param variable See variable IDs on the NWDC data catalog page. +#' @param location Options : huc12, huc10, huc8, huc6, huc4, huc2, countyCd, stateCd +#' Locations can be visualized with the Spatial Extent Viewer. Only one location +#' can be queried at a time. All data are returned on a HUC12 spatial resolution. +#' When a queried location contains more than the maximum number of HUC12s +#' allowed per page or file (defined under limit below), multiple pages or files +#' will be returned. All huc12, huc10, and countyCd location queries return a +#' single page or file. All huc2 location queries return multiple pages or files. +#' All other (huc8, huc6, huc4, stateCd) location queries may or may not return +#' multiple pages or files, depending on their size. +#' @param timeres Options : monthly, annualcy, annualwy. +#' @param startdate Format : YYYY (for annual data) or YYYY-MM (for monthly data) +#' @param enddate Format : YYYY (for annual data) or YYYY-MM (for monthly data) +#' @param intersection Options : overlap, envelop +#' @param limit Defines the number of HUC12s returned per page or file. +#' Queries of locations containing more than the below maximum value of HUC12s +#' will return multiple pages or files (see location above for details). +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' wu1 <- read_waterdata_use_data(model = "wu-public-supply-wd", +#' variable = c("pswdtot", "pswdgw", "pswdsw"), +#' location = "stateCd:RI", +#' startdate = "2020-01", +#' timeres = "monthly") +#' +#' wu2 <- read_waterdata_use_data(model = "wu-thermoelectric", +#' variable = c('tecufgw', 'tecufsw', 'tecuftot', +#' 'tewdfgw', 'tewdfsw', 'tewdftot', +#' 'tewdssw'), +#' location = "stateCd:RI", +#' startdate = "2020-01", +#' timeres = "monthly") +#' +#' wu3 <- read_waterdata_use_data(model = "wu-irrigation-cu", +#' variable = "irrcutot", +#' location = "stateCd:WI", +#' startdate = "2020-01", +#' timeres = "monthly") +#' +#' wu4 <- read_waterdata_use_data(model = "wu-irrigation-wd", +#' variable = c("irrwdtot", "irrwdgw", "irrwdsw"), +#' location = "huc2:04", +#' startdate = "2015", +#' timeres = "annualcy") +#' +#' wu5 <- read_waterdata_use_data(model = "wu-public-supply-cu", +#' variable = "pscutot", +#' location = "stateCd:WI", +#' startdate = "2020", +#' timeres = "annualwy") +#' } +read_waterdata_use_data <- function(model = NA_character_, + variable = NA_character_, + location = NA_character_, + timeres = NA_character_, + startdate = NA_character_, + enddate = NA_character_, + intersection = "overlap", + limit = 600){ + + args <- mget(names(formals())) + args <- Filter(Negate(anyNA), args) + format <- "json" + + baseURL <- httr2::request("https://api.water.usgs.gov/") |> + httr2::req_url_path_append("nwaa-data") |> + httr2::req_url_path_append("data") |> + httr2::req_user_agent(default_ua()) |> + httr2::req_headers(`Accept` = "application/json") |> + httr2::req_url_query(format = format ) |> + httr2::req_error(body = error_body) |> + httr2::req_timeout(seconds = 180) + + baseURL <- explode_query(baseURL, POST = FALSE, args, multi = "comma") + + message("Requesting:\n", baseURL$url) + if(format == "csv"){ + resp <- httr2::req_perform(baseURL) + body <- httr2::resp_body_string(resp) + df <- suppressMessages(data.table::fread(file = body, data.table = FALSE) ) + + } else { + resps <- httr2::req_perform_iterative(baseURL, + next_req = next_req_url_wu, + max_reqs = Inf, on_error = "stop") + + df <- data.frame() + + for(resp in resps){ + body <- httr2::resp_body_json(resp)[["data"]][[1]] + for(i in 1:length(body)){ + + df_i <- suppressWarnings(data.table::rbindlist(body[[i]], fill = TRUE)) |> + data.table::setDF() + df_i$location <- names(body[i]) + df <- rbind(df, df_i) + } + } + } + + attr(df, "request") <- baseURL + attr(df, "queryTime") <- Sys.time() + return(df) + +} + +next_req_url_wu <- function(resp, req){ + + body <- httr2::resp_body_json(resp) + + links <- body$metadata$links + if(any(sapply(links, function(x) x$rel) == "next")){ + next_index <- which(sapply(links, function(x) x$rel) == "next") + + next_url <- links[[next_index]][["href"]] + next_url <- gsub(pattern = "https://water.usgs.gov", + replacement = "https://api.water.usgs.gov", + x = next_url) + return(httr2::req_url(req = req, url = next_url)) + } else { + return(NULL) + } + +} + + diff --git a/R/walk_pages.R b/R/walk_pages.R index e83fcdb7c..b0a08d27c 100644 --- a/R/walk_pages.R +++ b/R/walk_pages.R @@ -15,7 +15,6 @@ walk_pages <- function(req){ df1 <- get_resp_data(resp) return_list <- rbind(return_list, df1) } - return(return_list) } @@ -106,7 +105,7 @@ get_csv <- function(req, limit){ if(httr2::resp_has_body(resp)){ return_list <- httr2::resp_body_string(resp) - df <- suppressMessages(readr::read_csv(file = return_list)) + df <- suppressMessages(data.table::fread(text = return_list, data.table = FALSE)) if(skip_geo){ df <- df[, names(df)[!names(df) %in% c("x", "y")]] } else { diff --git a/man/readNWISuse.Rd b/man/readNWISuse.Rd index db926c349..bbe4ecf5d 100644 --- a/man/readNWISuse.Rd +++ b/man/readNWISuse.Rd @@ -53,29 +53,3 @@ Retrieves water use data from USGS Water Use Data for the Nation. See \url{https://waterdata.usgs.gov/nwis/wu} for more information. All available use categories for the supplied arguments are retrieved. } -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# All data for a county -allegheny <- readNWISuse(stateCd = "Pennsylvania", countyCd = "Allegheny") - -# Data for an entire state for certain years -ohio <- readNWISuse(years = c(2000, 2005, 2010), stateCd = "OH", countyCd = NULL) - -# Data for an entire state, county by county -pr <- readNWISuse(years = c(2000, 2005, 2010), stateCd = "PR", countyCd = "ALL") - -# All national-scale data, transforming data frame to named columns from named rows -national <- readNWISuse(stateCd = NULL, countyCd = NULL, transform = TRUE) - -# Washington, DC data -dc <- readNWISuse(stateCd = "DC", countyCd = NULL) - -# data for multiple counties, with different input formatting -paData <- readNWISuse(stateCd = "42", countyCd = c("Allegheny County", "BUTLER", 1, "031")) - -# retrieving two specific categories for an entire state -ks <- readNWISuse(stateCd = "KS", countyCd = NULL, categories = c("IT", "LI")) -} -\dontshow{\}) # examplesIf} -} diff --git a/man/read_waterdata_use_data.Rd b/man/read_waterdata_use_data.Rd new file mode 100644 index 000000000..2c4503f08 --- /dev/null +++ b/man/read_waterdata_use_data.Rd @@ -0,0 +1,90 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_waterdata_use.R +\name{read_waterdata_use_data} +\alias{read_waterdata_use_data} +\title{Get USGS Daily Data} +\usage{ +read_waterdata_use_data( + model = NA_character_, + variable = NA_character_, + location = NA_character_, + timeres = NA_character_, + startdate = NA_character_, + enddate = NA_character_, + intersection = "overlap", + limit = 600 +) +} +\arguments{ +\item{model}{See model IDs on the NWDC data catalog page. +Options are : "wu-public-supply-wd", "wu-thermoelectric", "wu-irrigation-cu", +"wu-irrigation-wd", and "wu-public-supply-cu"} + +\item{variable}{See variable IDs on the NWDC data catalog page.} + +\item{location}{Options : huc12, huc10, huc8, huc6, huc4, huc2, countyCd, stateCd +Locations can be visualized with the Spatial Extent Viewer. Only one location +can be queried at a time. All data are returned on a HUC12 spatial resolution. +When a queried location contains more than the maximum number of HUC12s +allowed per page or file (defined under limit below), multiple pages or files +will be returned. All huc12, huc10, and countyCd location queries return a +single page or file. All huc2 location queries return multiple pages or files. +All other (huc8, huc6, huc4, stateCd) location queries may or may not return +multiple pages or files, depending on their size.} + +\item{timeres}{Options : monthly, annualcy, annualwy.} + +\item{startdate}{Format : YYYY (for annual data) or YYYY-MM (for monthly data)} + +\item{enddate}{Format : YYYY (for annual data) or YYYY-MM (for monthly data)} + +\item{intersection}{Options : overlap, envelop} + +\item{limit}{Defines the number of HUC12s returned per page or file. +Queries of locations containing more than the below maximum value of HUC12s +will return multiple pages or files (see location above for details).} +} +\description{ +USGS's National Water Availability Assessment Data Companion +(NWDC) offers web services that provide access to national-scale USGS +modeled water availability data underlying the National Water Availability +Assessment. More information at \url{https://water.usgs.gov/nwaa-data}. +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +wu1 <- read_waterdata_use_data(model = "wu-public-supply-wd", + variable = c("pswdtot", "pswdgw", "pswdsw"), + location = "stateCd:RI", + startdate = "2020-01", + timeres = "monthly") + +wu2 <- read_waterdata_use_data(model = "wu-thermoelectric", + variable = c('tecufgw', 'tecufsw', 'tecuftot', + 'tewdfgw', 'tewdfsw', 'tewdftot', + 'tewdssw'), + location = "stateCd:RI", + startdate = "2020-01", + timeres = "monthly") + +wu3 <- read_waterdata_use_data(model = "wu-irrigation-cu", + variable = "irrcutot", + location = "stateCd:WI", + startdate = "2020-01", + timeres = "monthly") + +wu4 <- read_waterdata_use_data(model = "wu-irrigation-wd", + variable = c("irrwdtot", "irrwdgw", "irrwdsw"), + location = "huc2:04", + startdate = "2015", + timeres = "annualcy") + +wu5 <- read_waterdata_use_data(model = "wu-public-supply-cu", + variable = "pscutot", + location = "stateCd:WI", + startdate = "2020", + timeres = "annualwy") +} +\dontshow{\}) # examplesIf} +} diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index fa7783782..fd282758e 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -224,31 +224,31 @@ test_that("readNWISstat tests", { expect_gt(nrow(annualData), 2) }) -context("readNWISuse tests") -test_that("readNWISuse tests", { - testthat::skip_on_cran() - skip_on_ci() - dc <- readNWISuse( - years = c(2000, 2005, 2010), - stateCd = "DC", countyCd = NULL - ) - expect_true(nrow(dc) == 3) - expect_is(dc$state_cd, "character") - - ohio <- readNWISuse( - years = 2005, - stateCd = "OH", - countyCd = "ALL" - ) - expect_true(nrow(ohio) == 88) - - twoCounties <- readNWISuse( - years = 2010, - stateCd = "PA", - countyCd = c("Cambria", "Indiana") - ) - expect_true(nrow(twoCounties) == 2) -}) +# context("readNWISuse tests") +# test_that("readNWISuse tests", { +# testthat::skip_on_cran() +# skip_on_ci() +# dc <- readNWISuse( +# years = c(2000, 2005, 2010), +# stateCd = "DC", countyCd = NULL +# ) +# expect_true(nrow(dc) == 3) +# expect_is(dc$state_cd, "character") +# +# ohio <- readNWISuse( +# years = 2005, +# stateCd = "OH", +# countyCd = "ALL" +# ) +# expect_true(nrow(ohio) == 88) +# +# twoCounties <- readNWISuse( +# years = 2010, +# stateCd = "PA", +# countyCd = c("Cambria", "Indiana") +# ) +# expect_true(nrow(twoCounties) == 2) +# }) context("state tests") test_that("state county tests", { diff --git a/vignettes/Status.Rmd b/vignettes/Status.Rmd index 9cf91c27d..d32d83033 100644 --- a/vignettes/Status.Rmd +++ b/vignettes/Status.Rmd @@ -44,10 +44,10 @@ df <- data.frame( "readNWISmeas", "readNWISdata", "readNWISuv", + "readNWISuse", "readNWISrating", "readNWISstat", "readNWISpeak", - "readNWISuse", "whatNWISdata" ), New = c( @@ -60,10 +60,11 @@ df <- data.frame( "read_waterdata_field_measurements", "read_waterdata", "read_waterdata_continuous", - rep("", 5) + "read_waterdata_use_data", + rep("", 4) ), "Available on (branch)" = c(rep("main (CRAN)", 8), - "develop", rep("", 5)) + "develop", "develop", rep("", 4)) ) knitr::kable(df, col.names = c("WaterServices (legacy) function", "Water Data (new) function", "Available on (branch name)")) diff --git a/vignettes/dataRetrieval.Rmd b/vignettes/dataRetrieval.Rmd index 92623e0ae..aecc49158 100644 --- a/vignettes/dataRetrieval.Rmd +++ b/vignettes/dataRetrieval.Rmd @@ -75,7 +75,7 @@ Functions <- c( "read_waterdata_field_measurements", "readNWISpeak", "read_waterdata_field_measurements", - "readNWISuse", + "read_waterdata_water_data", "readNWISstat", "read_waterdata_parameter_codes", "read_waterdata_monitoring_location", @@ -123,7 +123,8 @@ Source <- c("USGS Water Data API", "USGS Water Data API", "NWIS", "USGS Water Data API", - rep("NWIS",2), + "USGS Water Data API", + "NWIS", "USGS Water Data API", "USGS Water Data API", "USGS Samples Data", @@ -412,20 +413,13 @@ surfaceData <- read_waterdata_field_measurements(monitoring_location_id = "USGS- ## Water Use Data -Retrieves water use data from USGS Water Use Data for the Nation. See [https://waterdata.usgs.gov/nwis/wu](https://waterdata.usgs.gov/nwis/wu) for more information. All available use categories for the supplied arguments are retrieved. +Retrieves water use data from USGS Water Use Data for the Nation. See for more information. ```{r eval=FALSE} -allegheny <- readNWISuse( - stateCd = "Pennsylvania", - countyCd = "Allegheny" -) +allegheny <- read_waterdata_use_data(location = "countyCd:42003", + model = "wu-public-supply-wd", + variable = c("pswdtot", "pswdgw", "pswdsw")) - -national <- readNWISuse( - stateCd = NULL, - countyCd = NULL, - transform = TRUE -) ``` ## Statistics Data diff --git a/vignettes/tutorial.Rmd b/vignettes/tutorial.Rmd index 825ffbde1..cb5d68f29 100644 --- a/vignettes/tutorial.Rmd +++ b/vignettes/tutorial.Rmd @@ -114,7 +114,7 @@ There are many types of data available from `dataRetrieval`. To understand how t |stat|`readNWISstat`| Site statistics | None yet | |rating|`readNWISrating`| Rating curves| None yet | |peak|`readNWISpeak`|Peak flow| None yet | -|use|`readNWISuse`|Water Use| None yet | +|use|`readNWISuse`|Water Use| `read_waterdata_use_data` | |meas|`readNWISmeas`|Discrete surface water| `read_waterdata_field_measurements`| | | `readNWISdata` | General data import | `read_waterdata` | From e70ff54de0f753b210ce18adb7b4d7bdd476fe90 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 22 Jan 2026 12:13:52 -0600 Subject: [PATCH 02/71] Just use csv, it's a little faster --- R/read_waterdata_use.R | 62 +++++++++-------------- man/read_waterdata_continuous.Rd | 2 +- man/read_waterdata_daily.Rd | 4 +- man/read_waterdata_field_measurements.Rd | 4 +- man/read_waterdata_latest_continuous.Rd | 2 +- man/read_waterdata_latest_daily.Rd | 4 +- man/read_waterdata_monitoring_location.Rd | 40 +++++++-------- man/read_waterdata_ts_meta.Rd | 4 +- 8 files changed, 55 insertions(+), 67 deletions(-) diff --git a/R/read_waterdata_use.R b/R/read_waterdata_use.R index 51fc7787c..ba4c07d6b 100644 --- a/R/read_waterdata_use.R +++ b/R/read_waterdata_use.R @@ -72,7 +72,8 @@ read_waterdata_use_data <- function(model = NA_character_, args <- mget(names(formals())) args <- Filter(Negate(anyNA), args) - format <- "json" + + format <- "csv" baseURL <- httr2::request("https://api.water.usgs.gov/") |> httr2::req_url_path_append("nwaa-data") |> @@ -86,29 +87,16 @@ read_waterdata_use_data <- function(model = NA_character_, baseURL <- explode_query(baseURL, POST = FALSE, args, multi = "comma") message("Requesting:\n", baseURL$url) - if(format == "csv"){ - resp <- httr2::req_perform(baseURL) - body <- httr2::resp_body_string(resp) - df <- suppressMessages(data.table::fread(file = body, data.table = FALSE) ) - - } else { - resps <- httr2::req_perform_iterative(baseURL, - next_req = next_req_url_wu, - max_reqs = Inf, on_error = "stop") - - df <- data.frame() - for(resp in resps){ - body <- httr2::resp_body_json(resp)[["data"]][[1]] - for(i in 1:length(body)){ + resps <- httr2::req_perform_iterative(baseURL, + next_req = next_req_url_wu_csv, + max_reqs = Inf, on_error = "stop") - df_i <- suppressWarnings(data.table::rbindlist(body[[i]], fill = TRUE)) |> - data.table::setDF() - df_i$location <- names(body[i]) - df <- rbind(df, df_i) - } - } - } + df <- resps |> + httr2::resps_successes() |> + httr2::resps_data(\(resp) data.table::fread(text = httr2::resp_body_string(resp), + data.table = FALSE, + colClasses = list(character = "huc12_id"))) attr(df, "request") <- baseURL attr(df, "queryTime") <- Sys.time() @@ -116,23 +104,23 @@ read_waterdata_use_data <- function(model = NA_character_, } -next_req_url_wu <- function(resp, req){ +next_req_url_wu_csv <- function(resp, req){ - body <- httr2::resp_body_json(resp) - - links <- body$metadata$links - if(any(sapply(links, function(x) x$rel) == "next")){ - next_index <- which(sapply(links, function(x) x$rel) == "next") - - next_url <- links[[next_index]][["href"]] - next_url <- gsub(pattern = "https://water.usgs.gov", - replacement = "https://api.water.usgs.gov", - x = next_url) - return(httr2::req_url(req = req, url = next_url)) - } else { - return(NULL) + headers <- httr2::resp_headers(resp) + if("link" %in% names(headers)){ + if(grepl(pattern = '\"next\"', headers$link)){ + next_url <- gsub(pattern = ".*<(.*)>.*", + replacement = "\\1", + x = headers$link) + next_url <- gsub(pattern = "https://water.usgs.gov", + replacement = "https://api.water.usgs.gov", + x = next_url) + return(httr2::req_url(req = req, url = next_url)) + } } - + return(NULL) } + + diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index e97db63bd..4542788d5 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -25,7 +25,7 @@ read_waterdata_continuous( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://help.waterdata.usgs.gov/codes-and-parameters/parameters}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} diff --git a/man/read_waterdata_daily.Rd b/man/read_waterdata_daily.Rd index 043d6c7e2..44522f354 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -28,11 +28,11 @@ read_waterdata_daily( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://help.waterdata.usgs.gov/codes-and-parameters/parameters}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} -\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://help.waterdata.usgs.gov/code/stat_cd_nm_query?stat_nm_cd=\%25&fmt=html}. +\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/statistic-codes/items}. Multiple statistic_ids can be requested as a character vector.} diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index 4df1dd454..cec758b01 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -31,7 +31,7 @@ read_waterdata_field_measurements( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://help.waterdata.usgs.gov/codes-and-parameters/parameters}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} @@ -66,7 +66,7 @@ Only features that have a \code{last_modified} that intersects the value of date \item{observing_procedure}{Water measurement or water-quality observing procedure descriptions.} -\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. \href{https://help.waterdata.usgs.gov/code/alt_datum_cd_query?fmt=html}{A list of codes is available.}} +\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} \item{measuring_agency}{The agency performing the measurement.} diff --git a/man/read_waterdata_latest_continuous.Rd b/man/read_waterdata_latest_continuous.Rd index 90b78a4c2..8fea80e7d 100644 --- a/man/read_waterdata_latest_continuous.Rd +++ b/man/read_waterdata_latest_continuous.Rd @@ -27,7 +27,7 @@ read_waterdata_latest_continuous( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://help.waterdata.usgs.gov/codes-and-parameters/parameters}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} diff --git a/man/read_waterdata_latest_daily.Rd b/man/read_waterdata_latest_daily.Rd index 330d7fb35..d6fc4e98e 100644 --- a/man/read_waterdata_latest_daily.Rd +++ b/man/read_waterdata_latest_daily.Rd @@ -28,11 +28,11 @@ read_waterdata_latest_daily( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://help.waterdata.usgs.gov/codes-and-parameters/parameters}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} -\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://help.waterdata.usgs.gov/code/stat_cd_nm_query?stat_nm_cd=\%25&fmt=html}. +\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/statistic-codes/items}. Multiple statistic_ids can be requested as a character vector.} diff --git a/man/read_waterdata_monitoring_location.Rd b/man/read_waterdata_monitoring_location.Rd index ed8132e8a..118ede088 100644 --- a/man/read_waterdata_monitoring_location.Rd +++ b/man/read_waterdata_monitoring_location.Rd @@ -56,11 +56,11 @@ read_waterdata_monitoring_location( Multiple monitoring_location_ids can be requested as a character vector.} -\item{agency_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available \href{https://help.waterdata.usgs.gov/code/agency_cd_query?fmt=html}{at this link}.} +\item{agency_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} \item{agency_name}{The name of the agency that is reporting the data.} -\item{monitoring_location_number}{Each monitoring location in the USGS data base has a unique 8- to 15-digit identification number. Monitoring location numbers are assigned \href{https://help.waterdata.usgs.gov/faq/sites/do-station-numbers-have-any-particular-meaning}{based on this logic}.} +\item{monitoring_location_number}{Each monitoring location in the USGS data base has a unique 8- to 15-digit identification number.} \item{monitoring_location_name}{This is the official name of the monitoring location in the database. For well information this can be a district-assigned local number.} @@ -74,15 +74,15 @@ Multiple monitoring_location_ids can be requested as a character vector.} \item{state_name}{The name of the state or state equivalent in which the monitoring location is located.} -\item{county_code}{The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. \href{https://help.waterdata.usgs.gov/code/county_query?fmt=html}{A list of codes is available.}} +\item{county_code}{The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items}.} -\item{county_name}{The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. \href{https://help.waterdata.usgs.gov/code/county_query?fmt=html}{A list of codes is available.}} +\item{county_name}{The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. [A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items}.} \item{minor_civil_division_code}{Codes for primary governmental or administrative divisions of the county or county equivalent in which the monitoring location is located.} -\item{site_type_code}{A code describing the hydrologic setting of the monitoring location. \href{https://help.waterdata.usgs.gov/code/site_tp_query?fmt=html}{A list of codes is available.}} +\item{site_type_code}{A code describing the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} -\item{site_type}{A description of the hydrologic setting of the monitoring location. \href{https://help.waterdata.usgs.gov/code/site_tp_query?fmt=html}{A list of codes is available.}} +\item{site_type}{A description of the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} \item{hydrologic_unit_code}{The United States is divided and sub-divided into successively smaller hydrologic units which are classified into four levels: regions, sub-regions, accounting units, and cataloging units. The hydrologic units are arranged within each other, from the smallest (cataloging units) to the largest (regions). Each hydrologic unit is identified by a unique hydrologic unit code (HUC) consisting of two to eight digits based on the four levels of classification in the hydrologic unit system.} @@ -92,25 +92,25 @@ Multiple monitoring_location_ids can be requested as a character vector.} \item{altitude_accuracy}{Accuracy of the altitude, in feet. An accuracy of +/- 0.1 foot would be entered as “.1”. Many altitudes are interpolated from the contours on topographic maps; accuracies determined in this way are generally entered as one-half of the contour interval.} -\item{altitude_method_code}{Codes representing the method used to measure altitude. \href{https://help.waterdata.usgs.gov/code/alt_meth_cd_query?fmt=html}{A list of codes is available.}} +\item{altitude_method_code}{Codes representing the method used to measure altitude.} -\item{altitude_method_name}{The name of the the method used to measure altitude. \href{https://help.waterdata.usgs.gov/code/alt_meth_cd_query?fmt=html}{A list of codes is available.}} +\item{altitude_method_name}{The name of the the method used to measure altitude.} -\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. \href{https://help.waterdata.usgs.gov/code/alt_datum_cd_query?fmt=html}{A list of codes is available.}} +\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} -\item{vertical_datum_name}{The datum used to determine altitude and vertical position at the monitoring location. \href{https://help.waterdata.usgs.gov/code/alt_datum_cd_query?fmt=html}{A list of codes is available.}} +\item{vertical_datum_name}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} -\item{horizontal_positional_accuracy_code}{Indicates the accuracy of the latitude longitude values. \href{https://help.waterdata.usgs.gov/code/coord_acy_cd_query?fmt=html}{A list of codes is available.}} +\item{horizontal_positional_accuracy_code}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items}.} -\item{horizontal_positional_accuracy}{Indicates the accuracy of the latitude longitude values. \href{https://help.waterdata.usgs.gov/code/coord_acy_cd_query?fmt=html}{A list of codes is available.}} +\item{horizontal_positional_accuracy}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items}.} -\item{horizontal_position_method_code}{Indicates the method used to determine latitude longitude values. \href{https://help.waterdata.usgs.gov/code/coord_meth_cd_query?fmt=html}{A list of codes is available.}} +\item{horizontal_position_method_code}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items}.} -\item{horizontal_position_method_name}{Indicates the method used to determine latitude longitude values. \href{https://help.waterdata.usgs.gov/code/coord_meth_cd_query?fmt=html}{A list of codes is available.}} +\item{horizontal_position_method_name}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items}.} -\item{original_horizontal_datum}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. \href{https://help.waterdata.usgs.gov/code/coord_datum_cd_query?fmt=html}{A list of codes is available.}} +\item{original_horizontal_datum}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items}.} -\item{original_horizontal_datum_name}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. \href{https://help.waterdata.usgs.gov/code/coord_datum_cd_query?fmt=html}{A list of codes is available.}} +\item{original_horizontal_datum_name}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items}.} \item{drainage_area}{The area enclosed by a topographic divide from which direct surface runoff from precipitation normally drains by gravity into the stream above that point.} @@ -122,17 +122,17 @@ Multiple monitoring_location_ids can be requested as a character vector.} \item{construction_date}{Date the well was completed.} -\item{aquifer_code}{Local aquifers in the USGS water resources data base are identified by a geohydrologic unit code (a three-digit number related to the age of the formation, followed by a 4 or 5 character abbreviation for the geologic unit or aquifer name). \href{https://help.waterdata.usgs.gov/faq/groundwater/local-aquifer-description}{Additional information is available at this link.}} +\item{aquifer_code}{Local aquifers in the USGS water resources data base are identified by a geohydrologic unit code (a three-digit number related to the age of the formation, followed by a 4 or 5 character abbreviation for the geologic unit or aquifer name).} -\item{national_aquifer_code}{National aquifers are the principal aquifers or aquifer systems in the United States, defined as regionally extensive aquifers or aquifer systems that have the potential to be used as a source of potable water. Not all groundwater monitoring locations can be associated with a National Aquifer. Such monitoring locations will not be retrieved using this search criteria. \href{https://help.waterdata.usgs.gov/code/nat_aqfr_query?fmt=html}{A list of National aquifer codes and names is available.}} +\item{national_aquifer_code}{National aquifers are the principal aquifers or aquifer systems in the United States, defined as regionally extensive aquifers or aquifer systems that have the potential to be used as a source of potable water. Not all groundwater monitoring locations can be associated with a National Aquifer. Such monitoring locations will not be retrieved using this search criteria. A list of National aquifer codes and names is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/national-aquifer-codes/items}.} -\item{aquifer_type_code}{Groundwater occurs in aquifers under two different conditions. Where water only partly fills an aquifer, the upper surface is free to rise and decline. These aquifers are referred to as unconfined (or water-table) aquifers. Where water completely fills an aquifer that is overlain by a confining bed, the aquifer is referred to as a confined (or artesian) aquifer. When a confined aquifer is penetrated by a well, the water level in the well will rise above the top of the aquifer (but not necessarily above land surface). \href{https://help.waterdata.usgs.gov/faq/groundwater/local-aquifer-description}{Additional information is available at this link.}} +\item{aquifer_type_code}{Groundwater occurs in aquifers under two different conditions. Where water only partly fills an aquifer, the upper surface is free to rise and decline. These aquifers are referred to as unconfined (or water-table) aquifers. Where water completely fills an aquifer that is overlain by a confining bed, the aquifer is referred to as a confined (or artesian) aquifer. When a confined aquifer is penetrated by a well, the water level in the well will rise above the top of the aquifer (but not necessarily above land surface).} \item{well_constructed_depth}{The depth of the finished well, in feet below land surface datum. Note: Not all groundwater monitoring locations have information on Well Depth. Such monitoring locations will not be retrieved using this search criteria.} \item{hole_constructed_depth}{The total depth to which the hole is drilled, in feet below land surface datum. Note: Not all groundwater monitoring locations have information on Hole Depth. Such monitoring locations will not be retrieved using this search criteria.} -\item{depth_source_code}{A code indicating the source of water-level data. \href{https://help.waterdata.usgs.gov/code/water_level_src_cd_query?fmt=html}{A list of codes is available.}} +\item{depth_source_code}{A code indicating the source of water-level data.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: diff --git a/man/read_waterdata_ts_meta.Rd b/man/read_waterdata_ts_meta.Rd index 82cfce84d..088f1b8a4 100644 --- a/man/read_waterdata_ts_meta.Rd +++ b/man/read_waterdata_ts_meta.Rd @@ -39,7 +39,7 @@ read_waterdata_ts_meta( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://help.waterdata.usgs.gov/codes-and-parameters/parameters}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} @@ -50,7 +50,7 @@ Available options are: geometry, time_series_id, unit_of_measure, parameter_name, parameter_code, statistic_id, hydrologic_unit_code, state_name, last_modified, begin, end, begin_utc, end_utc, computation_period_identifier, computation_identifier, thresholds, sublocation_identifier, primary, monitoring_location_id, web_description, parameter_description, parent_time_series_id. The default (\code{NA}) will return all columns of the data.} -\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://help.waterdata.usgs.gov/code/stat_cd_nm_query?stat_nm_cd=\%25&fmt=html}. +\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/statistic-codes/items}. Multiple statistic_ids can be requested as a character vector.} From 758533bb7cade84e0388ffcfd1669db98841887c Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 5 Mar 2026 11:55:54 -0600 Subject: [PATCH 03/71] getting ready for NGWMN --- NAMESPACE | 9 +- NEWS | 16 +- R/AAA.R | 1 + R/construct_api_requests.R | 19 ++- R/dataRetrieval-package.R | 3 +- R/deal_with_empty.R | 12 +- R/get_ogc_documentation.R | 57 +++++-- R/readNGWMNdata.R | 255 ---------------------------- R/read_ngwmn_lithology.R | 63 +++++++ R/read_ngwmn_providers.R | 57 +++++++ R/read_ngwmn_sites.R | 136 +++++++++++++++ R/read_ngwmn_water_level.R | 96 +++++++++++ R/read_ngwmn_well_construction.R | 66 +++++++ R/setAccess.R | 1 + R/sysdata.rda | Bin 326552 -> 326576 bytes R/walk_pages.R | 4 + _pkgdown.yml | 8 +- man/check_OGC_requests.Rd | 8 +- man/construct_ngwmn_requests.Rd | 58 +++++++ man/get_ogc_params.Rd | 4 +- man/readNGWMNdata.Rd | 53 ------ man/readNGWMNlevels.Rd | 47 ----- man/readNGWMNsites.Rd | 37 ---- man/read_ngwmn_lithology.Rd | 54 ++++++ man/read_ngwmn_providers.Rd | 48 ++++++ man/read_ngwmn_sites.Rd | 133 +++++++++++++++ man/read_ngwmn_water_level.Rd | 104 ++++++++++++ man/read_ngwmn_well_construction.Rd | 57 +++++++ vignettes/tutorial.Rmd | 8 +- 29 files changed, 979 insertions(+), 435 deletions(-) delete mode 100644 R/readNGWMNdata.R create mode 100644 R/read_ngwmn_lithology.R create mode 100644 R/read_ngwmn_providers.R create mode 100644 R/read_ngwmn_sites.R create mode 100644 R/read_ngwmn_water_level.R create mode 100644 R/read_ngwmn_well_construction.R create mode 100644 man/construct_ngwmn_requests.Rd delete mode 100644 man/readNGWMNdata.Rd delete mode 100644 man/readNGWMNlevels.Rd delete mode 100644 man/readNGWMNsites.Rd create mode 100644 man/read_ngwmn_lithology.Rd create mode 100644 man/read_ngwmn_providers.Rd create mode 100644 man/read_ngwmn_sites.Rd create mode 100644 man/read_ngwmn_water_level.Rd create mode 100644 man/read_ngwmn_well_construction.Rd diff --git a/NAMESPACE b/NAMESPACE index 67434a709..061ba096e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -8,6 +8,7 @@ export(check_waterdata_sample_params) export(constructNWISURL) export(constructWQPURL) export(construct_api_requests) +export(construct_ngwmn_requests) export(construct_waterdata_sample_request) export(countyCd) export(countyCdLookup) @@ -27,9 +28,6 @@ export(pCodeToName) export(parameterCdFile) export(parse_WQP) export(pcode_to_name) -export(readNGWMNdata) -export(readNGWMNlevels) -export(readNGWMNsites) export(readNWISdata) export(readNWISdv) export(readNWISpCode) @@ -43,6 +41,11 @@ export(readWQPdata) export(readWQPqw) export(readWQPsummary) export(read_USGS_samples) +export(read_ngwmn_lithology) +export(read_ngwmn_providers) +export(read_ngwmn_sites) +export(read_ngwmn_water_level) +export(read_ngwmn_well_construction) export(read_waterdata) export(read_waterdata_channel) export(read_waterdata_combined_meta) diff --git a/NEWS b/NEWS index 81b683c19..7cc986c91 100644 --- a/NEWS +++ b/NEWS @@ -1,25 +1,25 @@ dataRetrieval 2.7.22.9000 =================== -* Added data.table to Imports + * Added read_waterdata_stats_por and read_waterdata_stats_daterange to access USGS daily data statistics. -* Updated vignettes, examples, and README to reflect new stats functions. -* Added tests for read_waterdata_stats functions +* Added read_waterdata_field_meta, read_waterdata_combine_meta, and read_waterdata_channel +* Added read_ngwmn_water_levels, read_ngwmn_sites, read_ngwmn_providers, read_ngwmn_well_construction, read_ngwmn_lithology +* Removed readNWISgwl, readNWISmeas, and readNGWMN as services have been turned off +* Added data.table to Imports * Updated next_req_url to allow paging through /statistics API output * Added deprecation message to readNWISstat function -* Specify "UTC" attribute for returned time +* Improved time documentation for waterdata functions +* Specify "UTC" attribute for returned time for waterdata functinos * Added options("dataRetrieval.attach_request" = TRUE) as default to attach the request object as an attribute to the returned data frames. Setting options("dataRetrieval.attach_request" = FALSE) will return a data frame without the request attribute -* Improved time documentation * Improved error handling in WQP functions -* Added read_waterdata_field_meta, read_waterdata_combine_meta, -and read_waterdata_channel -* Removed readNWISgwl and readNWISmeas as services have been turned off * Updated CQL2 templates to allow HUC queries specifically to use a wildcard to get multiple inclusive HUCs. + dataRetrieval 2.7.22 =================== * Added read_waterdata_latest_daily to access latest daily USGS water data. diff --git a/R/AAA.R b/R/AAA.R index 9e7053ad7..2cd4c98ec 100644 --- a/R/AAA.R +++ b/R/AAA.R @@ -26,6 +26,7 @@ pkg.env <- new.env() "national_aquifer_code", "reliability_code", "site_types", "statistic_code", "topographic_code", "time_zone_code") + num_cols <- c() pkg.env$api_endpoints <- services pkg.env$metadata <- collections } diff --git a/R/construct_api_requests.R b/R/construct_api_requests.R index dbcd3d9ed..09de17b12 100644 --- a/R/construct_api_requests.R +++ b/R/construct_api_requests.R @@ -175,6 +175,7 @@ check_limits <- function(args){ #' Setup the request for the OGC API requests #' #' @noRd +#' @param base Character OGC or NGWMN #' @return httr2 request #' @examplesIf is_dataRetrieval_user() #' @@ -182,10 +183,18 @@ check_limits <- function(args){ #' request <- dataRetrieval:::base_url() #' request #' } -base_url <- function(){ +base_url <- function(base = "OGC"){ - httr2::request("https://api.waterdata.usgs.gov/ogcapi/") |> - httr2::req_url_path_append(getOption("dataRetrieval.api_version")) + match.arg(base, c("OGC", "NGWMN")) + + if(base == "OGC"){ + baseURL <- httr2::request("https://api.waterdata.usgs.gov/ogcapi/") |> + httr2::req_url_path_append(getOption("dataRetrieval.api_version")) + } else { + baseURL <- httr2::request("https://ngwmn-qa.wma.chs.usgs.gov/apps/ngwmn/ogcapi/") + } + + } #' Setup the request for a particular endpoint collection @@ -198,9 +207,9 @@ base_url <- function(){ #' request <- dataRetrieval:::setup_api("daily") #' request #' } -setup_api <- function(service, format = "json"){ +setup_api <- function(service, format = "json", base = "OGC"){ - baseURL <- base_url() |> + baseURL <- base_url(base) |> httr2::req_url_path_append("collections") |> httr2::req_url_path_append(service, "items") |> basic_request(format = format) diff --git a/R/dataRetrieval-package.R b/R/dataRetrieval-package.R index 7058ee59f..0099cbed8 100644 --- a/R/dataRetrieval-package.R +++ b/R/dataRetrieval-package.R @@ -214,7 +214,8 @@ NULL # } # # num_cols <- c("value", "contributing_drainage_area", "drainage_area", -# "altitude_accuracy", "well_construction_depth", +# #"altitude_accuracy", +# "well_construction_depth", # "hole_construction_depth", "channel_flow", "channel_width", # "channel_area", "channel_velocity", "channel_location_distance") # diff --git a/R/deal_with_empty.R b/R/deal_with_empty.R index e18901b5f..8f3bf835f 100644 --- a/R/deal_with_empty.R +++ b/R/deal_with_empty.R @@ -6,6 +6,7 @@ #' as "daily", "monitoring-locations", "time-series-metadata" #' @param skipGeometry A logical for whether to return geometry #' @param convertType A logical for whether to convert value to numeric +#' @param base character, either "OGC" or "NGWMN" depending on data. #' #' @return data.frame #' @noRd @@ -24,12 +25,15 @@ deal_with_empty <- function(return_list, service, skipGeometry, convertType, - no_paging = FALSE){ - + no_paging = FALSE, + base = "OGC"){ + if(nrow(return_list) == 0){ if(all(is.na(properties))){ - schema <- check_OGC_requests(endpoint = service, type = "schema") + schema <- check_OGC_requests(endpoint = service, + type = "schema", + base = base) properties <- names(schema$properties) } return_list <- data.frame(matrix(nrow = 0, @@ -37,7 +41,7 @@ deal_with_empty <- function(return_list, return_list <- lapply(return_list, as.character) names(return_list) <- properties - single_params <- c("datetime", "last_modified", "begin", "end", "time") + single_params <- c("datetime", "last_modified", "begin", "end", "time", "datetime", "sample_time") for(i in single_params){ if(i %in% names(return_list)){ diff --git a/R/get_ogc_documentation.R b/R/get_ogc_documentation.R index 0b58d2398..e5261a35f 100644 --- a/R/get_ogc_documentation.R +++ b/R/get_ogc_documentation.R @@ -3,6 +3,7 @@ #' This function populates the parameter descriptions. #' #' @param service Character, can be any of the endpoints +#' @param base Character, can be "OGC" or "NGWMN" #' @return list #' @noRd #' @examplesIf is_dataRetrieval_user() @@ -10,11 +11,14 @@ #' \donttest{ #' ml_desc <- dataRetrieval:::get_description("monitoring-locations") #' ml_desc +#' +#' wl_desc <- dataRetrieval:::get_description("waterLevelObs", base = "NGWMN") +#' wl_desc #' } #' -get_description <- function(service){ +get_description <- function(service, base = "OGC"){ - query_ret <- get_collection() + query_ret <- get_collection(base) tags <- query_ret[["tags"]] @@ -38,9 +42,9 @@ get_description <- function(service){ #' collection #' } #' -get_collection <- function(){ +get_collection <- function(base = "OGC"){ - check_collections <- base_url() |> + check_collections <- base_url(base = base) |> httr2::req_url_path_append("openapi") |> httr2::req_url_query(f = "html#/server/getCollections") @@ -58,6 +62,7 @@ get_collection <- function(){ #' available, it will also contain a description. #' #' @param service Character, can be any of the USGS Waterdata API endpoints or collections. +#' @param base Either "OGC" for waterdata, or "NGWMN". #' @return list #' @export #' @examplesIf is_dataRetrieval_user() @@ -67,9 +72,9 @@ get_collection <- function(){ #' ml$national_aquifer_code #' } #' -get_ogc_params <- function(service){ - - check_queryables_req <- base_url() |> +get_ogc_params <- function(service, base = "OGC"){ + + check_queryables_req <- base_url(base) |> httr2::req_url_path_append("collections") |> httr2::req_url_path_append(service) |> httr2::req_url_path_append("schema") |> @@ -78,7 +83,13 @@ get_ogc_params <- function(service){ query_ret <- httr2::req_perform(check_queryables_req) |> httr2::resp_body_json() - params <- sapply(query_ret$properties, function(x) x[["description"]]) + if(base == "OGC"){ + params <- sapply(query_ret$properties, function(x) x[["description"]]) + } else if (base == "NGWMN"){ + params <- query_ret$properties + } + + params } @@ -90,6 +101,7 @@ get_ogc_params <- function(service){ #' #' @param service Character, can be any of the endpoints #' @param output_id Character, dataRetrieval output name +#' @param base Character, either "OGC" or "NGWMN" #' @return list #' @noRd #' @examplesIf is_dataRetrieval_user() @@ -97,12 +109,20 @@ get_ogc_params <- function(service){ #' \donttest{ #' dataRetrieval:::get_properties_for_docs("monitoring-locations", #' "monitoring_location_id") +#' +#' dataRetrieval:::get_properties_for_docs("waterLevelObs", +#' base = "NGWMN") #' #' } #' -get_properties_for_docs <- function(service, output_id = NA){ +get_properties_for_docs <- function(service, + output_id = NA, + base = "OGC"){ + + schema <- check_OGC_requests(endpoint = service, + type = "schema", + base = base) - schema <- check_OGC_requests(endpoint = service, type = "schema") properties <- names(schema$properties) if(!is.na(output_id)){ properties[properties == "id"] <- output_id @@ -116,6 +136,7 @@ get_properties_for_docs <- function(service, output_id = NA){ #' #' @param endpoint Character, can be any existing collection #' @param type Character, can be "queryables", "schema" +#' @param base Character, can be "OGC" or "NGWMN" #' @export #' @keywords internal #' @return list @@ -131,16 +152,24 @@ get_properties_for_docs <- function(service, output_id = NA){ #' type = "queryables") #' ts_meta_schema <- check_OGC_requests(endpoint = "time-series-metadata", #' type = "schema") +#' +#' ngwml <- check_OGC_requests(endpoint = "waterLevelObs", +#' type = "schema", +#' base = "NGWMN") #' } check_OGC_requests <- function(endpoint = "daily", - type = "queryables"){ + type = "queryables", + base = "OGC"){ match.arg(type, c("queryables", "schema")) + match.arg(base, c("OGC", "NGWMN")) - match.arg(endpoint, c(pkg.env$api_endpoints, - pkg.env$metadata)) + if(base == "OGC"){ + match.arg(endpoint, c(pkg.env$api_endpoints, + pkg.env$metadata)) + } - req <- base_url() |> + req <- base_url(base) |> httr2::req_url_path_append("collections") |> httr2::req_url_path_append(endpoint) |> httr2::req_url_path_append(type) |> diff --git a/R/readNGWMNdata.R b/R/readNGWMNdata.R deleted file mode 100644 index bc8704bfb..000000000 --- a/R/readNGWMNdata.R +++ /dev/null @@ -1,255 +0,0 @@ -#' Import data from the National Groundwater Monitoring Network. -#' -#' Only water level data and site locations and names are currently available through the web service. -#' @param service char Service for the request - "observation" and "featureOfInterest" are implemented. -#' @param \dots Other parameters to supply, namely `siteNumbers` or `bbox` -#' @param asDateTime logical if `TRUE`, will convert times to POSIXct format. Currently defaults to -#' `FALSE` since time zone information is not included. -#' @param tz character to set timezone attribute of dateTime. Default is "UTC", and converts the -#' date times to UTC, properly accounting for daylight savings times based on the data's provided time zone offset. -#' Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", -#' "America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", -#' "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also `OlsonNames()` -#' for more information on time zones. -#' @export -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # one site -#' site <- "USGS.430427089284901" -#' #oneSite <- readNGWMNdata(siteNumbers = site, service = "observation") -#' -#' # multiple sites -#' sites <- c("USGS.272838082142201", "USGS.404159100494601", "USGS.401216080362703") -#' # Very slow: -#' # multiSiteData <- readNGWMNdata(siteNumbers = sites, service = "observation") -#' # attributes(multiSiteData) -#' -#' # non-USGS site -#' # accepts colon or period between agency and ID -#' site <- "MBMG:702934" -#' # data <- readNGWMNdata(siteNumbers = site, service = "featureOfInterest") -#' -#' # bounding box -#' # bboxSites <- readNGWMNdata(service = "featureOfInterest", bbox = c(30, -102, 31, 99)) -#' # retrieve sites. Set asDateTime to false since one site has an invalid date -#' # Very slow: -#' # bboxData <- readNGWMNdata(service = "observation", siteNumbers = bboxSites$site[1:3], -#' # asDateTime = FALSE) -#' } -#' -readNGWMNdata <- function(service, ..., asDateTime = TRUE, tz = "UTC") { - message("DISCLAIMER: NGWMN retrieval functions are still in flux, - and no future behavior or output is guaranteed") - - dots <- convertLists(...) - - match.arg(service, c("observation", "featureOfInterest")) - - if (service == "observation") { - allObs <- data.frame() - allAttrs <- data.frame() - - # these attributes are pulled out and saved when doing binds to be reattached - attrs <- c("url", "gml:identifier", "generationDate", "responsibleParty", "contact") - featureID <- stats::na.omit(gsub(":", ".", dots[["siteNumbers"]])) - - for (f in featureID) { - obsFID <- retrieveObservation(featureID = f, asDateTime, attrs, tz = tz) - obsFIDattr <- saveAttrs(attrs, obsFID) - obsFID <- removeAttrs(attrs, obsFID) - allObs <- r_bind_dr(allObs, obsFID) - allAttrs <- r_bind_dr(allAttrs, obsFIDattr) - } - - allSites <- tryCatch( - { - retrieveFeatureOfInterest(featureID = featureID) - }, - error = function(cond) { - return(NULL) - } - ) - - if (!is.null(allSites)) { - attr(allObs, "siteInfo") <- allSites - } - - attr(allObs, "other") <- allAttrs - returnData <- allObs - } else if (service == "featureOfInterest") { - if ("siteNumbers" %in% names(dots)) { - featureID <- stats::na.omit(gsub(":", ".", dots[["siteNumbers"]])) - allSites <- tryCatch({ - retrieveFeatureOfInterest(featureID = featureID) - }) - } - - if ("bbox" %in% names(dots)) { - allSites <- tryCatch({ - retrieveFeatureOfInterest(bbox = dots[["bbox"]]) - }) - } - returnData <- allSites - } - - return(returnData) -} - -#' Retrieve groundwater levels from the National Ground Water Monitoring Network. -#' -#' @param siteNumbers character Vector of feature IDs formatted with agency code and site number -#' separated by a period or semicolon, e.g. `USGS.404159100494601`. -#' @param asDateTime logical Should dates and times be converted to date/time objects, -#' or returned as character? Defaults to `TRUE`. Must be set to `FALSE` if a site -#' contains non-standard dates. -#' @param tz character to set timezone attribute of dateTime. Default is "UTC", and converts the -#' date times to UTC, properly accounting for daylight savings times based on the data's provided time zone offset. -#' Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", -#' "America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", -#' "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also `OlsonNames()` -#' for more information on time zones. -#' @export -#' -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # one site -#' site <- "USGS.430427089284901" -#' # oneSite <- readNGWMNlevels(siteNumbers = site) -#' -#' # multiple sites -#' sites <- c("USGS:272838082142201", "USGS:404159100494601", "USGS:401216080362703") -#' # multiSiteData <- readNGWMNlevels(sites) -#' -#' # non-USGS site -#' site <- "MBMG.103306" -#' # data <- readNGWMNlevels(siteNumbers = site, asDateTime = FALSE) -#' -#' # site with no data returns empty data frame -#' noDataSite <- "UTGS.401544112060301" -#' # noDataSite <- readNGWMNlevels(siteNumbers = noDataSite) -#' } -readNGWMNlevels <- function(siteNumbers, asDateTime = TRUE, tz = "UTC") { - data <- readNGWMNdata( - siteNumbers = siteNumbers, service = "observation", - asDateTime = asDateTime, tz = tz - ) - return(data) -} - -#' Retrieve site data from the National Ground Water Monitoring Network. -#' -#' @param siteNumbers character Vector of feature IDs formatted with agency code and site number -#' separated by a period or semicolon, e.g. `USGS.404159100494601`. -#' -#' @export -#' @return A data frame the following columns: -#' #' \tabular{lll}{ -#' Name \tab Type \tab Description \cr -#' site \tab char \tab Site FID \cr -#' description \tab char \tab Site description \cr -#' dec_lat_va, dec_lon_va \tab numeric \tab Site latitude and longitude \cr -#' } -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # one site -#' site <- "USGS.430427089284901" -#' #oneSite <- readNGWMNsites(siteNumbers = site) -#' -#' # non-USGS site -#' site <- "MBMG.103306" -#' #siteInfo <- readNGWMNsites(siteNumbers = site) -#' } -readNGWMNsites <- function(siteNumbers) { - sites <- readNGWMNdata(siteNumbers = siteNumbers, service = "featureOfInterest") - return(sites) -} - -retrieveObservation <- function(featureID, asDateTime, attrs, tz) { - - baseURL <- httr2::request(pkg.env[["NGWMN"]]) - baseURL <- httr2::req_url_query(baseURL, - request = "GetObservation", - service = "SOS", - version = "2.0.0", - observedProperty = "urn:ogc:def:property:OGC:GroundWaterLevel", - responseFormat = "text/xml", - featureOfInterest = paste("VW_GWDP_GEOSERVER", featureID, sep = ".")) - - - returnData <- importNGWMN(baseURL, asDateTime = asDateTime, tz = tz) - if (nrow(returnData) == 0) { - # need to add NA attributes, so they aren't messed up when stored as DFs - attr(returnData, "gml:identifier") <- NA - attr(returnData, "generationDate") <- NA - } - - # mutate removes the attributes, need to save and append - attribs <- saveAttrs(attrs, returnData) - if (nrow(returnData) > 0) { - # tack on site number - siteNum <- rep(sub(".*\\.", "", featureID), nrow(returnData)) - returnData$site <- siteNum - numCol <- ncol(returnData) - returnData <- returnData[, c(numCol, 1:(numCol - 1))] # move siteNum to the left - } - attributes(returnData) <- c(attributes(returnData), as.list(attribs)) - - return(returnData) -} - -# retrieve feature of interest -# could allow pass through srsName - needs to be worked in higher-up in dots -retrieveFeatureOfInterest <- function(..., asDateTime, srsName = "urn:ogc:def:crs:EPSG::4269") { - values <- convertLists(...) - - baseURL <- httr2::request(pkg.env[["NGWMN"]]) - baseURL <- httr2::req_url_query(baseURL, - request = "GetFeatureOfInterest", - service = "SOS", - version = "2.0.0", - responseFormat = "text/xml") - - if ("featureID" %in% names(values)) { - - features <- paste("VW_GWDP_GEOSERVER", - values[["featureID"]], - sep = ".") - - baseURL <- httr2::req_url_query(baseURL, - featureOfInterest = features, - .multi = "comma") - - } else if ("bbox" %in% names(values)) { - baseURL <- httr2::req_url_query(baseURL, - bbox = paste(values[["bbox"]], collapse = ","), - srsName = srsName - ) - } else { - stop("Geographical filter not specified. Please use siteNumbers or bbox") - } - - siteDF <- importNGWMN(baseURL, asDateTime, tz = "") - attr(siteDF, "url") <- baseURL$url - attr(siteDF, "queryTime") <- Sys.time() - return(siteDF) -} - - -# save specified attributes from a data frame -saveAttrs <- function(attrs, df) { - attribs <- sapply(attrs, function(x) attr(df, x)) - if (is.vector(attribs)) { - toReturn <- as.data.frame(t(attribs), stringsAsFactors = FALSE) - } else { # don't need to transpose - toReturn <- as.data.frame(attribs, stringsAsFactors = FALSE) - } - return(toReturn) -} - -# strip specified attributes from a data frame -removeAttrs <- function(attrs, df) { - for (a in attrs) { - attr(df, a) <- NULL - } - return(df) -} diff --git a/R/read_ngwmn_lithology.R b/R/read_ngwmn_lithology.R new file mode 100644 index 000000000..71f0678a7 --- /dev/null +++ b/R/read_ngwmn_lithology.R @@ -0,0 +1,63 @@ +#' Get NGWMN Lithology Observations +#' +#' @description `r get_description("lithologyObs", base = "NGWMN")` +#' +#' @export +#' @param monitoring_location_id +#' `r get_ogc_params("lithologyObs", base = "NGWMN")$monitoring_location_id$description` +#' @param monitoring_location_obs_number +#' `r get_ogc_params("lithologyObs", base = "NGWMN")$monitoring_location_obs_number$description` +#' @param properties A vector of requested columns to be returned from the query. +#' Available options are: +#' `r dataRetrieval:::get_properties_for_docs("lithologyObs", base = "NGWMN")`. +#' The default (`NA`) will return all columns of the data. + +#' @param limit The optional limit parameter is used to control the subset of the +#' selected features that should be returned in each page. The maximum allowable +#' limit is 50000. It may be beneficial to set this number lower if your internet +#' connection is spotty. The default (`NA`) will set the limit to the maximum +#' @param no_paging logical, defaults to `FALSE`. If `TRUE`, the data will +#' be requested from a native csv format. This can be dangerous because the +#' data will cut off at 50,000 rows without indication that more data +#' is available. Use `TRUE` with caution. +#' +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' site <- "AKDNR-535134236016630" +#' ngwmn_lith <- read_ngwmn_lithology(monitoring_location_id = site) +#' +#' ngwmn_lith_sub <- read_ngwmn_lithology(monitoring_location_id = site, +#' monitoring_location_obs_number = 2) +#' +#' sites <- c("ISWS-P428197", "ISWS-P428197", +#' "AKDNR-535143966816631", "AKDNR-535134236016630") +#' ngwml_lith_sites <- read_ngwmn_lithology(monitoring_location_id = sites) +#' +#' } +read_ngwmn_lithology <- function(monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + properties = NA_character_, + limit = NA, + no_paging = FALSE){ + + service <- "lithologyObs" + + args <- mget(names(formals())) + + return_list <- get_ngwmn_data(args, service) + + return_list <- deal_with_empty(return_list, + properties, + service, + skipGeometry = TRUE, + convertType = TRUE, + no_paging = no_paging, + base = "NGWMN") + + + return_list <- sf::st_drop_geometry(return_list) + + return(return_list) +} diff --git a/R/read_ngwmn_providers.R b/R/read_ngwmn_providers.R new file mode 100644 index 000000000..27fb16e81 --- /dev/null +++ b/R/read_ngwmn_providers.R @@ -0,0 +1,57 @@ +#' Get NGWMN Provider Data +#' +#' @description `r get_description("providers", base = "NGWMN")` +#' +#' @export +#' @param state +#' `r get_ogc_params("providers", base = "NGWMN")$state$description` +#' @param agency_code +#' `r get_ogc_params("providers", base = "NGWMN")$agency_code$description` +#' @param organization_type +#' `r get_ogc_params("providers", base = "NGWMN")$organization_type$description` +#' @param properties A vector of requested columns to be returned from the query. +#' Available options are: +#' `r dataRetrieval:::get_properties_for_docs("providers", base = "NGWMN")`. +#' The default (`NA`) will return all columns of the data. + +#' @param limit The optional limit parameter is used to control the subset of the +#' selected features that should be returned in each page. The maximum allowable +#' limit is 50000. It may be beneficial to set this number lower if your internet +#' connection is spotty. The default (`NA`) will set the limit to the maximum +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' +#' ngwmn_providers <- read_ngwmn_providers(state = "WI") +#' +#' ngwml_providers2 <- read_ngwmn_providers(state = c("WI", "MN")) +#' +#' org_type <- read_ngwmn_providers(organization_type = "NWIS") +#' +#' } +read_ngwmn_providers <- function(state = NA_character_, + agency_code = NA_character_, + organization_type = NA_character_, + properties = NA_character_, + limit = NA){ + + service <- "providers" + + args <- mget(names(formals())) + + return_list <- get_ngwmn_data(args, service) + + return_list <- deal_with_empty(return_list, + properties, + service, + skipGeometry = TRUE, + convertType = TRUE, + no_paging = FALSE, + base = "NGWMN") + + + return_list <- sf::st_drop_geometry(return_list) + + return(return_list) +} diff --git a/R/read_ngwmn_sites.R b/R/read_ngwmn_sites.R new file mode 100644 index 000000000..8fa0f48e9 --- /dev/null +++ b/R/read_ngwmn_sites.R @@ -0,0 +1,136 @@ +#' Get NGWMN Site Data +#' +#' @description `r get_description("sites", base = "NGWMN")` +#' +#' @export +#' @param monitoring_location_id +#' `r get_ogc_params("sites", base = "NGWMN")$monitoring_location_id$description` +#' @param agency_code +#' `r get_ogc_params("sites", base = "NGWMN")$agency_code$description` +#' @param monitoring_location_number +#' `r get_ogc_params("sites", base = "NGWMN")$monitoring_location_number$description` +#' @param altitude +#' `r get_ogc_params("sites", base = "NGWMN")$altitude$description` +#' @param national_aquifer_code +#' `r get_ogc_params("sites", base = "NGWMN")$national_aquifer_code$description` +#' @param national_aquifer_description +#' `r get_ogc_params("sites", base = "NGWMN")$national_aquifer_description$description` +#' @param country_code +#' `r get_ogc_params("sites", base = "NGWMN")$country_code$description` +#' @param country_name +#' `r get_ogc_params("sites", base = "NGWMN")$country_name$description` +#' @param state_name +#' `r get_ogc_params("sites", base = "NGWMN")$state_name$description` +#' @param county_name +#' `r get_ogc_params("sites", base = "NGWMN")$county_name$description` +#' @param aquifer_name +#' `r get_ogc_params("sites", base = "NGWMN")$aquifer_name$description` +#' @param site_type +#' `r get_ogc_params("sites", base = "NGWMN")$site_type$description` +#' @param aquifer_type_code +#' `r get_ogc_params("sites", base = "NGWMN")$aquifer_type_code$description` +#' @param qw_sys_name +#' `r get_ogc_params("sites", base = "NGWMN")$qw_sys_name$description` +#' @param qw_sn_flag +#' `r get_ogc_params("sites", base = "NGWMN")$qw_sn_flag$description` +#' @param qw_baseline_flag +#' `r get_ogc_params("sites", base = "NGWMN")$qw_baseline_flag$description` +#' @param qw_well_chars +#' `r get_ogc_params("sites", base = "NGWMN")$qw_well_chars$description` +#' @param qw_well_type +#' `r get_ogc_params("sites", base = "NGWMN")$qw_well_type$description` +#' @param qw_well_purpose +#' `r get_ogc_params("sites", base = "NGWMN")$qw_well_purpose$description` +#' @param wl_sys_name +#' `r get_ogc_params("sites", base = "NGWMN")$wl_sys_name$description` +#' @param wl_sn_flag +#' `r get_ogc_params("sites", base = "NGWMN")$wl_sn_flag$description` +#' @param wl_baseline_flag +#' `r get_ogc_params("sites", base = "NGWMN")$wl_baseline_flag$description` +#' @param wl_well_chars +#' `r get_ogc_params("sites", base = "NGWMN")$wl_well_chars$description` +#' @param wl_well_type +#' `r get_ogc_params("sites", base = "NGWMN")$wl_well_type$description` +#' @param wl_well_purpose +#' `r get_ogc_params("sites", base = "NGWMN")$wl_well_purpose$description` +#' +#' @param properties A vector of requested columns to be returned from the query. +#' Available options are: +#' `r dataRetrieval:::get_properties_for_docs("sites", base = "NGWMN")`. +#' The default (`NA`) will return all columns of the data. +#' @param skipGeometry This option can be used to skip response geometries for +#' each feature. The returning object will be a data frame with no spatial +#' information. +#' @param limit The optional limit parameter is used to control the subset of the +#' selected features that should be returned in each page. The maximum allowable +#' limit is 50000. It may be beneficial to set this number lower if your internet +#' connection is spotty. The default (`NA`) will set the limit to the maximum +#' @param bbox Only features that have a geometry that intersects the bounding +#' box are selected.The bounding box is provided as four or six numbers, depending +#' on whether the coordinate reference system includes a vertical axis (height or +#' depth). Coordinates are assumed to be in crs 4326. The expected format is a numeric +#' vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, +#' Southern-most latitude, Eastern-most longitude, Northern-most longitude). +#' @param no_paging logical, defaults to `FALSE`. If `TRUE`, the data will +#' be requested from a native csv format. This can be dangerous because the +#' data will cut off at 50,000 rows without indication that more data +#' is available. Use `TRUE` with caution. +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' +#' ngwmn_sites <- read_ngwmn_sites(state_name = "Wisconsin") +#' +#' ngwml_providers2 <- read_ngwmn_sites(state = c("WI", "MN")) +#' +#' org_type <- read_ngwmn_sites(organization_type = "NWIS") +#' +#' } +read_ngwmn_sites <- function(monitoring_location_id = NA_character_, + agency_code = NA_character_, + monitoring_location_number = NA_character_, + altitude = NA_character_, + national_aquifer_code = NA_character_, + national_aquifer_description = NA_character_, + country_code = NA_character_, + country_name = NA_character_, + state_name = NA_character_, + county_name = NA_character_, + aquifer_name = NA_character_, + site_type = NA_character_, + aquifer_type_code = NA_character_, + qw_sys_name = NA_character_, + qw_sn_flag = NA_character_, + qw_baseline_flag = NA_character_, + qw_well_chars = NA_character_, + qw_well_type = NA_character_, + qw_well_purpose = NA_character_, + wl_sys_name = NA_character_, + wl_sn_flag = NA_character_, + wl_baseline_flag = NA_character_, + wl_well_chars = NA_character_, + wl_well_type = NA_character_, + wl_well_purpose = NA_character_, + bbox = NA, + properties = NA_character_, + skipGeometry = FALSE, + limit = NA, + no_paging = FALSE){ + + service <- "sites" + + args <- mget(names(formals())) + + return_list <- get_ngwmn_data(args, service) + + return_list <- deal_with_empty(return_list, + properties, + service, + skipGeometry = skipGeometry, + convertType = TRUE, + no_paging = no_paging, + base = "NGWMN") + + return(return_list) +} diff --git a/R/read_ngwmn_water_level.R b/R/read_ngwmn_water_level.R new file mode 100644 index 000000000..d0c46ac11 --- /dev/null +++ b/R/read_ngwmn_water_level.R @@ -0,0 +1,96 @@ +#' Get NGWMN Water Level Data +#' +#' @description `r dataRetrieval:::get_description("waterLevelObs", base = "NGWMN")` +#' +#' @export +#' @param monitoring_location_id +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$monitoring_location_id$description` +#' @param monitoring_location_obs_number +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$monitoring_location_obs_number$description` +#' @param sample_time +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$sample_time$description` +#' See also Details below for more information. +#' +#' @param data_provided_by +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$data_provided_by$description` +#' @param water_depth_below_land_surface_ft +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$water_depth_below_land_surface_ft$description` +#' @param water_level_above_site_datum_ft +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$water_level_above_site_datum_ft$description` +#' @param monitoring_location_vertical_datum +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$monitoring_location_vertical_datum$description` +#' @param water_level_above_navd88_ft +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$water_level_above_navd88_ft$description` +#' +#' @param datetime +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$sample_time$descriptiond` +#' Multiple time_series_ids can be requested as a character vector. +#' @param properties A vector of requested columns to be returned from the query. +#' Available options are: +#' `r dataRetrieval:::get_properties_for_docs("waterLevelObs", base = "NGWMN")`. +#' The default (`NA`) will return all columns of the data. + +#' @param limit The optional limit parameter is used to control the subset of the +#' selected features that should be returned in each page. The maximum allowable +#' limit is 50000. It may be beneficial to set this number lower if your internet +#' connection is spotty. The default (`NA`) will set the limit to the maximum +#' @param no_paging logical, defaults to `FALSE`. If `TRUE`, the data will +#' be requested from a native csv format. This can be dangerous because the +#' data will cut off at 50,000 rows without indication that more data +#' is available. Use `TRUE` with caution. +#' +#' @inherit read_waterdata_continuous details +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' site <- "USGS-272838082142201" +#' ngwmn_wl <- read_ngwmn_water_level(monitoring_location_id = site) +#' +#' ngwmn_wl_sub <- read_ngwmn_water_level(monitoring_location_id = site, +#' monitoring_location_obs_number = 1:10) +#' +#' ngwml_wl_time2 <- read_ngwmn_water_level(monitoring_location_id = site, +#' datetime = c("2022-01-01", "2024-01-01")) +#' +#' sites <- c("USGS-272838082142201", "USGS-404159100494601", +#' "USGS-401216080362703", "MBMG-702934") +#' ngwml_wl_sites <- read_ngwmn_water_level(monitoring_location_id = sites) +#' +#' } +read_ngwmn_water_level <- function(monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + sample_time = NA_character_, + data_provided_by = NA_character_, + water_depth_below_land_surface_ft = NA_character_, + water_level_above_site_datum_ft = NA_character_, + monitoring_location_vertical_datum = NA_character_, + water_level_above_navd88_ft = NA_character_, + properties = NA_character_, + datetime = NA_character_, + limit = NA, + no_paging = FALSE){ + + service <- "waterLevelObs" + + args <- mget(names(formals())) + + return_list <- get_ngwmn_data(args = args, + service = service) + + return_list <- deal_with_empty(return_list, + properties, + service, + skipGeometry = TRUE, + convertType = TRUE, + no_paging = no_paging, + base = "NGWMN") + + + return_list <- sf::st_drop_geometry(return_list) + + return(return_list) +} + + + diff --git a/R/read_ngwmn_well_construction.R b/R/read_ngwmn_well_construction.R new file mode 100644 index 000000000..4ac9382c2 --- /dev/null +++ b/R/read_ngwmn_well_construction.R @@ -0,0 +1,66 @@ +#' Get NGWMN Well Construction Data +#' +#' @description `r get_description("constructionObs", base = "NGWMN")` +#' +#' @export +#' @param monitoring_location_id +#' `r get_ogc_params("constructionObs", base = "NGWMN")$monitoring_location_id$description` +#' @param monitoring_location_obs_number +#' `r get_ogc_params("constructionObs", base = "NGWMN")$monitoring_location_obs_number$description` +#' @param material +#' `r get_ogc_params("constructionObs", base = "NGWMN")$material$description` +#' @param properties A vector of requested columns to be returned from the query. +#' Available options are: +#' `r dataRetrieval:::get_properties_for_docs("constructionObs", base = "NGWMN")`. +#' The default (`NA`) will return all columns of the data. + +#' @param limit The optional limit parameter is used to control the subset of the +#' selected features that should be returned in each page. The maximum allowable +#' limit is 50000. It may be beneficial to set this number lower if your internet +#' connection is spotty. The default (`NA`) will set the limit to the maximum +#' @param no_paging logical, defaults to `FALSE`. If `TRUE`, the data will +#' be requested from a native csv format. This can be dangerous because the +#' data will cut off at 50,000 rows without indication that more data +#' is available. Use `TRUE` with caution. +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' site <- "USGS-272838082142201" +#' ngwmn_well <- read_ngwmn_well_construction(monitoring_location_id = site) +#' +#' ngwmn_well_sub <- read_ngwmn_well_construction(monitoring_location_id = site, +#' monitoring_location_obs_number = 2) +#' +#' sites <- c("USGS-272838082142201", "USGS-404159100494601", +#' "USGS-401216080362703", "MBMG-702934") +#' ngwml_well_sites <- read_ngwmn_well_construction(monitoring_location_id = sites) +#' +#' } +read_ngwmn_well_construction <- function(monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + material = NA_character_, + properties = NA_character_, + limit = NA, + no_paging = FALSE){ + + service <- "constructionObs" + + args <- mget(names(formals())) + + return_list <- get_ngwmn_data(args, + service) + + return_list <- deal_with_empty(return_list, + properties, + service, + skipGeometry = TRUE, + convertType = TRUE, + no_paging = no_paging, + base = "NGWMN") + + + return_list <- sf::st_drop_geometry(return_list) + + return(return_list) +} diff --git a/R/setAccess.R b/R/setAccess.R index e436feda3..641cc1b06 100644 --- a/R/setAccess.R +++ b/R/setAccess.R @@ -72,6 +72,7 @@ Please contact comptools@usgs.gov for more information.") pkg.env$status <- "https://www.waterqualitydata.us/wqx3/status/" pkg.env$NGWMN <- "https://cida.usgs.gov/ngwmn_cache/sos" + # pkg.env$NGWMN <- "https://www.usgs.gov/apps/ngwmn/ngwmn_cache/sos" # nolint end } diff --git a/R/sysdata.rda b/R/sysdata.rda index d984e226a41f4863d93d639afb1d9cca19b362b4..e5678f1835d9365b677470b86b2ebd9d0cffa065 100644 GIT binary patch delta 873 zcmV-v1D5=l_Y<)96M%#PgaU*Ev;^$*1LFpqx9{`>dINvWc1#-e+s|Bn(&U3Fr4=Q{ zYAX1Yww)7Z-Ze0CkF2sJYP3;bt3P6-AWz(5r`$6fcgt0f%;WnW6Xv?<&{p?SU1EW5ilE`ewJ!`})O^4qs;uZzk z+mxsRScQ$}Z~M#7xGCZvG3Lng#(xQ&#`1mk-?V=QRU|MGM&CXrtdvX87G(CgGeSh| zM7kBYwA^0)1Rd=S%RvfMs-CDUWERG{(;emcyGVs`s1m*8 z&A9lXCA8PzFV$Z6jW>^1tYM6YJX z91u94WDSFfeT8@qTu^ZV%^k$=!Ap8+8JIO>R}ZA#?XT68bnj#y>(F(*zg>e0V5n^o z*Jy9f1In61cf3&VXZpp=bX3M1l&&PaFE2cjB?S<^?vQ^;(dD!LuVTQsn;>^U8vK6) zbA?bV*4{&jc+hJM0)eN1DOSS;#*bgA>rW z=kZJ6=+4baEtN;Q%F_Ht*mx`EfD^G)&0;Z?c#k-;>H!&{0xjZaFXavEpC45f55Ztf5F1XNQ!goyo(N>kA#qY>d>v4hQt}EG+W!IV&-G@)1Q4MVU zws}3ZpgMbMr0hQQ00000v}!@R00D*f6PvK)0{{R3GrTZ@o8wVH0{{R300CKA^pv+2 delta 849 zcmV-X1FrnA_Y;`+6M%#PgaU*Ev;^$*1BM2Nx9{`>dINv28<)V`;ipa+N0&zxdhw!S z{p?~JJj@SWBvwR?SM+}|(r7RK@YbZh(+tIZN0>Be!5NvJQG&cFddnI2=vx?jWi|h{ zvJB22DdKA%FS^UMDvVsaWocG~tXl}k#X{RF6rOw^2M8^BW%PimA*GUS4Wdcn;w{a9 zJO^oKtfqfm?=5=Yz(P|?k*yjI-=XEDJnpSBXAB2rr*z@sxsu~Fh?G@g)l;S(NDwMg z9y;G}uT@{+LiU8?OP3bnQ;(*>Rn;cPFeR=F*Iy)W zKejI(fg>Q9;5);k!hp3)P4A}=FdV2KJ6c*X9Z`Y3h+9frXG}sBE4~tSoDu7&sE*i} z3ow5_E;(=!@dmJ|rZiuoiw7)o@vHwi5&=%c0?0?Y&k~6mx=^cv;uRmap0Y>F32hKH~DMUQnYh@vVRPBG2 zM|y%k-Uj|Zu*xLUV0vHuW1{K&f(+Cj!j7WG3k&I8{D_ueGmHVmBM?2x2Rq2KmXQ}T zoU?lb28Y&nZNNndRGYFSNFL9|1XdB00Hp! b6TYwH0{{R3*+4Gpo8wVH0{{R300CKA<@A(D diff --git a/R/walk_pages.R b/R/walk_pages.R index 9afa9825a..8d99bf56a 100644 --- a/R/walk_pages.R +++ b/R/walk_pages.R @@ -50,6 +50,10 @@ get_resp_data <- function(resp) { FUN.VALUE = c(NA_character_))) } + if("altitude_accuracy" %in% names(return_df)){ + return_df$altitude_accuracy <- as.character(return_df$altitude_accuracy) + } + if(!use_sf){ return_df <- sf::st_drop_geometry(return_df) if("AsGeoJSON(geometry)" %in% names(return_df)){ diff --git a/_pkgdown.yml b/_pkgdown.yml index f9d8bafcd..6a46ff57d 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -117,9 +117,11 @@ reference: - title: National Ground-Water Monitoring Network desc: Functions to retrieve NGWMN data. contents: - - readNGWMNlevels - - readNGWMNsites - - readNGWMNdata + - read_ngwmn_water_levels + - read_ngwmn_sites + - read_ngwmn_providers + - read_ngwmn_well_construction + - read_ngwmn_lithology - title: Network Linked Data Index desc: Functions to interface with the NLDI. contents: diff --git a/man/check_OGC_requests.Rd b/man/check_OGC_requests.Rd index 1d7297967..53d7d2f17 100644 --- a/man/check_OGC_requests.Rd +++ b/man/check_OGC_requests.Rd @@ -4,12 +4,14 @@ \alias{check_OGC_requests} \title{Check OGC requests} \usage{ -check_OGC_requests(endpoint = "daily", type = "queryables") +check_OGC_requests(endpoint = "daily", type = "queryables", base = "OGC") } \arguments{ \item{endpoint}{Character, can be any existing collection} \item{type}{Character, can be "queryables", "schema"} + +\item{base}{Character, can be "OGC" or "NGWMN"} } \value{ list @@ -30,6 +32,10 @@ ts_meta_queryables <- check_OGC_requests(endpoint = "time-series-metadata", type = "queryables") ts_meta_schema <- check_OGC_requests(endpoint = "time-series-metadata", type = "schema") + +ngwml <- check_OGC_requests(endpoint = "waterLevelObs", + type = "schema", + base = "NGWMN") } \dontshow{\}) # examplesIf} } diff --git a/man/construct_ngwmn_requests.Rd b/man/construct_ngwmn_requests.Rd new file mode 100644 index 000000000..100bc7b59 --- /dev/null +++ b/man/construct_ngwmn_requests.Rd @@ -0,0 +1,58 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/get_ngwmn_data.R +\name{construct_ngwmn_requests} +\alias{construct_ngwmn_requests} +\title{Create NGWMN API url} +\usage{ +construct_ngwmn_requests( + service, + properties = NA_character_, + bbox = NA, + skipGeometry = FALSE, + no_paging = FALSE, + ... +) +} +\arguments{ +\item{service}{Which service available on \url{https://api.waterdata.usgs.gov/ogcapi/v0/}.} + +\item{properties}{The properties that should be included for each feature. The +parameter value is a comma-separated list of property names which depend on the +service being called.} + +\item{bbox}{Only features that have a geometry that intersects the bounding +box are selected.The bounding box is provided as four or six numbers, depending +on whether the coordinate reference system includes a vertical axis (height or +depth).} + +\item{skipGeometry}{This option can be used to skip response geometries for +each feature. The returning object will be a data frame with no spatial +information.} + +\item{...}{Extra parameters from the specific services.} +} +\description{ +Main documentation: \url{https://ngwmn-qa.wma.chs.usgs.gov/apps/ngwmn/ogcapi/}, +Swagger docs: \url{https://ngwmn-qa.wma.chs.usgs.gov/apps/ngwmn/ogcapi/openapi}. +} +\examples{ +site <- "USGS-02238500" +pcode <- "00060" +req_dv <- construct_api_requests("daily", + monitoring_location_id = site, + parameter_code = "00060") + +req_dv <- construct_api_requests("daily", + monitoring_location_id = site, + parameter_code = c("00060", "00065")) + +sites <- c("USGS-01491000", "USGS-01645000") +start_date <- "2018-01-01" +end_date <- "2022-01-01" +req_dv <- construct_ngwmn_requests("daily", + monitoring_location_id = sites, + parameter_code = c("00060", "00065"), + datetime = c(start_date, end_date)) + +} +\keyword{internal} diff --git a/man/get_ogc_params.Rd b/man/get_ogc_params.Rd index 9a8ab0d08..d71616671 100644 --- a/man/get_ogc_params.Rd +++ b/man/get_ogc_params.Rd @@ -4,10 +4,12 @@ \alias{get_ogc_params} \title{Get parameter descriptions} \usage{ -get_ogc_params(service) +get_ogc_params(service, base = "OGC") } \arguments{ \item{service}{Character, can be any of the USGS Waterdata API endpoints or collections.} + +\item{base}{Either "OGC" for waterdata, or "NGWMN".} } \value{ list diff --git a/man/readNGWMNdata.Rd b/man/readNGWMNdata.Rd deleted file mode 100644 index c2dd649b1..000000000 --- a/man/readNGWMNdata.Rd +++ /dev/null @@ -1,53 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/readNGWMNdata.R -\name{readNGWMNdata} -\alias{readNGWMNdata} -\title{Import data from the National Groundwater Monitoring Network.} -\usage{ -readNGWMNdata(service, ..., asDateTime = TRUE, tz = "UTC") -} -\arguments{ -\item{service}{char Service for the request - "observation" and "featureOfInterest" are implemented.} - -\item{\dots}{Other parameters to supply, namely \code{siteNumbers} or \code{bbox}} - -\item{asDateTime}{logical if \code{TRUE}, will convert times to POSIXct format. Currently defaults to -\code{FALSE} since time zone information is not included.} - -\item{tz}{character to set timezone attribute of dateTime. Default is "UTC", and converts the -date times to UTC, properly accounting for daylight savings times based on the data's provided time zone offset. -Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", -"America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", -"America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also \code{OlsonNames()} -for more information on time zones.} -} -\description{ -Only water level data and site locations and names are currently available through the web service. -} -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# one site -site <- "USGS.430427089284901" -#oneSite <- readNGWMNdata(siteNumbers = site, service = "observation") - -# multiple sites -sites <- c("USGS.272838082142201", "USGS.404159100494601", "USGS.401216080362703") -# Very slow: -# multiSiteData <- readNGWMNdata(siteNumbers = sites, service = "observation") -# attributes(multiSiteData) - -# non-USGS site -# accepts colon or period between agency and ID -site <- "MBMG:702934" -# data <- readNGWMNdata(siteNumbers = site, service = "featureOfInterest") - -# bounding box -# bboxSites <- readNGWMNdata(service = "featureOfInterest", bbox = c(30, -102, 31, 99)) -# retrieve sites. Set asDateTime to false since one site has an invalid date -# Very slow: -# bboxData <- readNGWMNdata(service = "observation", siteNumbers = bboxSites$site[1:3], -# asDateTime = FALSE) -} -\dontshow{\}) # examplesIf} -} diff --git a/man/readNGWMNlevels.Rd b/man/readNGWMNlevels.Rd deleted file mode 100644 index c53e3787d..000000000 --- a/man/readNGWMNlevels.Rd +++ /dev/null @@ -1,47 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/readNGWMNdata.R -\name{readNGWMNlevels} -\alias{readNGWMNlevels} -\title{Retrieve groundwater levels from the National Ground Water Monitoring Network.} -\usage{ -readNGWMNlevels(siteNumbers, asDateTime = TRUE, tz = "UTC") -} -\arguments{ -\item{siteNumbers}{character Vector of feature IDs formatted with agency code and site number -separated by a period or semicolon, e.g. \code{USGS.404159100494601}.} - -\item{asDateTime}{logical Should dates and times be converted to date/time objects, -or returned as character? Defaults to \code{TRUE}. Must be set to \code{FALSE} if a site -contains non-standard dates.} - -\item{tz}{character to set timezone attribute of dateTime. Default is "UTC", and converts the -date times to UTC, properly accounting for daylight savings times based on the data's provided time zone offset. -Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", -"America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", -"America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also \code{OlsonNames()} -for more information on time zones.} -} -\description{ -Retrieve groundwater levels from the National Ground Water Monitoring Network. -} -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# one site -site <- "USGS.430427089284901" -# oneSite <- readNGWMNlevels(siteNumbers = site) - -# multiple sites -sites <- c("USGS:272838082142201", "USGS:404159100494601", "USGS:401216080362703") -# multiSiteData <- readNGWMNlevels(sites) - -# non-USGS site -site <- "MBMG.103306" -# data <- readNGWMNlevels(siteNumbers = site, asDateTime = FALSE) - -# site with no data returns empty data frame -noDataSite <- "UTGS.401544112060301" -# noDataSite <- readNGWMNlevels(siteNumbers = noDataSite) -} -\dontshow{\}) # examplesIf} -} diff --git a/man/readNGWMNsites.Rd b/man/readNGWMNsites.Rd deleted file mode 100644 index 0aa0232bd..000000000 --- a/man/readNGWMNsites.Rd +++ /dev/null @@ -1,37 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/readNGWMNdata.R -\name{readNGWMNsites} -\alias{readNGWMNsites} -\title{Retrieve site data from the National Ground Water Monitoring Network.} -\usage{ -readNGWMNsites(siteNumbers) -} -\arguments{ -\item{siteNumbers}{character Vector of feature IDs formatted with agency code and site number -separated by a period or semicolon, e.g. \code{USGS.404159100494601}.} -} -\value{ -A data frame the following columns: -#' \tabular{lll}{ -Name \tab Type \tab Description \cr -site \tab char \tab Site FID \cr -description \tab char \tab Site description \cr -dec_lat_va, dec_lon_va \tab numeric \tab Site latitude and longitude \cr -} -} -\description{ -Retrieve site data from the National Ground Water Monitoring Network. -} -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# one site -site <- "USGS.430427089284901" -#oneSite <- readNGWMNsites(siteNumbers = site) - -# non-USGS site -site <- "MBMG.103306" -#siteInfo <- readNGWMNsites(siteNumbers = site) -} -\dontshow{\}) # examplesIf} -} diff --git a/man/read_ngwmn_lithology.Rd b/man/read_ngwmn_lithology.Rd new file mode 100644 index 000000000..fb4e264de --- /dev/null +++ b/man/read_ngwmn_lithology.Rd @@ -0,0 +1,54 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn_lithology.R +\name{read_ngwmn_lithology} +\alias{read_ngwmn_lithology} +\title{Get NGWMN Lithology Observations} +\usage{ +read_ngwmn_lithology( + monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + properties = NA_character_, + limit = NA, + no_paging = FALSE +) +} +\arguments{ +\item{monitoring_location_id}{This field is required. Combined site identifier of agency code and site number (format of \code{{agency_code}}-\code{{monitoring_location_number}}). A list of values can be passed for this field, seperated by commas.} + +\item{monitoring_location_obs_number}{Number of observation for given site. A list of values can be passed for this field, seperated by commas.} + +\item{properties}{A vector of requested columns to be returned from the query. +Available options are: +agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, lithology_id, lithology_description, lithology_controlled_concept, lithology_depth_from, lithology_depth_to, lithology_depth_to_unit, lithology_depth_from_unit. +The default (\code{NA}) will return all columns of the data.} + +\item{limit}{The optional limit parameter is used to control the subset of the +selected features that should be returned in each page. The maximum allowable +limit is 50000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum} + +\item{no_paging}{logical, defaults to \code{FALSE}. If \code{TRUE}, the data will +be requested from a native csv format. This can be dangerous because the +data will cut off at 50,000 rows without indication that more data +is available. Use \code{TRUE} with caution.} +} +\description{ +Lithology Observations data +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +site <- "AKDNR-535134236016630" +ngwmn_lith <- read_ngwmn_lithology(monitoring_location_id = site) + +ngwmn_lith_sub <- read_ngwmn_lithology(monitoring_location_id = site, + monitoring_location_obs_number = 2) + +sites <- c("ISWS-P428197", "ISWS-P428197", + "AKDNR-535143966816631", "AKDNR-535134236016630") +ngwml_lith_sites <- read_ngwmn_lithology(monitoring_location_id = sites) + +} +\dontshow{\}) # examplesIf} +} diff --git a/man/read_ngwmn_providers.Rd b/man/read_ngwmn_providers.Rd new file mode 100644 index 000000000..3788f6ef7 --- /dev/null +++ b/man/read_ngwmn_providers.Rd @@ -0,0 +1,48 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn_providers.R +\name{read_ngwmn_providers} +\alias{read_ngwmn_providers} +\title{Get NGWMN Provider Data} +\usage{ +read_ngwmn_providers( + state = NA_character_, + agency_code = NA_character_, + organization_type = NA_character_, + properties = NA_character_, + limit = NA +) +} +\arguments{ +\item{state}{State code for provider. A list of values can be passed for this field, seperated by commas.} + +\item{agency_code}{Code for the name of the agency or organization that owns the site and/or contributed it to the network. A list of values can be passed for this field, seperated by commas.} + +\item{organization_type}{Type of organization of data provider.} + +\item{properties}{A vector of requested columns to be returned from the query. +Available options are: +agency_name, agency_code, organization_type, state, link. +The default (\code{NA}) will return all columns of the data.} + +\item{limit}{The optional limit parameter is used to control the subset of the +selected features that should be returned in each page. The maximum allowable +limit is 50000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum} +} +\description{ +NGWMN contributing providers +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ + +ngwmn_providers <- read_ngwmn_providers(state = "WI") + +ngwml_providers2 <- read_ngwmn_providers(state = c("WI", "MN")) + +org_type <- read_ngwmn_providers(organization_type = "NWIS") + +} +\dontshow{\}) # examplesIf} +} diff --git a/man/read_ngwmn_sites.Rd b/man/read_ngwmn_sites.Rd new file mode 100644 index 000000000..7e22c3080 --- /dev/null +++ b/man/read_ngwmn_sites.Rd @@ -0,0 +1,133 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn_sites.R +\name{read_ngwmn_sites} +\alias{read_ngwmn_sites} +\title{Get NGWMN Site Data} +\usage{ +read_ngwmn_sites( + monitoring_location_id = NA_character_, + agency_code = NA_character_, + monitoring_location_number = NA_character_, + altitude = NA_character_, + national_aquifer_code = NA_character_, + national_aquifer_description = NA_character_, + country_code = NA_character_, + country_name = NA_character_, + state_name = NA_character_, + county_name = NA_character_, + aquifer_name = NA_character_, + site_type = NA_character_, + aquifer_type_code = NA_character_, + qw_sys_name = NA_character_, + qw_sn_flag = NA_character_, + qw_baseline_flag = NA_character_, + qw_well_chars = NA_character_, + qw_well_type = NA_character_, + qw_well_purpose = NA_character_, + wl_sys_name = NA_character_, + wl_sn_flag = NA_character_, + wl_baseline_flag = NA_character_, + wl_well_chars = NA_character_, + wl_well_type = NA_character_, + wl_well_purpose = NA_character_, + bbox = NA, + properties = NA_character_, + skipGeometry = FALSE, + limit = NA, + no_paging = FALSE +) +} +\arguments{ +\item{monitoring_location_id}{Site identifier, combination of agency code and site number (format \code{agency_code}- \code{monitoring_location_number}). A list of values can be passed for this field, seperated by commas.} + +\item{agency_code}{Code for the name of the agency or organization that owns the site and/or contributed it to the network. A list of values can be passed for this field, seperated by commas.} + +\item{monitoring_location_number}{Local, unique well or spring identification number or code. A list of values can be passed for this field, seperated by commas.} + +\item{altitude}{Elevation of the land surface at the site.} + +\item{national_aquifer_code}{Code for U.S. Pricinpal Aquifer, lookup \href{https://www.usgs.gov/mission-areas/water-resources/science/national-aquifer-code-reference-list}{here}. A list of values can be passed for this field, seperated by commas.} + +\item{national_aquifer_description}{Name for U.S. Principal Aquifer, lookup \href{https://www.usgs.gov/mission-areas/water-resources/science/national-aquifer-code-reference-list}{here}. A list of values can be passed for this field, seperated by commas.} + +\item{country_code}{Abbreviation of country of site location. A list of values can be passed for this field, seperated by commas.} + +\item{country_name}{Name of country of site location.} + +\item{state_name}{Name of state of site location. A list of values can be passed for this field, seperated by commas.} + +\item{county_name}{Name of county of site location. A list of values can be passed for this field, seperated by commas.} + +\item{aquifer_name}{Name of local aquifer of site. A list of values can be passed for this field, seperated by commas.} + +\item{site_type}{Type of groundwater site (Spring or Well).} + +\item{aquifer_type_code}{Characteristic of the type of aquifer that the well is completed in (Confined or Unconfined). For NGWMN, shallow semi-confined wells can be considered unconfined if they respond to climatic fluctuations in a relatively short period of time.} + +\item{qw_sys_name}{The system from which water quality data from the well or spring is served to the portal. A list of values can be passed for this field, seperated by commas.} + +\item{qw_sn_flag}{Flag for whether the well or spring is part of the NGWMN water-quality network.} + +\item{qw_baseline_flag}{Flag for whether the well or spring has completed its 5-year baseline period, classifies it as being in one of the three QW subnetworks.} + +\item{qw_well_chars}{The characteristics of the aquifer the well represents. There are 3 options: 'Background', 'Suspected / Anticipated Changes', 'Known Changes'. The field is NULL if the site is still in the baseline period.} + +\item{qw_well_type}{Description of the assigned QW monitoring category for the well or spring.} + +\item{qw_well_purpose}{Description of the prupose of conducting QW monitoring of the well or spring.} + +\item{wl_sys_name}{The system from which water level data from the well or spring is served to the portal. A list of values can be passed for this field, seperated by commas.} + +\item{wl_sn_flag}{Flag for whether the well or spring is part of the NGWMN water-level network.} + +\item{wl_baseline_flag}{Flag for whether the well or spring has completed its 5-year baseline period, classifies it as being in one of the three WL subnetworks.} + +\item{wl_well_chars}{The characteristics of the aquifer the well represents. There are 3 options: 'Background', 'Suspected / Anticipated Changes', 'Known Changes'. The field is NULL if the site is still in the baseline period.} + +\item{wl_well_type}{Description of the assigned WL monitoring category for the well or spring} + +\item{wl_well_purpose}{Description of the purpose of conducting WL monitoring of the well or spring.} + +\item{bbox}{Only features that have a geometry that intersects the bounding +box are selected.The bounding box is provided as four or six numbers, depending +on whether the coordinate reference system includes a vertical axis (height or +depth). Coordinates are assumed to be in crs 4326. The expected format is a numeric +vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, +Southern-most latitude, Eastern-most longitude, Northern-most longitude).} + +\item{properties}{A vector of requested columns to be returned from the query. +Available options are: +geometry, monitoring_location_id, agency_code, agency_name, monitoring_location_number, monitoring_location_name, longitude, original_horizontal_datum, horizontal_position_accuracy_code, altitude, vertical_datum, altitude_method_name, altitude_accuracy, well_constructed_depth, well_depth_units, national_aquifer_code, national_aquifer_description, country_code, country_name, state_name, county_name, aquifer_name, site_type, aquifer_type_code, qw_sys_name, qw_sn_flag, qw_baseline_flag, qw_well_chars, qw_well_type, qw_well_purpose, qw_well_purpose_notes, wl_sys_name, wl_sn_flag, wl_baseline_flag, wl_well_chars, wl_well_type, wl_well_purpose, wl_well_purpose_notes, link. +The default (\code{NA}) will return all columns of the data.} + +\item{skipGeometry}{This option can be used to skip response geometries for +each feature. The returning object will be a data frame with no spatial +information.} + +\item{limit}{The optional limit parameter is used to control the subset of the +selected features that should be returned in each page. The maximum allowable +limit is 50000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum} + +\item{no_paging}{logical, defaults to \code{FALSE}. If \code{TRUE}, the data will +be requested from a native csv format. This can be dangerous because the +data will cut off at 50,000 rows without indication that more data +is available. Use \code{TRUE} with caution.} +} +\description{ +Site data (from Monitoring Location Registry), including the name, identifier, agency, features, and location of the site +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ + +ngwmn_sites <- read_ngwmn_sites(state_name = "Wisconsin") + +ngwml_providers2 <- read_ngwmn_sites(state = c("WI", "MN")) + +org_type <- read_ngwmn_sites(organization_type = "NWIS") + +} +\dontshow{\}) # examplesIf} +} diff --git a/man/read_ngwmn_water_level.Rd b/man/read_ngwmn_water_level.Rd new file mode 100644 index 000000000..8732873ba --- /dev/null +++ b/man/read_ngwmn_water_level.Rd @@ -0,0 +1,104 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn_water_level.R +\name{read_ngwmn_water_level} +\alias{read_ngwmn_water_level} +\title{Get NGWMN Water Level Data} +\usage{ +read_ngwmn_water_level( + monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + sample_time = NA_character_, + data_provided_by = NA_character_, + water_depth_below_land_surface_ft = NA_character_, + water_level_above_site_datum_ft = NA_character_, + monitoring_location_vertical_datum = NA_character_, + water_level_above_navd88_ft = NA_character_, + properties = NA_character_, + datetime = NA_character_, + limit = NA, + no_paging = FALSE +) +} +\arguments{ +\item{monitoring_location_id}{This field is required. Combined site identifier of agency code and site number (format of \code{{agency_code}}-\code{{monitoring_location_number}}). A list of values can be passed for this field, seperated by commas.} + +\item{monitoring_location_obs_number}{Number of observation for given site. A list of values can be passed for this field, seperated by commas.} + +\item{sample_time}{The date of an observation. Date and time expressions adhere to RFC 3339. Intervals may be bounded or half-bounded (double-dots at start or end). +Examples: +\itemize{ +\item A date-time: "2018-02-12T23:20:50-00:00" +\item A bounded interval:"2018-02-12T00:00:00+05:00/2018-03-18T12:31:12+05:00" +\item Half-bounded intervals: "2018-02-12T00:00:00-05:00/.." or "../2018-03-18T12:31:12-05:00" +} + +Only features that have a \code{sample_time} that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties. + +See also Details below for more information.} + +\item{data_provided_by}{Code for the agency or organization that provides, collects, owns, and/or manages the water level measurement record.} + +\item{water_depth_below_land_surface_ft}{Calculated depth to water in feet.} + +\item{water_level_above_site_datum_ft}{Water-level value represented as depth to site datum in feet.} + +\item{monitoring_location_vertical_datum}{Code indicating the vertical datum.} + +\item{water_level_above_navd88_ft}{Mediated water-level value represented as depth to water relative to the NAVD88 datum.} + +\item{properties}{A vector of requested columns to be returned from the query. +Available options are: +agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, sample_time, orig_unit, orig_value, accuracy_unit, accuracy_value, obs_datum_cd, obs_comment, obs_method, data_provided_by, water_depth_below_land_surface_ft, water_level_above_site_datum_ft, monitoring_location_vertical_datum, water_level_above_navd88_ft. +The default (\code{NA}) will return all columns of the data.} + +\item{datetime}{Multiple time_series_ids can be requested as a character vector.} + +\item{limit}{The optional limit parameter is used to control the subset of the +selected features that should be returned in each page. The maximum allowable +limit is 50000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum} + +\item{no_paging}{logical, defaults to \code{FALSE}. If \code{TRUE}, the data will +be requested from a native csv format. This can be dangerous because the +data will cut off at 50,000 rows without indication that more data +is available. Use \code{TRUE} with caution.} +} +\description{ +Water Level Observations data +} +\details{ +You can also use a vector of length 2 for any time queries (such as time +or last_modified). The first value is the starting date (or datetime), +the second value is the ending date(or datetime). +NA's within the vector indicate a half-bound date. +For example, \code{time = c("2024-01-01", NA)} will return all data starting +at 2024-01-01. +\code{time = c(NA, "2024-01-01")} will return all data from the beginning of +the timeseries until 2024-01-01. +By default, time is assumed UTC, although time zone attributes +will be accommodated. As an example, setting \code{time = as.POSIXct(c("2021-01-01 12:00:00", +"2021-01-01 14:00"), tz = "America/New_York")} will request data that between +noon and 2pm eastern time on 2021-01-01. +All time values RETURNED from the service are UTC with the exception of +daily data, which returns time values in local dates. +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +site <- "USGS-272838082142201" +ngwmn_wl <- read_ngwmn_water_level(monitoring_location_id = site) + +ngwmn_wl_sub <- read_ngwmn_water_level(monitoring_location_id = site, + monitoring_location_obs_number = 1:10) + +ngwml_wl_time2 <- read_ngwmn_water_level(monitoring_location_id = site, + datetime = c("2022-01-01", "2024-01-01")) + +sites <- c("USGS-272838082142201", "USGS-404159100494601", + "USGS-401216080362703", "MBMG-702934") +ngwml_wl_sites <- read_ngwmn_water_level(monitoring_location_id = sites) + +} +\dontshow{\}) # examplesIf} +} diff --git a/man/read_ngwmn_well_construction.Rd b/man/read_ngwmn_well_construction.Rd new file mode 100644 index 000000000..834678e09 --- /dev/null +++ b/man/read_ngwmn_well_construction.Rd @@ -0,0 +1,57 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn_well_construction.R +\name{read_ngwmn_well_construction} +\alias{read_ngwmn_well_construction} +\title{Get NGWMN Well Construction Data} +\usage{ +read_ngwmn_well_construction( + monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + material = NA_character_, + properties = NA_character_, + limit = NA, + no_paging = FALSE +) +} +\arguments{ +\item{monitoring_location_id}{This field is required. Combined site identifier of agency code and site number (format of \code{{agency_code}}-\code{{monitoring_location_number}}). A list of values can be passed for this field, seperated by commas.} + +\item{monitoring_location_obs_number}{Number of observation for given site. A list of values can be passed for this field, seperated by commas.} + +\item{material}{Screen type or material.} + +\item{properties}{A vector of requested columns to be returned from the query. +Available options are: +agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, type, depth_from, depth_to, depth_from_unit, depth_to_unit, material, diameter, diameter_unit, hole_size, hole_size_unit. +The default (\code{NA}) will return all columns of the data.} + +\item{limit}{The optional limit parameter is used to control the subset of the +selected features that should be returned in each page. The maximum allowable +limit is 50000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum} + +\item{no_paging}{logical, defaults to \code{FALSE}. If \code{TRUE}, the data will +be requested from a native csv format. This can be dangerous because the +data will cut off at 50,000 rows without indication that more data +is available. Use \code{TRUE} with caution.} +} +\description{ +Well Construction Observations data +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +site <- "USGS-272838082142201" +ngwmn_well <- read_ngwmn_well_construction(monitoring_location_id = site) + +ngwmn_well_sub <- read_ngwmn_well_construction(monitoring_location_id = site, + monitoring_location_obs_number = 2) + +sites <- c("USGS-272838082142201", "USGS-404159100494601", + "USGS-401216080362703", "MBMG-702934") +ngwml_well_sites <- read_ngwmn_well_construction(monitoring_location_id = sites) + +} +\dontshow{\}) # examplesIf} +} diff --git a/vignettes/tutorial.Rmd b/vignettes/tutorial.Rmd index e674d68b4..712782160 100644 --- a/vignettes/tutorial.Rmd +++ b/vignettes/tutorial.Rmd @@ -444,9 +444,11 @@ There are two services that also have functions in `dataRetrieval`, the National Similar to WQP, the NGWMN brings groundwater data from multiple sources into a single location. There are currently a few `dataRetrieval` functions included: -* `readNGWMNsites()` -* `readNGWMNlevels()` -* `readNGWMNdata()`. +* `read_ngwmn_sites` +* `read_ngwmn_water_levels` +* `read_ngwmn_providers` +* `read_ngwmn_well_construction` +* `read_ngwmn_lithology` ## Network Linked Data Index (NLDI) From 98a441d3b372a5695f1dfb0c0d3607085c4a777a Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Mon, 9 Mar 2026 08:49:50 -0500 Subject: [PATCH 04/71] gah --- NAMESPACE | 1 - man/construct_ngwmn_requests.Rd | 58 --------------------------------- 2 files changed, 59 deletions(-) delete mode 100644 man/construct_ngwmn_requests.Rd diff --git a/NAMESPACE b/NAMESPACE index 061ba096e..aac81c3a0 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -8,7 +8,6 @@ export(check_waterdata_sample_params) export(constructNWISURL) export(constructWQPURL) export(construct_api_requests) -export(construct_ngwmn_requests) export(construct_waterdata_sample_request) export(countyCd) export(countyCdLookup) diff --git a/man/construct_ngwmn_requests.Rd b/man/construct_ngwmn_requests.Rd deleted file mode 100644 index 100bc7b59..000000000 --- a/man/construct_ngwmn_requests.Rd +++ /dev/null @@ -1,58 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/get_ngwmn_data.R -\name{construct_ngwmn_requests} -\alias{construct_ngwmn_requests} -\title{Create NGWMN API url} -\usage{ -construct_ngwmn_requests( - service, - properties = NA_character_, - bbox = NA, - skipGeometry = FALSE, - no_paging = FALSE, - ... -) -} -\arguments{ -\item{service}{Which service available on \url{https://api.waterdata.usgs.gov/ogcapi/v0/}.} - -\item{properties}{The properties that should be included for each feature. The -parameter value is a comma-separated list of property names which depend on the -service being called.} - -\item{bbox}{Only features that have a geometry that intersects the bounding -box are selected.The bounding box is provided as four or six numbers, depending -on whether the coordinate reference system includes a vertical axis (height or -depth).} - -\item{skipGeometry}{This option can be used to skip response geometries for -each feature. The returning object will be a data frame with no spatial -information.} - -\item{...}{Extra parameters from the specific services.} -} -\description{ -Main documentation: \url{https://ngwmn-qa.wma.chs.usgs.gov/apps/ngwmn/ogcapi/}, -Swagger docs: \url{https://ngwmn-qa.wma.chs.usgs.gov/apps/ngwmn/ogcapi/openapi}. -} -\examples{ -site <- "USGS-02238500" -pcode <- "00060" -req_dv <- construct_api_requests("daily", - monitoring_location_id = site, - parameter_code = "00060") - -req_dv <- construct_api_requests("daily", - monitoring_location_id = site, - parameter_code = c("00060", "00065")) - -sites <- c("USGS-01491000", "USGS-01645000") -start_date <- "2018-01-01" -end_date <- "2022-01-01" -req_dv <- construct_ngwmn_requests("daily", - monitoring_location_id = sites, - parameter_code = c("00060", "00065"), - datetime = c(start_date, end_date)) - -} -\keyword{internal} From 3379d6134f1478a9e5acce7bc906c4255520f5fd Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Mon, 9 Mar 2026 08:55:11 -0500 Subject: [PATCH 05/71] get all functions ready --- NAMESPACE | 1 + R/get_ngwmn_data.R | 192 ++++++++++++++++++++++++++++++++ man/construct_ngwmn_requests.Rd | 58 ++++++++++ 3 files changed, 251 insertions(+) create mode 100644 R/get_ngwmn_data.R create mode 100644 man/construct_ngwmn_requests.Rd diff --git a/NAMESPACE b/NAMESPACE index aac81c3a0..061ba096e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -8,6 +8,7 @@ export(check_waterdata_sample_params) export(constructNWISURL) export(constructWQPURL) export(construct_api_requests) +export(construct_ngwmn_requests) export(construct_waterdata_sample_request) export(countyCd) export(countyCdLookup) diff --git a/R/get_ngwmn_data.R b/R/get_ngwmn_data.R new file mode 100644 index 000000000..d4c9ce54a --- /dev/null +++ b/R/get_ngwmn_data.R @@ -0,0 +1,192 @@ +#' Coordinate the request and retrieval of NGWMN calls +#' +#' @param args arguments from individual functions +#' @param service Endpoint name. +#' +#' @noRd +#' @return data.frame with attributes +get_ngwmn_data <- function(args, + service){ + + args <- check_limits(args) + + properties <- args[["properties"]] + + args[["service"]] <- service + + req <- do.call(construct_ngwmn_requests, args) + + no_paging <- grepl("f=csv", req$url) + + message("Requesting:\n", req$url) + + if(no_paging){ + return_list <- get_csv(req, limit = args[["limit"]]) + } else { + return_list <- walk_pages(req) + } + + if(!("skipGeometry" %in% names(args)) || + is.na(args[["skipGeometry"]])){ + skipGeometry <- FALSE + } else { + skipGeometry <- args[["skipGeometry"]] + } + + return_list <- order_results(return_list) + + if(getOption("dataRetrieval.attach_request")){ + attr(return_list, "request") <- req + } + + attr(return_list, "queryTime") <- Sys.time() + return(return_list) +} + + +#' Create NGWMN API url +#' +#' Main documentation: , +#' Swagger docs: . +#' +#' @export +#' @param service Which service available on . +#' @param ... Extra parameters from the specific services. +#' @param bbox Only features that have a geometry that intersects the bounding +#' box are selected.The bounding box is provided as four or six numbers, depending +#' on whether the coordinate reference system includes a vertical axis (height or +#' depth). +#' @param properties The properties that should be included for each feature. The +#' parameter value is a comma-separated list of property names which depend on the +#' service being called. +#' @param skipGeometry This option can be used to skip response geometries for +#' each feature. The returning object will be a data frame with no spatial +#' information. +#' @keywords internal +#' @examples +#' site <- "USGS-02238500" +#' pcode <- "00060" +#' req_dv <- construct_api_requests("daily", +#' monitoring_location_id = site, +#' parameter_code = "00060") +#' +#' req_dv <- construct_api_requests("daily", +#' monitoring_location_id = site, +#' parameter_code = c("00060", "00065")) +#' +#' sites <- c("USGS-01491000", "USGS-01645000") +#' start_date <- "2018-01-01" +#' end_date <- "2022-01-01" +#' req_dv <- construct_ngwmn_requests("daily", +#' monitoring_location_id = sites, +#' parameter_code = c("00060", "00065"), +#' datetime = c(start_date, end_date)) +#' +construct_ngwmn_requests <- function(service, + properties = NA_character_, + bbox = NA, + skipGeometry = FALSE, + no_paging = FALSE, + ...){ + + POST <- FALSE + + single_params <- c("datetime", "last_modified", "datetime", "sample_time", + "begin", "end", "time", "limit") + + comma_params <- c("monitoring_location_id", + "monitoring_location_obs_number", + "properties") + + full_list <- list(...) + + if(all(is.na(full_list)) & all(is.na(bbox))){ + warning("No filtering arguments specified.") + } + # Figure out if the GET request will be > 2048 characters + # and remove NA's from the comma parameters + comma_params_filtered <- Filter(Negate(anyNA), lapply(full_list[comma_params], function(x) x[!is.na(x)])) + comma_params_filtered <- comma_params_filtered[!sapply(comma_params_filtered,is.null)] + + single_params_filtered <- Filter(Negate(anyNA), full_list[single_params]) + single_params_filtered <- single_params_filtered[!sapply(single_params_filtered,is.null)] + + force_post <- nchar(paste0(unlist(comma_params_filtered), collapse = ",")) > 2048 + + if(force_post){ + get_list <- single_params_filtered + } else { + # GET list refers to arguments that will go in the URL no matter what (not POST) + get_list <- c(single_params_filtered, comma_params_filtered) + } + + if(skipGeometry){ + get_list[["skipGeometry"]] <- skipGeometry + } + + get_list <- get_list[!is.na(get_list)] + + time_periods <- c("last_modified", "datetime", "time", "begin", "end", "sample_time") + if(any(time_periods %in% names(get_list))){ + + for(i in time_periods[time_periods %in% names(get_list)]){ + dates <- FALSE + if (all(service == "daily" & i != "last_modified")){ + dates <- TRUE + } + get_list[[i]] <- format_api_dates(get_list[[i]], date = dates) + full_list[[i]] <- format_api_dates(full_list[[i]], date = dates) + } + } + + format_type <- ifelse(isTRUE(no_paging), "csv", "json") + + baseURL <- setup_api(service, format = format_type, base = "NGWMN") + baseURL <- explode_query(baseURL, POST = FALSE, get_list, multi = "comma") + + if(all(!is.na(bbox))){ + baseURL <- httr2::req_url_query(baseURL, + bbox = as.numeric(bbox), + .multi = "comma") + } + + if(!all(is.na(properties))){ + + baseURL <- httr2::req_url_query(baseURL, + properties = properties, + .multi = "comma") + } + + #POST list are the arguments that need to be in the POST body + post_list <- full_list[!names(full_list) %in% names(get_list)] + + post_params <- explode_post(post_list) + + # Should we do a POST? + POST = length(post_params) > 0 + + if(POST){ + baseURL <- baseURL |> + httr2::req_headers(`Content-Type` = "application/query-cql-json") + + if(length(post_params) > 1){ + post_params <- list( + "params" = unname(post_params) + ) + + template_path_post <- system.file("templates/post.CQL2", package = "dataRetrieval") + template_post <- readChar(template_path_post, file.info(template_path_post)$size) + + x <- whisker::whisker.render(template_post, post_params) + } else { + x <- post_params[[1]] + } + + baseURL <- httr2::req_body_raw(baseURL, x) + + } else { + baseURL <- explode_query(baseURL, POST = FALSE, full_list, multi = "comma") + } + + return(baseURL) +} diff --git a/man/construct_ngwmn_requests.Rd b/man/construct_ngwmn_requests.Rd new file mode 100644 index 000000000..100bc7b59 --- /dev/null +++ b/man/construct_ngwmn_requests.Rd @@ -0,0 +1,58 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/get_ngwmn_data.R +\name{construct_ngwmn_requests} +\alias{construct_ngwmn_requests} +\title{Create NGWMN API url} +\usage{ +construct_ngwmn_requests( + service, + properties = NA_character_, + bbox = NA, + skipGeometry = FALSE, + no_paging = FALSE, + ... +) +} +\arguments{ +\item{service}{Which service available on \url{https://api.waterdata.usgs.gov/ogcapi/v0/}.} + +\item{properties}{The properties that should be included for each feature. The +parameter value is a comma-separated list of property names which depend on the +service being called.} + +\item{bbox}{Only features that have a geometry that intersects the bounding +box are selected.The bounding box is provided as four or six numbers, depending +on whether the coordinate reference system includes a vertical axis (height or +depth).} + +\item{skipGeometry}{This option can be used to skip response geometries for +each feature. The returning object will be a data frame with no spatial +information.} + +\item{...}{Extra parameters from the specific services.} +} +\description{ +Main documentation: \url{https://ngwmn-qa.wma.chs.usgs.gov/apps/ngwmn/ogcapi/}, +Swagger docs: \url{https://ngwmn-qa.wma.chs.usgs.gov/apps/ngwmn/ogcapi/openapi}. +} +\examples{ +site <- "USGS-02238500" +pcode <- "00060" +req_dv <- construct_api_requests("daily", + monitoring_location_id = site, + parameter_code = "00060") + +req_dv <- construct_api_requests("daily", + monitoring_location_id = site, + parameter_code = c("00060", "00065")) + +sites <- c("USGS-01491000", "USGS-01645000") +start_date <- "2018-01-01" +end_date <- "2022-01-01" +req_dv <- construct_ngwmn_requests("daily", + monitoring_location_id = sites, + parameter_code = c("00060", "00065"), + datetime = c(start_date, end_date)) + +} +\keyword{internal} From c2947bac63ef5ac6e7e75f1f9092f2efbf2867e6 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 2 Jun 2026 14:11:47 -0500 Subject: [PATCH 06/71] some updates from API --- R/get_ogc_data.R | 14 +++++++------- R/importNGWMN_wml2.R | 7 +++++++ R/readNGWMNdata.R | 5 +++-- R/read_ngwmn_lithology.R | 20 +++++++------------- R/read_ngwmn_providers.R | 30 ++++++++++++++---------------- R/read_ngwmn_sites.R | 29 +++++++++++++++-------------- R/read_ngwmn_water_level.R | 11 +---------- 7 files changed, 54 insertions(+), 62 deletions(-) diff --git a/R/get_ogc_data.R b/R/get_ogc_data.R index 8149557b7..4b01df231 100644 --- a/R/get_ogc_data.R +++ b/R/get_ogc_data.R @@ -54,13 +54,13 @@ get_ogc_data <- function(args, output_id, service, base = "OGC") { return_list <- walk_pages(req) } - return_list <- deal_with_empty( - return_list, - args[["properties"]], - service, - isTRUE(args[["skipGeometry"]]), - args[["convertType"]], - no_paging + return_list <- deal_with_empty(return_list = return_list, + properties = args[["properties"]], + service = service, + skipGeometry = isTRUE(args[["skipGeometry"]]), + convertType = args[["convertType"]], + no_paging = no_paging, + base = base ) return_list <- rejigger_cols(return_list, args[["properties"]], output_id) diff --git a/R/importNGWMN_wml2.R b/R/importNGWMN_wml2.R index f35d4bcae..0b2fcec1f 100644 --- a/R/importNGWMN_wml2.R +++ b/R/importNGWMN_wml2.R @@ -32,6 +32,13 @@ #' } #' importNGWMN <- function(input, asDateTime = FALSE, tz = "UTC") { + + .Deprecated( + new = "read_ngwmn_water_level", + package = "dataRetrieval", + msg = "Updated NGWMN APIs will use read_ngwmn set of functions." + ) + if (tz != "") { tz <- match.arg(tz, OlsonNames()) } else { diff --git a/R/readNGWMNdata.R b/R/readNGWMNdata.R index 0ef719319..51e5d862b 100644 --- a/R/readNGWMNdata.R +++ b/R/readNGWMNdata.R @@ -39,8 +39,9 @@ #' readNGWMNdata <- function(service, ..., asDateTime = TRUE, tz = "UTC") { .Deprecated( - "read_ngwmn_water_level", - msg = "Begin converting to read_ngwmn suite of functions" + new = "read_ngwmn_water_level", + package = "dataRetrieval", + msg = "Updated NGWMN APIs will use read_ngwmn set of functions." ) dots <- convertLists(...) diff --git a/R/read_ngwmn_lithology.R b/R/read_ngwmn_lithology.R index 54142cc5c..93fbbe66a 100644 --- a/R/read_ngwmn_lithology.R +++ b/R/read_ngwmn_lithology.R @@ -11,16 +11,7 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("lithologyObs", base = "NGWMN")`. #' The default (`NA`) will return all columns of the data. - -#' @param limit The optional limit parameter is used to control the subset of the -#' selected features that should be returned in each page. The maximum allowable -#' limit is 50000. It may be beneficial to set this number lower if your internet -#' connection is spotty. The default (`NA`) will set the limit to the maximum -#' @param no_paging logical, defaults to `FALSE`. If `TRUE`, the data will -#' be requested from a native csv format. This can be dangerous because the -#' data will cut off at 50,000 rows without indication that more data -#' is available. Use `TRUE` with caution. -#' +#' @inheritParams check_arguments_non_api #' #' @examplesIf is_dataRetrieval_user() #' @@ -28,8 +19,6 @@ #' site <- "AKDNR-535134236016630" #' ngwmn_lith <- read_ngwmn_lithology(monitoring_location_id = site) #' -#' ngwmn_lith_sub <- read_ngwmn_lithology(monitoring_location_id = site, -#' monitoring_location_obs_number = 2) #' #' sites <- c("ISWS-P428197", "ISWS-P428197", #' "AKDNR-535143966816631", "AKDNR-535134236016630") @@ -51,7 +40,12 @@ read_ngwmn_lithology <- function( rlang::check_dots_empty() args <- mget(names(formals())) - return_list <- get_ngwmn_data(args, service) + return_list <- get_ogc_data( + args = args, + output_id = "id", + service = service, + base = "NGWMN" + ) return(return_list) } diff --git a/R/read_ngwmn_providers.R b/R/read_ngwmn_providers.R index 27fb16e81..9eee8d629 100644 --- a/R/read_ngwmn_providers.R +++ b/R/read_ngwmn_providers.R @@ -13,11 +13,7 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("providers", base = "NGWMN")`. #' The default (`NA`) will return all columns of the data. - -#' @param limit The optional limit parameter is used to control the subset of the -#' selected features that should be returned in each page. The maximum allowable -#' limit is 50000. It may be beneficial to set this number lower if your internet -#' connection is spotty. The default (`NA`) will set the limit to the maximum +#' @inheritParams check_arguments_non_api #' #' @examplesIf is_dataRetrieval_user() #' @@ -34,21 +30,23 @@ read_ngwmn_providers <- function(state = NA_character_, agency_code = NA_character_, organization_type = NA_character_, properties = NA_character_, - limit = NA){ + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request")){ service <- "providers" - + rlang::check_dots_empty() args <- mget(names(formals())) - return_list <- get_ngwmn_data(args, service) - - return_list <- deal_with_empty(return_list, - properties, - service, - skipGeometry = TRUE, - convertType = TRUE, - no_paging = FALSE, - base = "NGWMN") + return_list <- get_ogc_data( + args = args, + output_id = "id", + service = service, + base = "NGWMN" + ) return_list <- sf::st_drop_geometry(return_list) diff --git a/R/read_ngwmn_sites.R b/R/read_ngwmn_sites.R index 383b5a24f..9af3aca8f 100644 --- a/R/read_ngwmn_sites.R +++ b/R/read_ngwmn_sites.R @@ -61,30 +61,22 @@ #' @param skipGeometry This option can be used to skip response geometries for #' each feature. The returning object will be a data frame with no spatial #' information. -#' @param limit The optional limit parameter is used to control the subset of the -#' selected features that should be returned in each page. The maximum allowable -#' limit is 50000. It may be beneficial to set this number lower if your internet -#' connection is spotty. The default (`NA`) will set the limit to the maximum + #' @param bbox Only features that have a geometry that intersects the bounding #' box are selected.The bounding box is provided as four or six numbers, depending #' on whether the coordinate reference system includes a vertical axis (height or #' depth). Coordinates are assumed to be in crs 4326. The expected format is a numeric #' vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, #' Southern-most latitude, Eastern-most longitude, Northern-most longitude). -#' @param no_paging logical, defaults to `FALSE`. If `TRUE`, the data will -#' be requested from a native csv format. This can be dangerous because the -#' data will cut off at 50,000 rows without indication that more data -#' is available. Use `TRUE` with caution. #' +#' @inheritParams check_arguments_non_api #' @examplesIf is_dataRetrieval_user() #' #' \donttest{ #' #' ngwmn_sites <- read_ngwmn_sites(state_name = "Wisconsin") #' -#' ngwml_providers2 <- read_ngwmn_sites(state = c("WI", "MN")) -#' -#' org_type <- read_ngwmn_sites(organization_type = "NWIS") +#' org_type <- read_ngwmn_sites(agency_code = "NWIS", state_name = "Wisconsin") #' #' } read_ngwmn_sites <- function( @@ -116,14 +108,23 @@ read_ngwmn_sites <- function( bbox = NA, properties = NA_character_, skipGeometry = FALSE, - limit = NA, - no_paging = FALSE + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") ) { service <- "sites" rlang::check_dots_empty() args <- mget(names(formals())) - return_list <- get_ngwmn_data(args, service) + return_list <- get_ogc_data( + args = args, + output_id = "id", + service = service, + base = "NGWMN" + ) return(return_list) } diff --git a/R/read_ngwmn_water_level.R b/R/read_ngwmn_water_level.R index b1e76ff8f..9f5af73e9 100644 --- a/R/read_ngwmn_water_level.R +++ b/R/read_ngwmn_water_level.R @@ -29,17 +29,8 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("waterLevelObs", base = "NGWMN")`. #' The default (`NA`) will return all columns of the data. - -#' @param limit The optional limit parameter is used to control the subset of the -#' selected features that should be returned in each page. The maximum allowable -#' limit is 50000. It may be beneficial to set this number lower if your internet -#' connection is spotty. The default (`NA`) will set the limit to the maximum -#' @param no_paging logical, defaults to `FALSE`. If `TRUE`, the data will -#' be requested from a native csv format. This can be dangerous because the -#' data will cut off at 50,000 rows without indication that more data -#' is available. Use `TRUE` with caution. #' -#' @inherit read_waterdata_continuous details +#' @inheritParams check_arguments_non_api #' #' @examplesIf is_dataRetrieval_user() #' From a125abff2858cdd7b99fbcb9719e52343de5a8ad Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 2 Jun 2026 15:28:40 -0500 Subject: [PATCH 07/71] updates from APIs --- DESCRIPTION | 2 +- NAMESPACE | 4 +- man/check_OGC_requests.Rd | 2 +- man/construct_api_requests.Rd | 1 + man/construct_ngwmn_requests.Rd | 58 ---------------------------- man/readNGWMNdata.Rd | 53 +++++++++++++++++++++++++ man/readNGWMNlevels.Rd | 47 ++++++++++++++++++++++ man/read_ngwmn_lithology.Rd | 44 +++++++++++++++------ man/read_ngwmn_providers.Rd | 38 ++++++++++++++++-- man/read_ngwmn_sites.Rd | 45 ++++++++++++++++------ man/read_ngwmn_water_level.Rd | 60 ++++++++++++++++------------- man/read_ngwmn_well_construction.Rd | 42 +++++++++++++++----- 12 files changed, 274 insertions(+), 122 deletions(-) delete mode 100644 man/construct_ngwmn_requests.Rd create mode 100644 man/readNGWMNdata.Rd create mode 100644 man/readNGWMNlevels.Rd diff --git a/DESCRIPTION b/DESCRIPTION index f9ba7fdf4..101d0fc5c 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: dataRetrieval Type: Package Title: Retrieval Functions for USGS and EPA Hydrology and Water Quality Data -Version: 2.7.25 +Version: 2.7.25.9000 Authors@R: c( person("Laura", "DeCicco", role = c("aut","cre"), email = "ldecicco@usgs.gov", diff --git a/NAMESPACE b/NAMESPACE index 4ea0db46e..f6c0aa264 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -8,7 +8,6 @@ export(check_waterdata_sample_params) export(constructNWISURL) export(constructWQPURL) export(construct_api_requests) -export(construct_ngwmn_requests) export(construct_waterdata_sample_request) export(countyCd) export(countyCdLookup) @@ -28,6 +27,9 @@ export(pCodeToName) export(parameterCdFile) export(parse_WQP) export(pcode_to_name) +export(readNGWMNdata) +export(readNGWMNlevels) +export(readNGWMNsites) export(readNWISdata) export(readNWISdv) export(readNWISpCode) diff --git a/man/check_OGC_requests.Rd b/man/check_OGC_requests.Rd index 53d7d2f17..00ad8002e 100644 --- a/man/check_OGC_requests.Rd +++ b/man/check_OGC_requests.Rd @@ -32,7 +32,7 @@ ts_meta_queryables <- check_OGC_requests(endpoint = "time-series-metadata", type = "queryables") ts_meta_schema <- check_OGC_requests(endpoint = "time-series-metadata", type = "schema") - + ngwml <- check_OGC_requests(endpoint = "waterLevelObs", type = "schema", base = "NGWMN") diff --git a/man/construct_api_requests.Rd b/man/construct_api_requests.Rd index cbad05506..98656b981 100644 --- a/man/construct_api_requests.Rd +++ b/man/construct_api_requests.Rd @@ -9,6 +9,7 @@ construct_api_requests( output_id, ..., bbox = NA, + base = "OGC", convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), chunk_size = getOption("dataRetrieval.site_chunk_size_data"), diff --git a/man/construct_ngwmn_requests.Rd b/man/construct_ngwmn_requests.Rd deleted file mode 100644 index 100bc7b59..000000000 --- a/man/construct_ngwmn_requests.Rd +++ /dev/null @@ -1,58 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/get_ngwmn_data.R -\name{construct_ngwmn_requests} -\alias{construct_ngwmn_requests} -\title{Create NGWMN API url} -\usage{ -construct_ngwmn_requests( - service, - properties = NA_character_, - bbox = NA, - skipGeometry = FALSE, - no_paging = FALSE, - ... -) -} -\arguments{ -\item{service}{Which service available on \url{https://api.waterdata.usgs.gov/ogcapi/v0/}.} - -\item{properties}{The properties that should be included for each feature. The -parameter value is a comma-separated list of property names which depend on the -service being called.} - -\item{bbox}{Only features that have a geometry that intersects the bounding -box are selected.The bounding box is provided as four or six numbers, depending -on whether the coordinate reference system includes a vertical axis (height or -depth).} - -\item{skipGeometry}{This option can be used to skip response geometries for -each feature. The returning object will be a data frame with no spatial -information.} - -\item{...}{Extra parameters from the specific services.} -} -\description{ -Main documentation: \url{https://ngwmn-qa.wma.chs.usgs.gov/apps/ngwmn/ogcapi/}, -Swagger docs: \url{https://ngwmn-qa.wma.chs.usgs.gov/apps/ngwmn/ogcapi/openapi}. -} -\examples{ -site <- "USGS-02238500" -pcode <- "00060" -req_dv <- construct_api_requests("daily", - monitoring_location_id = site, - parameter_code = "00060") - -req_dv <- construct_api_requests("daily", - monitoring_location_id = site, - parameter_code = c("00060", "00065")) - -sites <- c("USGS-01491000", "USGS-01645000") -start_date <- "2018-01-01" -end_date <- "2022-01-01" -req_dv <- construct_ngwmn_requests("daily", - monitoring_location_id = sites, - parameter_code = c("00060", "00065"), - datetime = c(start_date, end_date)) - -} -\keyword{internal} diff --git a/man/readNGWMNdata.Rd b/man/readNGWMNdata.Rd new file mode 100644 index 000000000..c2dd649b1 --- /dev/null +++ b/man/readNGWMNdata.Rd @@ -0,0 +1,53 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/readNGWMNdata.R +\name{readNGWMNdata} +\alias{readNGWMNdata} +\title{Import data from the National Groundwater Monitoring Network.} +\usage{ +readNGWMNdata(service, ..., asDateTime = TRUE, tz = "UTC") +} +\arguments{ +\item{service}{char Service for the request - "observation" and "featureOfInterest" are implemented.} + +\item{\dots}{Other parameters to supply, namely \code{siteNumbers} or \code{bbox}} + +\item{asDateTime}{logical if \code{TRUE}, will convert times to POSIXct format. Currently defaults to +\code{FALSE} since time zone information is not included.} + +\item{tz}{character to set timezone attribute of dateTime. Default is "UTC", and converts the +date times to UTC, properly accounting for daylight savings times based on the data's provided time zone offset. +Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", +"America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", +"America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also \code{OlsonNames()} +for more information on time zones.} +} +\description{ +Only water level data and site locations and names are currently available through the web service. +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} +\donttest{ +# one site +site <- "USGS.430427089284901" +#oneSite <- readNGWMNdata(siteNumbers = site, service = "observation") + +# multiple sites +sites <- c("USGS.272838082142201", "USGS.404159100494601", "USGS.401216080362703") +# Very slow: +# multiSiteData <- readNGWMNdata(siteNumbers = sites, service = "observation") +# attributes(multiSiteData) + +# non-USGS site +# accepts colon or period between agency and ID +site <- "MBMG:702934" +# data <- readNGWMNdata(siteNumbers = site, service = "featureOfInterest") + +# bounding box +# bboxSites <- readNGWMNdata(service = "featureOfInterest", bbox = c(30, -102, 31, 99)) +# retrieve sites. Set asDateTime to false since one site has an invalid date +# Very slow: +# bboxData <- readNGWMNdata(service = "observation", siteNumbers = bboxSites$site[1:3], +# asDateTime = FALSE) +} +\dontshow{\}) # examplesIf} +} diff --git a/man/readNGWMNlevels.Rd b/man/readNGWMNlevels.Rd new file mode 100644 index 000000000..c53e3787d --- /dev/null +++ b/man/readNGWMNlevels.Rd @@ -0,0 +1,47 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/readNGWMNdata.R +\name{readNGWMNlevels} +\alias{readNGWMNlevels} +\title{Retrieve groundwater levels from the National Ground Water Monitoring Network.} +\usage{ +readNGWMNlevels(siteNumbers, asDateTime = TRUE, tz = "UTC") +} +\arguments{ +\item{siteNumbers}{character Vector of feature IDs formatted with agency code and site number +separated by a period or semicolon, e.g. \code{USGS.404159100494601}.} + +\item{asDateTime}{logical Should dates and times be converted to date/time objects, +or returned as character? Defaults to \code{TRUE}. Must be set to \code{FALSE} if a site +contains non-standard dates.} + +\item{tz}{character to set timezone attribute of dateTime. Default is "UTC", and converts the +date times to UTC, properly accounting for daylight savings times based on the data's provided time zone offset. +Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", +"America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", +"America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also \code{OlsonNames()} +for more information on time zones.} +} +\description{ +Retrieve groundwater levels from the National Ground Water Monitoring Network. +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} +\donttest{ +# one site +site <- "USGS.430427089284901" +# oneSite <- readNGWMNlevels(siteNumbers = site) + +# multiple sites +sites <- c("USGS:272838082142201", "USGS:404159100494601", "USGS:401216080362703") +# multiSiteData <- readNGWMNlevels(sites) + +# non-USGS site +site <- "MBMG.103306" +# data <- readNGWMNlevels(siteNumbers = site, asDateTime = FALSE) + +# site with no data returns empty data frame +noDataSite <- "UTGS.401544112060301" +# noDataSite <- readNGWMNlevels(siteNumbers = noDataSite) +} +\dontshow{\}) # examplesIf} +} diff --git a/man/read_ngwmn_lithology.Rd b/man/read_ngwmn_lithology.Rd index fb4e264de..695c21f37 100644 --- a/man/read_ngwmn_lithology.Rd +++ b/man/read_ngwmn_lithology.Rd @@ -8,8 +8,12 @@ read_ngwmn_lithology( monitoring_location_id = NA_character_, monitoring_location_obs_number = NA_character_, properties = NA_character_, - limit = NA, - no_paging = FALSE + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") ) } \arguments{ @@ -22,15 +26,35 @@ Available options are: agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, lithology_id, lithology_description, lithology_controlled_concept, lithology_depth_from, lithology_depth_to, lithology_depth_to_unit, lithology_depth_from_unit. The default (\code{NA}) will return all columns of the data.} -\item{limit}{The optional limit parameter is used to control the subset of the -selected features that should be returned in each page. The maximum allowable -limit is 50000. It may be beneficial to set this number lower if your internet -connection is spotty. The default (\code{NA}) will set the limit to the maximum} +\item{...}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} -\item{no_paging}{logical, defaults to \code{FALSE}. If \code{TRUE}, the data will +\item{no_paging}{logical, defaults to FALSE. +If \code{TRUE}, the data will be requested from a native csv format. This can be dangerous because the data will cut off at 50,000 rows without indication that more data is available. Use \code{TRUE} with caution.} + +\item{chunk_size}{Number of monitoring_location_ids to chunk requests into. +The default for functions that don't generally return long-term data records +is 250, while +the default for time series functions is +10. +Setting to \code{NA} will eliminate site chunking, giving users full control.} + +\item{limit}{numeric, The optional limit parameter is used to control the subset of the +selected features that should be returned in each page. The maximum allowable +limit is 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} } \description{ Lithology Observations data @@ -42,13 +66,11 @@ Lithology Observations data site <- "AKDNR-535134236016630" ngwmn_lith <- read_ngwmn_lithology(monitoring_location_id = site) -ngwmn_lith_sub <- read_ngwmn_lithology(monitoring_location_id = site, - monitoring_location_obs_number = 2) - + sites <- c("ISWS-P428197", "ISWS-P428197", "AKDNR-535143966816631", "AKDNR-535134236016630") ngwml_lith_sites <- read_ngwmn_lithology(monitoring_location_id = sites) - + } \dontshow{\}) # examplesIf} } diff --git a/man/read_ngwmn_providers.Rd b/man/read_ngwmn_providers.Rd index 3788f6ef7..4b177bb6e 100644 --- a/man/read_ngwmn_providers.Rd +++ b/man/read_ngwmn_providers.Rd @@ -9,7 +9,12 @@ read_ngwmn_providers( agency_code = NA_character_, organization_type = NA_character_, properties = NA_character_, - limit = NA + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") ) } \arguments{ @@ -24,10 +29,35 @@ Available options are: agency_name, agency_code, organization_type, state, link. The default (\code{NA}) will return all columns of the data.} -\item{limit}{The optional limit parameter is used to control the subset of the +\item{...}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} + +\item{no_paging}{logical, defaults to FALSE. +If \code{TRUE}, the data will +be requested from a native csv format. This can be dangerous because the +data will cut off at 50,000 rows without indication that more data +is available. Use \code{TRUE} with caution.} + +\item{chunk_size}{Number of monitoring_location_ids to chunk requests into. +The default for functions that don't generally return long-term data records +is 250, while +the default for time series functions is +10. +Setting to \code{NA} will eliminate site chunking, giving users full control.} + +\item{limit}{numeric, The optional limit parameter is used to control the subset of the selected features that should be returned in each page. The maximum allowable -limit is 50000. It may be beneficial to set this number lower if your internet -connection is spotty. The default (\code{NA}) will set the limit to the maximum} +limit is 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} } \description{ NGWMN contributing providers diff --git a/man/read_ngwmn_sites.Rd b/man/read_ngwmn_sites.Rd index 7e22c3080..f291585ea 100644 --- a/man/read_ngwmn_sites.Rd +++ b/man/read_ngwmn_sites.Rd @@ -33,8 +33,12 @@ read_ngwmn_sites( bbox = NA, properties = NA_character_, skipGeometry = FALSE, - limit = NA, - no_paging = FALSE + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") ) } \arguments{ @@ -104,15 +108,35 @@ The default (\code{NA}) will return all columns of the data.} each feature. The returning object will be a data frame with no spatial information.} -\item{limit}{The optional limit parameter is used to control the subset of the -selected features that should be returned in each page. The maximum allowable -limit is 50000. It may be beneficial to set this number lower if your internet -connection is spotty. The default (\code{NA}) will set the limit to the maximum} +\item{...}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} -\item{no_paging}{logical, defaults to \code{FALSE}. If \code{TRUE}, the data will +\item{no_paging}{logical, defaults to FALSE. +If \code{TRUE}, the data will be requested from a native csv format. This can be dangerous because the data will cut off at 50,000 rows without indication that more data is available. Use \code{TRUE} with caution.} + +\item{chunk_size}{Number of monitoring_location_ids to chunk requests into. +The default for functions that don't generally return long-term data records +is 250, while +the default for time series functions is +10. +Setting to \code{NA} will eliminate site chunking, giving users full control.} + +\item{limit}{numeric, The optional limit parameter is used to control the subset of the +selected features that should be returned in each page. The maximum allowable +limit is 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} } \description{ Site data (from Monitoring Location Registry), including the name, identifier, agency, features, and location of the site @@ -122,12 +146,11 @@ Site data (from Monitoring Location Registry), including the name, identifier, a \donttest{ -ngwmn_sites <- read_ngwmn_sites(state_name = "Wisconsin") +ngwmn_sites <- read_ngwmn_sites(state_name = "Minnesota") -ngwml_providers2 <- read_ngwmn_sites(state = c("WI", "MN")) +org_type <- read_ngwmn_sites(agency_code = "MN_DNR", + county_name = "Washington County") -org_type <- read_ngwmn_sites(organization_type = "NWIS") - } \dontshow{\}) # examplesIf} } diff --git a/man/read_ngwmn_water_level.Rd b/man/read_ngwmn_water_level.Rd index 8732873ba..ecf3901f6 100644 --- a/man/read_ngwmn_water_level.Rd +++ b/man/read_ngwmn_water_level.Rd @@ -15,8 +15,12 @@ read_ngwmn_water_level( water_level_above_navd88_ft = NA_character_, properties = NA_character_, datetime = NA_character_, - limit = NA, - no_paging = FALSE + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") ) } \arguments{ @@ -53,35 +57,39 @@ The default (\code{NA}) will return all columns of the data.} \item{datetime}{Multiple time_series_ids can be requested as a character vector.} -\item{limit}{The optional limit parameter is used to control the subset of the -selected features that should be returned in each page. The maximum allowable -limit is 50000. It may be beneficial to set this number lower if your internet -connection is spotty. The default (\code{NA}) will set the limit to the maximum} +\item{...}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} -\item{no_paging}{logical, defaults to \code{FALSE}. If \code{TRUE}, the data will +\item{no_paging}{logical, defaults to FALSE. +If \code{TRUE}, the data will be requested from a native csv format. This can be dangerous because the data will cut off at 50,000 rows without indication that more data is available. Use \code{TRUE} with caution.} + +\item{chunk_size}{Number of monitoring_location_ids to chunk requests into. +The default for functions that don't generally return long-term data records +is 250, while +the default for time series functions is +10. +Setting to \code{NA} will eliminate site chunking, giving users full control.} + +\item{limit}{numeric, The optional limit parameter is used to control the subset of the +selected features that should be returned in each page. The maximum allowable +limit is 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} } \description{ Water Level Observations data } -\details{ -You can also use a vector of length 2 for any time queries (such as time -or last_modified). The first value is the starting date (or datetime), -the second value is the ending date(or datetime). -NA's within the vector indicate a half-bound date. -For example, \code{time = c("2024-01-01", NA)} will return all data starting -at 2024-01-01. -\code{time = c(NA, "2024-01-01")} will return all data from the beginning of -the timeseries until 2024-01-01. -By default, time is assumed UTC, although time zone attributes -will be accommodated. As an example, setting \code{time = as.POSIXct(c("2021-01-01 12:00:00", -"2021-01-01 14:00"), tz = "America/New_York")} will request data that between -noon and 2pm eastern time on 2021-01-01. -All time values RETURNED from the service are UTC with the exception of -daily data, which returns time values in local dates. -} \examples{ \dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} @@ -91,14 +99,14 @@ ngwmn_wl <- read_ngwmn_water_level(monitoring_location_id = site) ngwmn_wl_sub <- read_ngwmn_water_level(monitoring_location_id = site, monitoring_location_obs_number = 1:10) - + ngwml_wl_time2 <- read_ngwmn_water_level(monitoring_location_id = site, datetime = c("2022-01-01", "2024-01-01")) - + sites <- c("USGS-272838082142201", "USGS-404159100494601", "USGS-401216080362703", "MBMG-702934") ngwml_wl_sites <- read_ngwmn_water_level(monitoring_location_id = sites) - + } \dontshow{\}) # examplesIf} } diff --git a/man/read_ngwmn_well_construction.Rd b/man/read_ngwmn_well_construction.Rd index 834678e09..352e166ec 100644 --- a/man/read_ngwmn_well_construction.Rd +++ b/man/read_ngwmn_well_construction.Rd @@ -9,8 +9,12 @@ read_ngwmn_well_construction( monitoring_location_obs_number = NA_character_, material = NA_character_, properties = NA_character_, - limit = NA, - no_paging = FALSE + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") ) } \arguments{ @@ -25,15 +29,35 @@ Available options are: agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, type, depth_from, depth_to, depth_from_unit, depth_to_unit, material, diameter, diameter_unit, hole_size, hole_size_unit. The default (\code{NA}) will return all columns of the data.} -\item{limit}{The optional limit parameter is used to control the subset of the -selected features that should be returned in each page. The maximum allowable -limit is 50000. It may be beneficial to set this number lower if your internet -connection is spotty. The default (\code{NA}) will set the limit to the maximum} +\item{...}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} -\item{no_paging}{logical, defaults to \code{FALSE}. If \code{TRUE}, the data will +\item{no_paging}{logical, defaults to FALSE. +If \code{TRUE}, the data will be requested from a native csv format. This can be dangerous because the data will cut off at 50,000 rows without indication that more data is available. Use \code{TRUE} with caution.} + +\item{chunk_size}{Number of monitoring_location_ids to chunk requests into. +The default for functions that don't generally return long-term data records +is 250, while +the default for time series functions is +10. +Setting to \code{NA} will eliminate site chunking, giving users full control.} + +\item{limit}{numeric, The optional limit parameter is used to control the subset of the +selected features that should be returned in each page. The maximum allowable +limit is 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} } \description{ Well Construction Observations data @@ -47,11 +71,11 @@ ngwmn_well <- read_ngwmn_well_construction(monitoring_location_id = site) ngwmn_well_sub <- read_ngwmn_well_construction(monitoring_location_id = site, monitoring_location_obs_number = 2) - + sites <- c("USGS-272838082142201", "USGS-404159100494601", "USGS-401216080362703", "MBMG-702934") ngwml_well_sites <- read_ngwmn_well_construction(monitoring_location_id = sites) - + } \dontshow{\}) # examplesIf} } From 977d87038e4b390fc28582417acbda2bf6f9964a Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 2 Jun 2026 15:34:56 -0500 Subject: [PATCH 08/71] rebuilding docs --- R/readNWISdata.R | 75 ------------------------------ R/read_ngwmn_lithology.R | 5 +- R/read_ngwmn_providers.R | 56 +++++++++++------------ R/read_ngwmn_sites.R | 5 +- R/read_ngwmn_water_level.R | 2 +- R/read_ngwmn_well_construction.R | 27 +++++------ man/readNGWMNsites.Rd | 37 +++++++++++++++ man/readNWISdata.Rd | 78 -------------------------------- 8 files changed, 86 insertions(+), 199 deletions(-) create mode 100644 man/readNGWMNsites.Rd diff --git a/R/readNWISdata.R b/R/readNWISdata.R index 1e12c1df9..b50e03d2f 100644 --- a/R/readNWISdata.R +++ b/R/readNWISdata.R @@ -72,81 +72,6 @@ #' #' @seealso [read_waterdata()] #' @export -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # Examples not run for time considerations -#' -#' instFlow <- readNWISdata( -#' sites = "05114000", service = "iv", -#' parameterCd = "00060", -#' startDate = "2014-05-01T00:00Z", endDate = "2014-05-01T12:00Z" -#' ) -#' -#' instFlowCDT <- readNWISdata( -#' sites = "05114000", service = "iv", -#' parameterCd = "00060", -#' startDate = "2014-05-01T00:00", endDate = "2014-05-01T12:00", -#' tz = "America/Chicago" -#' ) -#' -#' multiSite <- readNWISdata( -#' sites = c("04025500", "040263491"), -#' service = "iv", parameterCd = "00060" -#' ) -#' -#' waterYearStat <- readNWISdata( -#' site = c("01646500"), -#' service = "stat", -#' statReportType = "annual", -#' statYearType = "water", -#' missingData = "on" -#' ) -#' monthlyStat <- readNWISdata( -#' site = c("01646500"), -#' service = "stat", -#' statReportType = "monthly" -#' ) -#' -#' dailyStat <- readNWISdata( -#' site = c("01646500"), -#' service = "stat", -#' statReportType = "daily", -#' statType = c("p25", "p50", "p75", "min", "max"), -#' parameterCd = "00060" -#' ) -#' -#' arg.list <- list( -#' site = "03111548", -#' statReportType = "daily", -#' statType = c("p25", "p50", "p75", "min", "max"), -#' parameterCd = "00060" -#' ) -#' allDailyStats_2 <- readNWISdata(arg.list, service = "stat") -#' -#' -#' site_id <- "01594440" -#' rating_curve <- readNWISdata(service = "rating", site_no = site_id, file_type = "base") -#' all_sites_base <- readNWISdata(service = "rating", file_type = "base") -#' all_sites_core <- readNWISdata(service = "rating", file_type = "corr") -#' all_sites_exsa <- readNWISdata(service = "rating", file_type = "exsa") -#' all_sites_24hrs <- readNWISdata(service = "rating", file_type = "exsa", period = 24) -#' -#' peak_data <- readNWISdata( -#' service = "peak", -#' site_no = c("01594440", "040851325"), -#' range_selection = "data_range" -#' ) -#' -#' peak_data <- readNWISdata( -#' service = "peak", -#' state_cd = "PA" -#' ) -#' -#' peak_data <- readNWISdata( -#' service = "peak", -#' huc2_cd = "20" -#' ) -#' } readNWISdata <- function( ..., asDateTime = TRUE, diff --git a/R/read_ngwmn_lithology.R b/R/read_ngwmn_lithology.R index 93fbbe66a..0cf0cd973 100644 --- a/R/read_ngwmn_lithology.R +++ b/R/read_ngwmn_lithology.R @@ -20,8 +20,9 @@ #' ngwmn_lith <- read_ngwmn_lithology(monitoring_location_id = site) #' #' -#' sites <- c("ISWS-P428197", "ISWS-P428197", -#' "AKDNR-535143966816631", "AKDNR-535134236016630") +#' sites <- c("ISWS-P428197", +#' "AKDNR-535143966816631", +#' "AKDNR-535134236016630") #' ngwml_lith_sites <- read_ngwmn_lithology(monitoring_location_id = sites) #' #' } diff --git a/R/read_ngwmn_providers.R b/R/read_ngwmn_providers.R index 9eee8d629..08e06f9c4 100644 --- a/R/read_ngwmn_providers.R +++ b/R/read_ngwmn_providers.R @@ -1,55 +1,55 @@ #' Get NGWMN Provider Data -#' +#' #' @description `r get_description("providers", base = "NGWMN")` -#' +#' #' @export -#' @param state +#' @param state #' `r get_ogc_params("providers", base = "NGWMN")$state$description` -#' @param agency_code +#' @param agency_code #' `r get_ogc_params("providers", base = "NGWMN")$agency_code$description` -#' @param organization_type +#' @param organization_type #' `r get_ogc_params("providers", base = "NGWMN")$organization_type$description` #' @param properties A vector of requested columns to be returned from the query. -#' Available options are: +#' Available options are: #' `r dataRetrieval:::get_properties_for_docs("providers", base = "NGWMN")`. #' The default (`NA`) will return all columns of the data. #' @inheritParams check_arguments_non_api -#' +#' #' @examplesIf is_dataRetrieval_user() -#' +#' #' \donttest{ -#' +#' #' ngwmn_providers <- read_ngwmn_providers(state = "WI") -#' +#' #' ngwml_providers2 <- read_ngwmn_providers(state = c("WI", "MN")) -#' -#' org_type <- read_ngwmn_providers(organization_type = "NWIS") -#' +#' +#' org_type <- read_ngwmn_providers(organization_type = "NWIS", state = c("WI", "MN")) +#' #' } -read_ngwmn_providers <- function(state = NA_character_, - agency_code = NA_character_, - organization_type = NA_character_, - properties = NA_character_, - ..., - convertType = getOption("dataRetrieval.convertType"), - no_paging = getOption("dataRetrieval.no_paging"), - chunk_size = getOption("dataRetrieval.site_chunk_size_data"), - limit = getOption("dataRetrieval.limit"), - attach_request = getOption("dataRetrieval.attach_request")){ - +read_ngwmn_providers <- function( + state = NA_character_, + agency_code = NA_character_, + organization_type = NA_character_, + properties = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) { service <- "providers" rlang::check_dots_empty() args <- mget(names(formals())) - + return_list <- get_ogc_data( args = args, output_id = "id", service = service, base = "NGWMN" ) - - + return_list <- sf::st_drop_geometry(return_list) - + return(return_list) } diff --git a/R/read_ngwmn_sites.R b/R/read_ngwmn_sites.R index 9af3aca8f..c8eb38573 100644 --- a/R/read_ngwmn_sites.R +++ b/R/read_ngwmn_sites.R @@ -74,9 +74,10 @@ #' #' \donttest{ #' -#' ngwmn_sites <- read_ngwmn_sites(state_name = "Wisconsin") +#' ngwmn_sites <- read_ngwmn_sites(state_name = "Minnesota") #' -#' org_type <- read_ngwmn_sites(agency_code = "NWIS", state_name = "Wisconsin") +#' org_type <- read_ngwmn_sites(agency_code = "MN_DNR", +#' county_name = "Washington County") #' #' } read_ngwmn_sites <- function( diff --git a/R/read_ngwmn_water_level.R b/R/read_ngwmn_water_level.R index 9f5af73e9..4ae9d34d3 100644 --- a/R/read_ngwmn_water_level.R +++ b/R/read_ngwmn_water_level.R @@ -39,7 +39,7 @@ #' ngwmn_wl <- read_ngwmn_water_level(monitoring_location_id = site) #' #' ngwmn_wl_sub <- read_ngwmn_water_level(monitoring_location_id = site, -#' monitoring_location_obs_number = 1:10) +#' monitoring_location_obs_number = 1:5) #' #' ngwml_wl_time2 <- read_ngwmn_water_level(monitoring_location_id = site, #' datetime = c("2022-01-01", "2024-01-01")) diff --git a/R/read_ngwmn_well_construction.R b/R/read_ngwmn_well_construction.R index 7b68b6711..fedf219b3 100644 --- a/R/read_ngwmn_well_construction.R +++ b/R/read_ngwmn_well_construction.R @@ -13,15 +13,7 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("constructionObs", base = "NGWMN")`. #' The default (`NA`) will return all columns of the data. - -#' @param limit The optional limit parameter is used to control the subset of the -#' selected features that should be returned in each page. The maximum allowable -#' limit is 50000. It may be beneficial to set this number lower if your internet -#' connection is spotty. The default (`NA`) will set the limit to the maximum -#' @param no_paging logical, defaults to `FALSE`. If `TRUE`, the data will -#' be requested from a native csv format. This can be dangerous because the -#' data will cut off at 50,000 rows without indication that more data -#' is available. Use `TRUE` with caution. +#' @inheritParams check_arguments_non_api #' #' @examplesIf is_dataRetrieval_user() #' @@ -42,14 +34,23 @@ read_ngwmn_well_construction <- function( monitoring_location_obs_number = NA_character_, material = NA_character_, properties = NA_character_, - limit = NA, - no_paging = FALSE + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") ) { service <- "constructionObs" - + rlang::check_dots_empty() args <- mget(names(formals())) - return_list <- get_ngwmn_data(args, service) + return_list <- get_ogc_data( + args = args, + output_id = "id", + service = service, + base = "NGWMN" + ) return(return_list) } diff --git a/man/readNGWMNsites.Rd b/man/readNGWMNsites.Rd new file mode 100644 index 000000000..0aa0232bd --- /dev/null +++ b/man/readNGWMNsites.Rd @@ -0,0 +1,37 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/readNGWMNdata.R +\name{readNGWMNsites} +\alias{readNGWMNsites} +\title{Retrieve site data from the National Ground Water Monitoring Network.} +\usage{ +readNGWMNsites(siteNumbers) +} +\arguments{ +\item{siteNumbers}{character Vector of feature IDs formatted with agency code and site number +separated by a period or semicolon, e.g. \code{USGS.404159100494601}.} +} +\value{ +A data frame the following columns: +#' \tabular{lll}{ +Name \tab Type \tab Description \cr +site \tab char \tab Site FID \cr +description \tab char \tab Site description \cr +dec_lat_va, dec_lon_va \tab numeric \tab Site latitude and longitude \cr +} +} +\description{ +Retrieve site data from the National Ground Water Monitoring Network. +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} +\donttest{ +# one site +site <- "USGS.430427089284901" +#oneSite <- readNGWMNsites(siteNumbers = site) + +# non-USGS site +site <- "MBMG.103306" +#siteInfo <- readNGWMNsites(siteNumbers = site) +} +\dontshow{\}) # examplesIf} +} diff --git a/man/readNWISdata.Rd b/man/readNWISdata.Rd index 2e66b64ac..8e47c060a 100644 --- a/man/readNWISdata.Rd +++ b/man/readNWISdata.Rd @@ -83,84 +83,6 @@ not be expressed in periods of less than a day, or in increments of months M or period returns data for a site generally from now to a time in the past. Note that when period is used all data up to the most recent value are returned. } -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# Examples not run for time considerations - -instFlow <- readNWISdata( - sites = "05114000", service = "iv", - parameterCd = "00060", - startDate = "2014-05-01T00:00Z", endDate = "2014-05-01T12:00Z" -) - -instFlowCDT <- readNWISdata( - sites = "05114000", service = "iv", - parameterCd = "00060", - startDate = "2014-05-01T00:00", endDate = "2014-05-01T12:00", - tz = "America/Chicago" -) - -multiSite <- readNWISdata( - sites = c("04025500", "040263491"), - service = "iv", parameterCd = "00060" -) - -waterYearStat <- readNWISdata( - site = c("01646500"), - service = "stat", - statReportType = "annual", - statYearType = "water", - missingData = "on" -) -monthlyStat <- readNWISdata( - site = c("01646500"), - service = "stat", - statReportType = "monthly" -) - -dailyStat <- readNWISdata( - site = c("01646500"), - service = "stat", - statReportType = "daily", - statType = c("p25", "p50", "p75", "min", "max"), - parameterCd = "00060" -) - -arg.list <- list( - site = "03111548", - statReportType = "daily", - statType = c("p25", "p50", "p75", "min", "max"), - parameterCd = "00060" -) -allDailyStats_2 <- readNWISdata(arg.list, service = "stat") - - -site_id <- "01594440" -rating_curve <- readNWISdata(service = "rating", site_no = site_id, file_type = "base") -all_sites_base <- readNWISdata(service = "rating", file_type = "base") -all_sites_core <- readNWISdata(service = "rating", file_type = "corr") -all_sites_exsa <- readNWISdata(service = "rating", file_type = "exsa") -all_sites_24hrs <- readNWISdata(service = "rating", file_type = "exsa", period = 24) - -peak_data <- readNWISdata( - service = "peak", - site_no = c("01594440", "040851325"), - range_selection = "data_range" -) - -peak_data <- readNWISdata( - service = "peak", - state_cd = "PA" -) - -peak_data <- readNWISdata( - service = "peak", - huc2_cd = "20" -) -} -\dontshow{\}) # examplesIf} -} \seealso{ \code{\link[=read_waterdata]{read_waterdata()}} } From aba54d7964fc8ae77f0c994ea616c9ecd726e23e Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 2 Jun 2026 15:35:07 -0500 Subject: [PATCH 09/71] remove old code --- R/get_ngwmn_data.R | 234 --------------------------------------------- 1 file changed, 234 deletions(-) delete mode 100644 R/get_ngwmn_data.R diff --git a/R/get_ngwmn_data.R b/R/get_ngwmn_data.R deleted file mode 100644 index d7397f599..000000000 --- a/R/get_ngwmn_data.R +++ /dev/null @@ -1,234 +0,0 @@ -#' Coordinate the request and retrieval of NGWMN calls -#' -#' @param args arguments from individual functions -#' @param service Endpoint name. -#' -#' @noRd -#' @return data.frame with attributes -get_ngwmn_data <- function(args, service) { - properties <- args[["properties"]] - - args[["service"]] <- service - - req <- do.call(construct_ngwmn_requests, args) - - no_paging <- grepl("f=csv", req$url) - - message("Requesting:\n", req$url) - - if (no_paging) { - return_list <- get_csv(req, limit = args[["limit"]]) - } else { - return_list <- walk_pages(req) - } - - if ( - !("skipGeometry" %in% names(args)) || - is.na(args[["skipGeometry"]]) - ) { - skipGeometry <- FALSE - } else { - skipGeometry <- args[["skipGeometry"]] - } - - return_list <- order_results(return_list) - - return_list <- deal_with_empty( - return_list, - properties, - service, - skipGeometry = TRUE, - convertType = convertType, - no_paging = no_paging, - base = "NGWMN" - ) - - return_list <- sf::st_drop_geometry(return_list) - - if (getOption("dataRetrieval.attach_request")) { - attr(return_list, "request") <- req - } - - attr(return_list, "queryTime") <- Sys.time() - return(return_list) -} - - -#' Create NGWMN API url -#' -#' Main documentation: , -#' Swagger docs: . -#' -#' @export -#' @param service Which service available on . -#' @param ... Extra parameters from the specific services. -#' @param bbox Only features that have a geometry that intersects the bounding -#' box are selected.The bounding box is provided as four or six numbers, depending -#' on whether the coordinate reference system includes a vertical axis (height or -#' depth). -#' @param properties The properties that should be included for each feature. The -#' parameter value is a comma-separated list of property names which depend on the -#' service being called. -#' @param skipGeometry This option can be used to skip response geometries for -#' each feature. The returning object will be a data frame with no spatial -#' information. -#' @keywords internal -#' @examples -#' site <- "USGS-02238500" -#' pcode <- "00060" -#' req_dv <- construct_api_requests("daily", -#' monitoring_location_id = site, -#' parameter_code = "00060") -#' -#' req_dv <- construct_api_requests("daily", -#' monitoring_location_id = site, -#' parameter_code = c("00060", "00065")) -#' -#' sites <- c("USGS-01491000", "USGS-01645000") -#' start_date <- "2018-01-01" -#' end_date <- "2022-01-01" -#' req_dv <- construct_ngwmn_requests("daily", -#' monitoring_location_id = sites, -#' parameter_code = c("00060", "00065"), -#' datetime = c(start_date, end_date)) -#' -construct_ngwmn_requests <- function( - service, - ..., - properties = NA_character_, - bbox = NA, - skipGeometry = FALSE, - no_paging = FALSE -) { - POST <- FALSE - - single_params <- c( - "datetime", - "last_modified", - "datetime", - "sample_time", - "begin", - "end", - "time", - "limit" - ) - - comma_params <- c( - "monitoring_location_id", - "monitoring_location_obs_number", - "properties" - ) - - full_list <- list(...) - - if (all(is.na(full_list)) & all(is.na(bbox))) { - warning("No filtering arguments specified.") - } - # Figure out if the GET request will be > 2048 characters - # and remove NA's from the comma parameters - comma_params_filtered <- Filter( - Negate(anyNA), - lapply(full_list[comma_params], function(x) x[!is.na(x)]) - ) - comma_params_filtered <- comma_params_filtered[ - !sapply(comma_params_filtered, is.null) - ] - - single_params_filtered <- Filter(Negate(anyNA), full_list[single_params]) - single_params_filtered <- single_params_filtered[ - !sapply(single_params_filtered, is.null) - ] - - force_post <- nchar(paste0(unlist(comma_params_filtered), collapse = ",")) > - 2048 - - if (force_post) { - get_list <- single_params_filtered - } else { - # GET list refers to arguments that will go in the URL no matter what (not POST) - get_list <- c(single_params_filtered, comma_params_filtered) - } - - if (skipGeometry) { - get_list[["skipGeometry"]] <- skipGeometry - } - - get_list <- get_list[!is.na(get_list)] - - time_periods <- c( - "last_modified", - "datetime", - "time", - "begin", - "end", - "sample_time" - ) - if (any(time_periods %in% names(full_list))) { - for (i in time_periods[time_periods %in% names(full_list)]) { - dates <- FALSE - if (all(service == "daily" & i != "last_modified")) { - dates <- TRUE - } - full_list[[i]] <- format_api_dates(full_list[[i]], date = dates) - } - } - - format_type <- ifelse(isTRUE(no_paging), "csv", "json") - - baseURL <- setup_api(service, format = format_type, base = "NGWMN") - baseURL <- explode_query(baseURL, POST = FALSE, get_list, multi = "comma") - - if (all(!is.na(bbox))) { - baseURL <- httr2::req_url_query( - baseURL, - bbox = as.numeric(bbox), - .multi = "comma" - ) - } - - if (!all(is.na(properties))) { - baseURL <- httr2::req_url_query( - baseURL, - properties = properties, - .multi = "comma" - ) - } - - #POST list are the arguments that need to be in the POST body - post_list <- full_list[!names(full_list) %in% names(get_list)] - - post_params <- explode_post(post_list) - - # Should we do a POST? - POST = length(post_params) > 0 - - if (POST) { - baseURL <- baseURL |> - httr2::req_headers(`Content-Type` = "application/query-cql-json") - - if (length(post_params) > 1) { - post_params <- list( - "params" = unname(post_params) - ) - - template_path_post <- system.file( - "templates/post.CQL2", - package = "dataRetrieval" - ) - template_post <- readChar( - template_path_post, - file.info(template_path_post)$size - ) - - x <- whisker::whisker.render(template_post, post_params) - } else { - x <- post_params[[1]] - } - - baseURL <- httr2::req_body_raw(baseURL, x) - } else { - baseURL <- explode_query(baseURL, POST = FALSE, full_list, multi = "comma") - } - - return(baseURL) -} From c2caa6d02c0d1dee64d0620aa38f814b88eb04c5 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 4 Jun 2026 08:34:18 -0500 Subject: [PATCH 10/71] Add more time columns --- R/construct_api_requests.R | 4 ++- R/walk_pages.R | 54 +++++++++++++++++++++++++++++--------- 2 files changed, 44 insertions(+), 14 deletions(-) diff --git a/R/construct_api_requests.R b/R/construct_api_requests.R index 937f80b0f..9ed7f554f 100644 --- a/R/construct_api_requests.R +++ b/R/construct_api_requests.R @@ -654,5 +654,7 @@ time_periods <- c( "begin", "end", "begin_utc", - "end_utc" + "end_utc", + "revision_created", + "revision_modified" ) diff --git a/R/walk_pages.R b/R/walk_pages.R index c703bd3af..4d2a8adf3 100644 --- a/R/walk_pages.R +++ b/R/walk_pages.R @@ -42,17 +42,10 @@ get_resp_data <- function(resp) { return_df <- sf::read_sf(httr2::resp_body_string(resp)) return_df <- coerce_num_cols(return_df, is_sf = TRUE) - - if ("qualifier" %in% names(return_df)) { - return_df$qualifier <- as.character(vapply( - X = return_df$qualifier, - FUN = function(x) { - x[is.na(x)] <- "" - paste(x, collapse = ", ") - }, - FUN.VALUE = c(NA_character_) - )) - } + + return_df <- coerce_time_cols(return_df, is_sf = TRUE) + + return_df <- coerce_qualifier_cols(return_df, is_sf = TRUE) if (!use_sf) { return_df <- sf::st_drop_geometry(return_df) @@ -118,8 +111,10 @@ get_csv <- function(req, limit) { data.table = FALSE, colClasses = "character" ) - - df <- coerce_num_cols(df) + + df <- coerce_num_cols(df, is_sf = FALSE) + + df <- coerce_time_cols(df, is_sf = FALSE) if (skip_geo) { df <- df[, names(df)[!names(df) %in% c("x", "y")]] @@ -143,6 +138,39 @@ ensure all requested data is returned." return(df) } +coerce_qualifier_cols <- function(df, is_sf = FALSE){ + + if ("qualifier" %in% names(df)) { + df$qualifier <- as.character(vapply( + X = df$qualifier, + FUN = function(x) { + x[is.na(x)] <- "" + paste(x, collapse = ", ") + }, + FUN.VALUE = c(NA_character_) + )) + } + return(df) +} + +coerce_time_cols <- function(df, is_sf = FALSE){ + included_time_cols <- names(df)[names(df) %in% time_periods] + if (length(included_time_cols) == 0) { + return(df) + } + + check_df <- if (is_sf) { + sf::st_drop_geometry(df[, included_time_cols, drop = FALSE]) + } else { + df[, included_time_cols, drop = FALSE] + } + + if (any(vapply(check_df, is.character, TRUE))) { + df[, included_time_cols] <- lapply(check_df, function(x) as.POSIXct(x, tz = "UTC")) + } + return(df) +} + coerce_num_cols <- function(df, is_sf = FALSE) { included_num_cols <- names(df)[names(df) %in% num_cols] if (length(included_num_cols) == 0) { From f06fcf5568eab2acb5bcf4ed3fed8785c125cacd Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 11 Jun 2026 12:15:27 -0500 Subject: [PATCH 11/71] remove old examples, add new ones --- R/dataRetrieval-package.R | 2 +- R/readNGWMNdata.R | 55 +--------------------------------- R/read_waterdata_peaks.R | 2 ++ R/sysdata.rda | Bin 327812 -> 328228 bytes man/read_ngwmn_lithology.Rd | 5 ++-- man/read_ngwmn_providers.Rd | 4 +-- man/read_ngwmn_water_level.Rd | 2 +- man/read_waterdata_peaks.Rd | 5 +++- 8 files changed, 14 insertions(+), 61 deletions(-) diff --git a/R/dataRetrieval-package.R b/R/dataRetrieval-package.R index 3a8ad141f..0f0d1da4d 100644 --- a/R/dataRetrieval-package.R +++ b/R/dataRetrieval-package.R @@ -208,7 +208,7 @@ NULL # "field-measurements", "latest-daily", # "continuous", "field-measurements-metadata", # "combined-metadata", "channel-measurements", "peaks") -# +# # property_list <- list() # for(service in services){ # property_list[[service]] <- dataRetrieval:::get_properties_for_docs(service) diff --git a/R/readNGWMNdata.R b/R/readNGWMNdata.R index 51e5d862b..f9c9a621a 100644 --- a/R/readNGWMNdata.R +++ b/R/readNGWMNdata.R @@ -12,31 +12,6 @@ #' "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also `OlsonNames()` #' for more information on time zones. #' @export -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # one site -#' site <- "USGS.430427089284901" -#' #oneSite <- readNGWMNdata(siteNumbers = site, service = "observation") -#' -#' # multiple sites -#' sites <- c("USGS.272838082142201", "USGS.404159100494601", "USGS.401216080362703") -#' # Very slow: -#' # multiSiteData <- readNGWMNdata(siteNumbers = sites, service = "observation") -#' # attributes(multiSiteData) -#' -#' # non-USGS site -#' # accepts colon or period between agency and ID -#' site <- "MBMG:702934" -#' # data <- readNGWMNdata(siteNumbers = site, service = "featureOfInterest") -#' -#' # bounding box -#' # bboxSites <- readNGWMNdata(service = "featureOfInterest", bbox = c(30, -102, 31, 99)) -#' # retrieve sites. Set asDateTime to false since one site has an invalid date -#' # Very slow: -#' # bboxData <- readNGWMNdata(service = "observation", siteNumbers = bboxSites$site[1:3], -#' # asDateTime = FALSE) -#' } -#' readNGWMNdata <- function(service, ..., asDateTime = TRUE, tz = "UTC") { .Deprecated( new = "read_ngwmn_water_level", @@ -122,25 +97,6 @@ readNGWMNdata <- function(service, ..., asDateTime = TRUE, tz = "UTC") { #' "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also `OlsonNames()` #' for more information on time zones. #' @export -#' -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # one site -#' site <- "USGS.430427089284901" -#' # oneSite <- readNGWMNlevels(siteNumbers = site) -#' -#' # multiple sites -#' sites <- c("USGS:272838082142201", "USGS:404159100494601", "USGS:401216080362703") -#' # multiSiteData <- readNGWMNlevels(sites) -#' -#' # non-USGS site -#' site <- "MBMG.103306" -#' # data <- readNGWMNlevels(siteNumbers = site, asDateTime = FALSE) -#' -#' # site with no data returns empty data frame -#' noDataSite <- "UTGS.401544112060301" -#' # noDataSite <- readNGWMNlevels(siteNumbers = noDataSite) -#' } readNGWMNlevels <- function(siteNumbers, asDateTime = TRUE, tz = "UTC") { data <- readNGWMNdata( siteNumbers = siteNumbers, @@ -164,16 +120,7 @@ readNGWMNlevels <- function(siteNumbers, asDateTime = TRUE, tz = "UTC") { #' description \tab char \tab Site description \cr #' dec_lat_va, dec_lon_va \tab numeric \tab Site latitude and longitude \cr #' } -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # one site -#' site <- "USGS.430427089284901" -#' #oneSite <- readNGWMNsites(siteNumbers = site) -#' -#' # non-USGS site -#' site <- "MBMG.103306" -#' #siteInfo <- readNGWMNsites(siteNumbers = site) -#' } + readNGWMNsites <- function(siteNumbers) { sites <- readNGWMNdata( siteNumbers = siteNumbers, diff --git a/R/read_waterdata_peaks.R b/R/read_waterdata_peaks.R index 216b91300..3fb614475 100644 --- a/R/read_waterdata_peaks.R +++ b/R/read_waterdata_peaks.R @@ -22,6 +22,7 @@ #' @param day `r get_ogc_params("peaks")$day` #' @param time_of_day `r get_ogc_params("peaks")$time_of_day` #' @param peak_since `r get_ogc_params("peaks")$peak_since` +#' @param qualifier `r get_ogc_params("peaks")$qualifier` #' @param properties A vector of requested columns to be returned from the query. #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("peaks", "peak_id")`. @@ -78,6 +79,7 @@ read_waterdata_peaks <- function( day = NA_character_, time_of_day = NA_character_, peak_since = NA_character_, + qualifier = NA_character_, skipGeometry = NA, time = NA_character_, bbox = NA, diff --git a/R/sysdata.rda b/R/sysdata.rda index befdb185603ca74a2e65996effa885b2eb756a68..986927ec002622acb519ddadf49656714a7df1ac 100644 GIT binary patch literal 328228 zcmV(pK=8l)H+ooF0004LBHlIv03iV!0000G&sfa$aij14T>vQ&2UKVgRpfklK zA+`t`^LEM5g0JmSTuuD9u`sR7lvVPfxn?(q?bVY_ux`!iOcMtyHn0Fp&YD$5nI-mr z9`mE3LeYZzu=|Y}tx>BU9FN?{n@A#oTEjTqW*sD2D+tx%&2D)`_N=PT3?mc2YbN@H zk{a!+_$-pH+HAFFBzdLWWdd7B#F$^sw>i|U4|k`ewO$C*0cY_cr!l-j5I->1G)oOO zm5iMSn>-&Z@~uv8*&G9d5-X7aFmGhvfcDr*;@jft`5b|`xM7j^goNa&79mC2xg!YM(GV(>?h(QIL{`W7yB%nV$0% z=Y3-<35Hu1sEgv*M(RQ(yh)V~h#4-_Mp{S8d)wK*b)bQ6!4XX^@!lg$o>v9!OC#|< za|bDz(nHLA@N02X(!gMzMN2bAy!ah$kDx|BJ)IS%h*Gd{b!sSMa}(!CYZsJ33(?fA zF?SzhKMXQvv*-5yRdd;Zi-*!CKomXo5E6)XDqjhiz!gXA?lg{lB0=uq=B6<4PhpN? z2Q`5hW%e2sW_w;IO}y~T{1f}3X`O-(w1$l;sNC)Qdl;D09}FhoX>tdlb{dajJ9S8* z^&5(a3AtVbH#vsT+{Gy1yzdo6ns1w}!&+~?!G~pKO!!%>pGARR0S|<%0v4ms90ut5y6pjqHz}|8&jh{ZJ7Td&%}Kc1}7bZ4Qo{2Z1 z2$N3}0IXToGO@xf$1+B$Rrg_WVVeCgLnXXG=82PQGyu zx%o5itQ6|Bo8zvUgll9G%C-#l8qJdhfaPF-el~{bu7z_r2wLF(a%e0N(UDc_q{m?MtU{Jus6ybTf0k8ZCsV3wPJsiUDg*>eAP*nSTiDWZ~0Cqk*=9v=uq&w$C zz#Rk7>{Rr`Jl&~M0)578)Q@mFGf;^WaYr8x8^jm=Bxqv`ojV)dIWg^~A1G-?YMM;1 zYc9iCR$k&({OnK70kuKJL0EDdu;1xSTKUqcCDK-#lp(Z8lXrpFWaYy6+xy8|_P&{|=`HH7Z`DR0RGt)alVH{+*ORy= z8VgH&W|&pCT{mSlZAE5^&@PSx2c~ZVVzI?gnhN5)u1w;SiY2{_1<3goEilxZWNtqw zd{vev8n`a5F=bUhBcSek%yg=^7`4+#Uzb5LNXCsykAU_SvFG5+Ljx` zH#7tHvU$J|lq`A>R;}5xD{#6Fxe9B#a*>kysS9*>t+@r~`xu{|a9WV;6jPT3%1LgP znrotle*lzdE4!(NBrZCkKvFW|gSNt$`3LpxyRTZlsu3Shxkp~UXRIjeW}=B9+?n86 z2rL+t>>&Ba3F5Q|_nNp!d9ui-kJsa2IezoS#kH4g=bzUc?1OLAJFGj-JMC@I>b4wP z*trr*?09-PYOCK&+sAAfp@yJht0A0#m8!zS&I5sF<6ImUSWfnFs&eSus@Rt<`<-nz zEA#=62c#ZBF_KHg$iMhUJlMHwUPaPXEhPyPHpX0V8Fq@V3BDgXg{46dNjKXicBu9) z9kM zL5ar%ZVd7%R%JGVSDvmlJSBFoJPlaaIcF|;?SkySGjfg`PC8!L5I0PvOUVv)Uo{+t zdimr@_HlNOCoS*z1)N~ZTOa_(_~=Y)xGIR z&SqI;n*K)gEeO0Uy_?zS-qhBy=)EtAqbcur4z`s(uYrLv3jBI>ziBj-Rey0cICpqF zbCvj~IzEGo8It9;70>#e{KxO~&fkqfBK*0;lxT#W)?3q1nwX}*JbI9hQLf7H(sV{D zHgh#s+9T+c~^$9M^%KK4?cN_X7ejlbB3&%8hO~D)iFzxZJwisOG>M&T?QHj)qc94B1olSmO z08f6+UZ&44f7a9}ZDrAB*ifC93 zj}Y z3aZ-%tmVh+PjL9~fp6M36=6<7zC6@?s}U}&eiEEh?;L~s#Aj`3>8LE>iIWPzkP2k_ z-lOck*#Xy`(8--=Z&m(DE(L&YeO=0{@US7O-d6Sp%Q?3CNy$uW8AqBlhZG)o1MP^^ zloPa^V!r&_b=?E19;mvN<(#lh5B=9Ocm#eq8X#!dMN`*`;Rh0bgvRTARI6}I`^|ME za@ABPf(V&O-wXJr7b5u^m#SQ93mulS#Cs(L5do;(x*mg7aY8DiK$1dL7Ez-IL`|-k zOH;i=5i5aBF|(eI_LH!{ERD~!{p+p?ri%o-N)+h-3w|g>M@cQxKtGY|{>5)^6;rio z%HzHcM0!=#`ZL-cS?R#&Oa2$7J|N|I-UTp|3NG{U^-t!$DT*EZE4J8QQgjZ5$6uXY zJ4xFNA-S-ep zD67v?K%%{#b|#bddHVvyJ7-Jbfp)CUo9jOyhxlv~(c91}>VFG;s0J5M8oA2Cov|&h zH50njY#d#Mk>Dt(1b5i^I%(s2LuBT|=Qe>y$<^iuTFyFl*&(+Mq>oEq{dw||*#Em@wKBjjwer`h)SJV$atFmR zOPlz>u*9dMxK~k*CTGxikQc0tP~z_TrRL*m*4VD!mHU!sp!P90_fd<*F*`^(Ma{fM zpL-BCNY)C5wwm%K&>Djp2*V+ePY&9+zq+{iGSp-`Dc!^Rqie-e*jlw#y{yFln&oEF zKvPYJ^g_xcE$6XN$l$bB1Ma|_$LlWCFIdbFL31Z5AU+bR)L!ce1~(HgnJ}su6;v+ zo$>vL8?=AxH0TLr7*E47;{hRWC>y%|*AXHL$CZ+A(%TG;;uMnzDr_Q%5jal*TcQ6A zx}23mHT=Qe%rQ~aVK~-H2{6##8MgLf1e?+X{9@a25eQ>=gQ1e#&PrFt(^-Mwlq~G= zZ4ImT{>nS1K^m`58$U5vaYf?zTJZ3c>}#X@5TvD~Gjw(YGQO2N0$KOO*^*WZbx}lxXMS zKS#Tsdz@1$cHQ0^6G`1%qF}Ai0O5!!D&+k7m>i(lJgRGa?Jp%>S?Jj`3!>!fJhf|& zB#;!haZCleKdie@svQe3bx=AeMFr$Ip!zz;$`GJ0+I=QZV=?j{NrH{RhFJR+Wr|0j zMri!~#P!4=RNsbtWRG4%d3wQ#@YyVJH8r)soQV>#8G26m!$7ZUBc_mj#9&D6!N}K@ z^VPQP0X!yb26FyE%vKk@MRv5pd@ZbBQdMo^Y}j^K-j^|GbBL=h``)OZd-ll-`&GR} zdYu@pWedz61&{%I6kr}Lv1Q#WB=Uo54`Om=LXTUdRQr6EP8ljP3_l~L>QKXE9x1B0 z*P4RSIY@O)U{e8JT0=9bp9mWhV|!seb;D6|F6BJJ3q~NyUf7OUpK-}shj5|53WMmU zT<#`lYu76JA3CF4;Dpj4CYmS4aZDU88}B6^CILdXKD14${&X!+mgn+ z22W_@&&B;xP!f=n%Rg$B<>EQ!pABIY3CVF<=UtnkESHsoITbqLQH8O5UFe9s>V;!p z&X^YH`t~A<1mWLB&gVgx%L53zUBu^WO9gm>Qr8auomk7J|E3-$jsw^rSZDsD$t8Q4c!d+}xVxRY8`fwX4Xo8XUthdG9d?x?0qLm&-pxrGg=W&Q#{ z=M)<$AYBHhgja}uMw>0R$qXj^RE7F-N}DGTC-AoB=Cz;e$Rp{Sl{ZDNy!p*EF>p=( z>QjIrQh1O-m%XlrTtwyq4im-n*YZBjVIpQQ@{&DkTBkTNV~BE!?JhRLy%<=?MylmL+ECf8A;j}c_$3<3{El` z*bdt!)G9Tl&`>W(HUS(k|17@uiZ${!kKxVD28bBWWrA*s@9m#ed9_flbc;B35K*Xy zm7h&hMJg<5Xxo-fzn5Vpca56UNvHhQDmt{;5q|4?Tky?8dDZ$SZh1Q+Da)eu;M5R{ z1WSJYUi1BbR-9r9qtQ;Vbgrq4T!3qkaP)uI^RDfj(bDMTp2agSxdIzNv#{^|E~W^6-?NLv4NL~YAGE{OvVuJF5Y=yJ!Q6h}%ccRMPT>V~ol~wTxPsChgR!a$3O`-f8eR(b%wo2y< zeZD54y;3}Xu7|P9`}#bN1=QTR2jGu@?PT_gq>lv*R_6tAcE5|aolxQ%xz|Y~c@%v$ ziFP3UX#qkL9DH%(lQ;tZ7ElD$JlHD1XTfBaE(i$xY>B@n)f>h4i zPrs(Q9VY9X$nr~W@2OR|ML)U>1pwc(xAy*00pplQk_9>KsBp}yH8o3DxVRKe6{g-p zkme!~S$&oFvF9`VFxUfju}qc#>Czmfko!#F&`K9>A;m-0k7~{s7RpMkla!{Ie19kuX zQHg^0|0?xTk;K7%t&O7F2+|29UD z*Z|3=@0z|GYU$GW$&-tz9?A%qc;Iv}Qx*gCW!g&LbwE9}gC0{C7E3=r+RxlN>C?!^ zBL4z^KyWDbc+QGg94c0|=g17{=iT>+L4x;jC$RM|;sbT081r<%KA>@~kIQooRA6X? z!za@4&#I;)^enu+2NAZXYHuE(=!eOhV71_)OKtoz&VJVrpw@Zfyg*~zRt#g{f+cI6 z#ZTU~1C=>-iQIu$EFCLknfD+%$%D=%V}4f`9F$zy(a)?zfT0bXYSRyNz2_%r%J?*@ zz^_H$U^Th^sXhe59RFT&+1Z-bpMFnhnSG}^3U_c-XZs5?9fK6#0v0u0V3V(!dRnPo z_wkl21JGc;V04835Bxb&!NKyh0})HKU4DM#{z!4N)Gf>;{0X&c)PbxDME9Pb#DG26 zP9_8I%9tqBo_y(WX(@{eE(C()TeBV-!qdRD2?H|s8o!m-r?<~eAenPEY`78F?sFFm z=^ulTKrvOzigk^ln}n3`ZkeuBMr~4~cFJ{XKKI#@d1cWmOaE3Y*vL2e=<=Q+n83@+ zW34@5?wB9pYn=4txqzKw-mRzQ;NUx<(2#<|0g}?zxdoU(Ranlc85C?4!Z2&qNgtzX zYg%tTt>ES#*zG|Z%f*%#3&;!D^x(H*NWpx%Rd;)Z+gx=JAXb!5Mzyn8B%DyFO~Vk) zE2YQwVq?7dM#D;|A4FVr21BjrEhzGfG6ihmst}ZRL||u-l^h1?XHqg-DbexLGX^4o z;>knMgy6}>9tDE42EZs`@CB}C(H5&Z1}%KTo2p~*bs_6#h~Uj+2ngulAX8QbZLN%- zlp~uQ2Gzxzf;2XVlMX@b1(~PJGExyR`#kW+_@?;o``r~mjI-XerNh9oY^OOY5U=J0 zv6L5Q1BN94|jK`X-=$Z=e|UnR>S^-2JGshp3YsZsL^W8 z(E!rO6;m1i11^Q=h0_<7=LhyZNUobsjq%^pKu{)h32$Qf=*r+FaJZTwGq_rc2xD7= zJ!k{GA~{L|gUR+^ie=`Uqe-M+nI_K&j7H*hCcDHy8=)J|)hq@M9~MfT)sOlRD$yEc zgo)ual|aX;<4MxTHz-sx3bGhIm*1i~Hi2y?uoBLjR#DFZ2L~+-(I&*&bmw^h2TUfA z+u~~L&_#%ID#ihjE_K9lZNipm(nvJhM*tMVu*cN0D%XAGq{dkzYAUR0j&LzmIfQd4 ztW1*4UAamCIwSc;$;ihzH)3W8OT*ecsQWD81q-KT-9s?s(A;zECO3N!W}qQ2=Nos^=6hdBjQ+GEdbBT=a)D;?o1XD?B55hpX4YA#rO{ zVvg7ERj=HDhLHozcg(oG^t`9tp0fphL^G0{7b-cBer3OiNbpt8r@zVmuK_lSITe5P z06n{e;!MqoK)tS#&P_^j75`N0_hb#Dv0+AJ?!d5OLB})UgJ_nDJL~I4$S$jMQ{TQ_ z!ROzh{&Y6y%pbc)l;s|aP|StrfbJHuESv|o3n614OkvCt1ndnSxv!>d-u$>=Lwwl! z^6Ag)Cm?8?Bw0(-!ph%OJA7CZQI8QR2mfmZ&Qp({I*1MUfijusMKKsEI6&Kn51`vN zjRQQ&m3!ElQ?%=uTUsRDP1dkwQ}D!fe~*yoFB3EV`sT;nPQ(a)E8Yb)n>O^cAo3_s zN)F(o^{Kpw@R#>*ms*)@6W@osq|D7C#gw=MUamq%pRE!Nbw0Yqa1dD%!9QSQ3iSkm zsWta^M^RdZ)$*7VIZMM-(UbMt5MAZ({DX5Hlg0`(`W;2ag1u4a!}yc&?F22;n_Bd(5pT>?l!p;z+26Rl$6j#lYS*0q-l=V4=EYX z$_RcZeRW-NA1*)S0T+wu%UUGQg(0Vw>Gp$|%jnKb%MqDUMpDL(FnMb&fyEm~D0_12 za2==n+B}BOJPM0a`dagJV5&{yjm=T}<>^d6_yu2(T}A0$A2NR> zWORR5=+cC(=0~i&-?ugmNs{gmo2iNfvNa|xsnjP2Sb4*8_dx+?jZHB`0}K9W1(*V# zs}OhaAjEBrEJ5`%W$cFq$Ebqa-uZ*7eTm+Q9KVWEfZ-_#!v=_)Z~CnyHt-~W*mbU2 zeufQY?NGbu{DDCg&q`<2?Joy`=eU8=t=HB%j{qUhc&}s8cjnTc%qbVSZZp!f=w2bF zf+&KNOWp&gpw3Q%%ju!*K=!RMoXH-3K}*lDzx@Y|ERq`puZ#rb$f2E{l;|h>4Uy2?9?d{UcND9FpDr*6AiK zeDQ?9WZ@kr0BqhzF|hiE2xOiUT~Pti=Ex9Ocn6(h&6MO}o;Y(nv1V;fy``|9E;rIe z|7lvoky=U4#!|5|vb184&RlaD-q&DmM`l^GQ}gxKQ5hix_E82eiZRdq*ej6vud}M= z2%JyH!?o#3^79pcD_w%)&56!Z>ZOOEOy+V*1v8!yFcBYc<;+|ez%qFdp~S{?N#d9k z79T|5-A0gUo!FTCN4~shkiJQL3nwCDr22#wm`%+-sTrnNn>TQ+NwVb@WIUe&RK!B% z)Dq~73t>ph)SCDgro7i6W%mW<_ooiHV_nBiGX0i-j)~)ztym@xc$N)>KEny>2f%b&1b+`AsVjir}_IMN3WUaa0?I~)}u-R{6%Z&#WRSUbSP(Q{YFul#9Qx zD!{3$C~x;q_(%K~c6Y*>`$@9$_=Dv&jdt|GuDto7cR`IHUI+^q!^w$6Ygi2pWgJ`l-oitrC%+RJbug`ru*}IdcbVfQ?f#{X|?)qj<*%D%6ey)V{6DT#i~N_u?5Ny;`Ct zv&fzAjX7_knTXBc!0=wH(oNZ`cr9Jji&_ep^g&L!Kr5vvN-JLp0LoKW>&E?rX$y#z zZcCuxLjEB<()(F4MQ5L8{*YggL+#2Jcz~hz6%%Ts7UNq`OCFbe!{=OrX7!)r=Tn?I z^bFS_d-~?#X=NOWTh8&kA5MI7d6T(&b)#@v+Ene@Z*8K%SO2UP4B`MlzfS~HrZ29m zzEeug19&wAlo>WQ$_SLy)WWUq;Qg(#1+x6f&_G>~G#_eZ`p@%Do54@g&eypZG091% z^wb6kZhk)jUFETg+}#04ewQdk4y2c~`P|^zlu}`=3|(KJ&B(j(Z2}N&1A+0}uR+r) z;ACUG+0)jwpZ5v>WZ9mz94` zW?qDe-rMt)7fP?UC%qTo{;T~kVnm>zCaM9ydLPPK8N@}Qnb4NJ+J2DkHBYh=@rnpY zwc=v=6z%PJP5_tNC%shN(Fx#;X<6lWN!C2DwYgb{WK78N&#(z98j~~M<5N@@N+;$c zcFyt$iU%~!d5JZz!fsbF*Ej<77l+eII~N{s@;E$lloH%=cG5xY%Q7|@2 zn(qbP((JGTya5yvv~u=f)(jZrUT9caeeX6QuvC^bsh9BJez=o=4>{}j2e68n99x+R z@O+nx4tx`u$^JKvf9#t;!~erVYZMTyh&-G>CCcNXp2QFYpi;`@*{$83JSij6RYQFpI#m6m#^7r4RrDHH_XNj6Z+}O=L7k2mWKT4`jHmD16JVk!PFl$@V{8}q zZ&IlGRf;GIhU8J&FYFeUI2Xeqs_U9S^3Q>Oh~sH%$O(GmGhN8iz3%EtQ?4#VI!q5V zpJ&tvP*+rRHKDr6Xa3)V2SNT|TvAnJKy3A{Qa4d0ijLqZH=I<{OBOX3-t!4&H!w2q z4O4HXdWB)a?NQ825wMxV3i=$JG{kFK+ANtE&NIyO(MM^8ed$9vK5u` z6bQFz2YDAhw=R88I*BCgtRUZCeDvki@B`LQLBhtKj~y=Jv)QqZuElO!KG5W?sl$WhM=8o&a)W+~hm{bvYJ2s{J z|C}it7Omm=T8+mZ6tdt@eqM9l=gi_;u0gL9y=2AF<(9wJ&h7mb3nn{y3yac-fO2s|h(@~* zk{lzs(_Zk1jkxP`2it|50%PeghuDYTD?IKYr9bhs)K1z{%z)$lI#i-V!orRAb%XliCC&sTlqrY=QM_iFskw&y%g|00 zIcY-1?*=236qU04?Fj_-+}tbhTc*iqO2|5*DHW1bN!kI((*qlU$Ad^o04wLO_Gr1y zZPRfk%Og_*QwY_P>gMemTkOqe)JGK$g<>HUddmu5}=<7rV7nCu*LeT z5}0lvI`a99mV(R2Kf_177Uxu?jifh0;zw;7lM43?v?_~P$ht;B+LTiEF<~4ie6rm$ z9)h~Z@#3R^;_HOsNQSvg>dl5KCBE>`;F>k^6IvtQdkU&j#B^qm=&oI$Ln1Di%=dyq zSlkNe7_$|3O^$3i?n>LylNKB}Aj}b%gJs-J!l*5a!EtBkua=y=eey2(m}YOco6UG^ z8f+<4PYj$@IpRJ)PBgQJS(b~Dg)UZ-(=3Qbfex}B{3=DmTrn!c$SeXCXxU?%dL4Gi z-^@=<0QWi)5I<>5m_a|cwy0V)T6>yP;~+I=ZR;2xOGf;ZgrT!pJ3+KUN-tWcZN*E28tn)wI z!zd{ORs>&|5nHAOH<~rynrd!qRW~(?QVeb~=t?K>3>4HlSio#HzjrFN{V^bvYH03U zE4se0REaLUW}-Q?^m!xLvbD?BI1$bpC0}1C@}pr}eu{H{-ZS|ElCC_)okQ?su>4R49{&5F|M)y60*1H>92(j}F}=w) zPZdU9q=(GKsYhzkp+lU|=aZI;Wn+^0) z!{fAwd^wP&>k*-)wEG=!hQ8y42zHWHB7Ld3d7Q0O&uC4=k3jU(YP9UmM-W|K))a6JMBFx`-$Qt;Ek%LiF41GLP!g1I;X)zUQfo8y)H0+2bjw9B^* zD5=&VdQb5weB6ZV9hHIZ<7}oR>b8mw>bbdF{$-Xi*6KP_>DY7veHTHuTXStU4XaDB z(4`5Ey-@~(wzpgT>N>dhA`lAQiInG5zaKopEua+kmTi;wSaY`&f(98uBR^$-mQBjYCN8q+pSr3^S*h6qe5Q8?hgQeW6 ziK7()?U7_qkksos4FQXaVp6cn#_;Crz#<-EfXeYgjj$>52-;$x;$UFs~aVaT` z8n(SUbx>ji;Tt~~o|_n+O=Q3RFr`-K#&Bi|64N((&szK9VC!x#k&X`rVVO@fYGyeN zBBz>^4yIfb*$1`Ax8w~deDa$r^XY(ru&^qb_OMNxRx^@)d zk*GjSMi8sjT@W0dpKQ=K<*6-7Iu%3Cmi(dsk8rGp*)J!W2SzuxS#+hY9(OvLbuTTD zQYpMozQ`Hv0e2DEj{}X%>vfy}smnhf{c8&NB4}(aAT(((D(J3>Soy=< z5AL<23NZiG$=cpbU0n!&^D3K>`l<(rs0`pfp#fFVA&)+XnA1eTQin?)YaxyvVj-8DFFiHvw;fh?la-n-Ar?xtH=NV$(Zdlu;39AIe`dpP8pUHjP z21W8jd_z*StVbhKi_C@vA?^$IGCOW?WN!khD{~i0n-r`o(VXI=U6CH^59pl8CS}S( z{^1M1#2>-DInAhmHgAuLkRDFHI;DG1pR$!Oz@n>=PGWHd#ue;gfEdW`M5-wW3@{aN)$2f;`>VGPn2g3ziwP^E4h?wI%&;bHcVIlmy^2 znZ>BZrJm`=0t;@lt;2ENbTEWLM&K{Dd^-YK6)Y=Nv1k6h=SO=$!$l8${+QzLSUu@! zrlEKV{1y2}mBIBJ^|mv2M6=)@i2B^0^`%f4T|J_q?C$k7Hx9CwY0{Tyd-P4{bA1#x zj8(_f8PbuUHZ@8jU;qTZdk>A>B6{tj(EVP7ijM=6>BizOwad>0Mk=*z4DdO+irC77 zy0jOOY?Hw~09mn%{4%9@hf%$@YTqx#O3)Z9AW@8qRE0c<3HK0Hi~`KU#{^=Yk!8L^ zg?dB>4uELNc;XVMaM*FdI1a%@0$=IYbzc*2u3nqo#+GAUOO5KHB~1<4Kc897Fdv#Aa@fycmL)8H+E$Az~}7=;yuJaLTj^7e8z zy-ZXiVldEwsge%z+VvQ?<2_Z2=Wr<)R&R@4Yx;tP<1vayCwI>Ks6Q~AjG}!FSNOyB z_B2jHCcAYX*7g^3=-iznBE*B0n%@>4G&>!=HhQma=e+o}pBa4+=FIq=5=v_(>d{A?03G*|pnY*MWl~u%}4>9 z644U-9YKajW0tH>SEBU8QUG^#>xyV)11H_+VEq)z1n9i8lA}A*)UJ*NW9+kdm_cNY zE2Z6?tskb*-Mh+47$DWdd=LuP?SOtUGEjj40;wP*dGRb})z+#YQmnTK4E8ijF6du3 zpqa%OicX(iNQ!WVRD4y^lvQBj)cYJ7%KaFkP4)O7?~G2fEoWOUBXE;jFf#aHJRuW_ zc4gOBKJD1cvjGDC=j;fc3#TsW*qh5*zkyNJYK}I}kfR<)Vh~_!;ne961<$*3cdy2K zLiT0O5hlh(SEULbdeq-jk^g!@XYMG&8FH-sk5<%iohq(5Y>Najjy1G7bDGXt91yN@ z!SEnZMj0C*|@=*Gb3j5GM z$36AYr=j~_6m}}Um_zWMptkn^? zo0iIPnTFFziuquE)WO$4tQQ8Xz4tvihR`~ZXA0KUlu3Q?qCQ&d8*tsCsr>e=kk(;P zW9H5Z`l?sHs}hZ>f>maz6kadc2_-nOp(;lYxXg&DNs$_sWwqEA-*=H>8kf4Q&bce~ zGD7RQIs~+G)%da)gd z9`Y=y`^dc5UTwo{yhP|2?Z3 z2*620H>65p_jHM81uQ`|Yhn$*XxF3Ko5Clq*DbIEngDeuep9m|v^4|03X6E={!si_ zPlkY0orq3Ik~xn6kw2S7>}|Z=cnlWrUm1Er({twQ%y6IxQ{@L2ISV)DLI;l> zIN36FH}xdJDAya{k_Hl*FfA9uf0>wwd3D0QHX%BmBa{x?rQNml#)$Fz2O_)md6gO* z>3Eh>Mh+_oTQd}2`l<7?hd+-VdrEWD3%z?+!E|Nw|9VtqCUv_o9lv*E?!W`f52D!t z_zMp&5d`*&yy`J4MRObS@IZWJCBv#r}4&-e59GTqhamyn#0Te@~ zqT-)x9l>0GBrrj;eF*)M!u(CBz={%pqFeco*&P*wM|MCC_4Y|TE%A{s1Gy?CW5NgE z|8tLlZ7nPCfezPf{}94wXJvF7sH}7>1iH(!+OI;1^{}Apy~gBr1d!~=V<@yovsTj# zt4Gh=AcJZ`bOiq;nKxYH@f`>9_&Cdjy*=;4{PJ!}SG*O|THwgl0)*#AzccNf6lghu zhNE7o*V?Ul^UN7YOxTbiw&Js=G?3D0 z1h;X4*oJh>rY3%ff_$;XA#y`6X_nloebFBLjHrk`a^z54)@OKua))$$pJLpaps;nK zk>yGzdlM*r1Rh!8ao|Y#MK3TRV#ZReps6xq{1BDluDA3dD(N?!c({j2mr(#g~ZDBO+`>O&&C+h z(w#Cg6J2NTan5vr+a{wlIw0m00m3Y@*%xwbl5t+{SWo{Q41kR~oa8oVN1-aP~D)+ zEWWRtI*x-(DQ`0uWA%+X=lH?nCApL?F<2_yy~9hU`s-&XtgbbgWKyBECKA&Wqh8N4?u z(oStnCmD>Y9QzPauzB4&7iXa)3&8AftOwJcCb1)OR94p_8kZ*{Gb{wvKjhc*J4x|Y)nH_arCRg$j7pbN}T;ln6g!mup2pp3_( z2QIje**QoYDzW5sLT@sjV4fZG3!=%@bq27Lvlu?pcW<_mZdAmWUnOQHMZRNy9jg#ojS-}Om}=Lb2jylD;ddB;rL(Z^ct(pH7%>k>4!V(b&=LzH zY&DZh)4AP4V#kn)v_6N<{oUr%Z#zrX?hc~h+yg+Y9b+cY>CiTq)TP6L>iRgVH|SOX zR1?!yG&K~?n;OUdc8CO8EEiRR?C4yZ6Of@@tb?)b(%ryv8%QBldF=>o>Beq z;P;1cs9p~ir*`g0T%0%phDfeA4}Ye)RX2Uz26-$n>IG z6ji?1VFK=m;OOe9C9iZ(P0tra_Fe>Wd%X9F7au*wL)VJAsH}K6)w_CmYfGivSBeb< zXLERer1dHpxPc*a67mjjuF}+^Um>+FjdIg^d!TMO))c(|hi8hlEK+VJY$Rjj$MhR+VS5lK^1DF6b*@H}@%UbV$6NVBqA4JX*vvp_1xGs597kaLn2IMr8avfo)x{mAiSU}pRpoyPf6Byo2 zOA28Z0Up%;T`BQmsEz-IeANu`oP1+TxHabbH6O|g4ks8-iYbpg&0?R;G=-IFu-|UIaCNrKFe5 zOsiU)@6EP7_mZJMzn)p~WGn1|Y6HFX-Ms)ZK+V5FLdCqRlJLnfcn`d!@qG~#$%Oa_ z`d3V}tYwMeY=LFB8*{j}68@f`osj&a5h@nAjYD6;|LC;56JOQ)T;66uEgamZOUPE5)=B#XECx#})uR z);e$=ELXLuuWdOs{Z0tD)0=nG?*~7&C!NNb36f?C=lHDI*?mk6UCkAPwrUkd4(l^%W^UvQCj)_Q9QPdt0Xqx>B?SnDj zWIj9+Jh5T#l5s$om+mo2TbU0hTY^lEvF-<;D=8Ob&9FO64|s^$QzNnEoH9L6fCMIt zadhkLrEP71TL$i)*CE3xXx4Fc%#$CdavM(Epa%d041$RcOa|T^7uQn^XZhj*m`pqU zuo^CNP5NGlJu>Ws;7v}V2>u1Rj~QR9msG8}>=O#P(72|51urg3>uSd=-*(6@sHrEZ z)y(bKi|N=w=?tx_mKGc7-+;0Bk(vXF42n*;SpBGPsO!daXx zL%P1n*m}8(=L7a}gYuRi^1;M|A*O1s+9M^Xo=b0*(mayXxm$jz>hV{?WgylNRSBK3 zZkpIhD#XDx8X}J}`+P;h*!Uv}oV>WHD~)5u#n|p@OI-h?iRGb$NM-#A`k-Ph+|$R! zU1>fkqF&e$BjTEYd&sLs1|;%uhk4<%k}9Lx1c2yzA56Sw;_T>h4NvP}H>Cc4H`+W`BaMLp~S+ z3B$oyqGvaEcS*W5B&t0s^C<|Y{Z7M*J_XP=R}l^IkhQ53m!D4uK7cb%h0w6&n^H*B zvztkRKLK`5vh0}dC~R#CPWI4LAojFRTV54|gY%Yf8Hv`Rl)ulNnEO})*c`oP_pK4z zm)ch}j-5MV5#yBI&MVVee1NvcVBN~ScsBKtzTom%^5v(V$dRO16~gTI`>Hjjebf#F z5|FNgCoV`)bwoP>>q>Ym60JqEOh3P^d!6~W_?yJbk}v>AAHMUXcjK&(_T@9T0vOp- z^S^YRN5UJ{u}W>EL@k6BK8#gIkG_7@1?Zgt(eb$Chu$xtyc>hq>I-W!lC;_8u#JNr zE%Ok_jrKK>+-`E|$g-^&NK|u+6IlRn*um7GBY@%ey_e8aN~xBf%S_@m*WxFYn^HFF ztW5b<9!j2Tq|EkGh`h8&yOA77n`PQdFu)?&i$!37x9i0YFZq?b9x~EkglXPd5$%jc z%n#t42``?5rMs&0OM6qhgnu0+x3M^igBz^^KX)zP#h+Yadz(wqhnNrP&1}ux5;G02 z;pU)>oV;(1VW;%mb2>;y%dn@DfQUcT@glL_x7#~9{Gd?rUDsu|fP!^1L~rnE`}T~jX0Mh0X?Z2U^!YT1>)_OzPmlrOp*%}l`x53#cZ|@|D>v>H=F(H#M7{x zf$Sz#yLg_qC*qp!k}#DLW*SHWT>sEWzG#}1IovWjC_rY1ImT?hh38J2Xx@^v!Er^X zEC-A`$mDntA?#gF%Q|(Y@kT8E(f_Ce{XD0KShT-KK)g5cc8_m%NABwCTt|q$XG&BC zCO1^_8K#UjSR59@7!L?4epcEXeV$>c|*cSer4EU5;wIUG>*h!mruDB{eT1mqLZ z9T#?+K~rQV;P{DX5Xjo&Qjx_+W;8Q7o-g1UDnEIdSN!;=1|G2k;iLA~sPanjv!^!` zcHwq#qLpWaha~8x0vr_=*tjhgxs>XEq~}zJM>SNu zPT9@_@ybXh8YX)%7~cRh)MqNvR7+j7gC4_uS2IX6Z9M#>$$haNdxCwqXw&Q!t9peU|f$H0@EwW7P^E6lg6PB?z#!S?+;2%;2;{2SF@1}H;!|6oy_Pdpq zWf`kI^f2itvzGQ$p-4@#9N57xVt_FLls^xI8TDv?e_V2OvAqlWa<$A4{)n`_Q-7e4 z9`*$E0=sjF;le|}mro%yR!Qbc>!5>MtyXZ7=hgQ-Z%)@_H8pVRDV5y=c>TVIL5K>y%GuV|JD3-ryMeWXao}ljSA!+eDZZ30$euETp2-z-|#Q! zW3%>fA0E8&de@yF%&3}Xw?o5_>_E(YdXD(5>+;(xcVfRU0;Uc)XBSoI_WVYB-}5R8 zJ?6+92H-3$Zf~XgPLFTDnQWppj))G{^M$7pQPVI(8vxq}6C4Y&H>b;PTZUUCpHmC1 zMKFTxWoxWoZQDI~6C8c}Q;S5LmY)MGsw^wIYtSG2N(F+jAjvYj1?NJ8?ew*5&<`ZH zNJohmRdnoQ@m1C)!=AuGID#4CfN!))h16P1ll7{pojK{0lU&xA-7)IvMNEuto^rCd zx&pcB(|#h-2F&VVhJbSV9U9WVVJc2NLwY{)-~{drBv>fZ#&r|j)HSEZ;82k)_5K<7GqKi=zDy22(30WVg za$o5@-$Z8H^f_1Bmk;`F(OtTU__7a5a*L|OTeNR<@4$Y-+6r;A({Fl>V|m9*)AnzE zZ^1{i!Zn=FwxXpu%_(XoKn}HB<$}M;|3CS0No6lzOk7UpUdFsgy&=5ny(<(r{M&w{ zv4rs@R^FFiL%*E%$Yg!`Ulxp`vKALGj#Os`54bI3rt6y)787u|U8~jI2+6-s*{dZL ze0+T4?QPpZ+izLzMuu=z)BKk+Y(kRcQZ1IJkhD>veaLphc_H*OFg$p3ix`ahSx2T! zp9>6jiFaML%%ZTVKPh4oWt(rdOxXz-PqWnf6v*@5{#5fwNc;|lNLM7a+ILl~_n)+W zY%83?)SVF!L-dNAY5J69-tYUYoP3?OTf7oCK1CPa;aACJoh6S0@IuakD{#8mncAbD zq_dtfiOqx*c2|An&(~=AeMyQfFuZKoe`zU#E`KBrZ&22S9~${ttwnnq1;p zt`9QT_bC|G8CN{v@nB{oDfh+*ck&HK9sdo>M*hh%2u#vI=pD1%$2({pRUlwTPD zSC)n?q|*@uS>~^%Dy+W_oHn`YUYJ-JK_#Q`<$Po!mJBC&iD00eVdxj90>x-m{-4CX zoo<@#B6Fj`^l>B?vuq;13mTy(oVR>m;NOrF6C>@}5kYVnw1As?#m*8ErGs~Z{SLD= zQB_g5R=}&{+4PpdF$U4UcREKcFWg{KH~7q4FUUqteYOiDT;wa{4&1n$Ey&M!77qCN znDRdRm{7Zg&?f*3D?h%_Z6-j#bwWDwSSqa~f1wJ5fpAei#NM>eO<$n;&w>UfUR*LB z-bOCMwg%Ch>I30DPC%I!N}{hp0VJl^pfaE?g5!A|jpZq%V`whPE?~Vp72tAY*BAY? z%Ur!z%c9(H1gU8qmUwNHX#sh#MYe}k7Z#+&@-$f{?;e0V7w_lb=KE#zr+RO!{v3(@C{$-B6M&%}e=>F$us~kimkt1amT?&tl1I9hAYiri}@U@hL zUx7932J#OX&oU$qNP$jy+am&Nr#2hA#5^}}v@CUS+0>zV`~-H1xZH96!-+80%=8Re z8>4h!Ur^R{FxTMZ8y*yfBDHFFq)x8Fza9e%z|Vy&YtScep9anQnKr)Vi>rjfW?cz{ ztzH4vqB=+opBRzoPJ?w7KJK!cHbrMK!ovg9z9c+CF>UctBm|k9^*t(P{{A6e3?)W( zcqXqXv1425wN^^CV9D{gu+Pj3o7LsiY12usye||aD*6g34W@zq?ueeHW}UDmkv8}W zuM97A7JRLQ(+4r*U8>-O+Jo*zOJMiNcDQRGIMvvNW3r=ocBM~b3|?ME&)hbGGHDO~ zN5~2qHynD5q1EuOYKm+_^yN5ZshXQHc1@_ zan-3|n1VKRRrw3$BJS?1T*Y3EsPSS#OGb;2a#l|W?!0aMB#M6dOtSFJk6&t`Vz3m3 z_QgD_Daro+ehGW5FyI}pm88m=y=&aAXAVCAnOi~A>3Vsi5@ev^gp_-l z^sLFNQr}|Ai(4gl=>zB5>(sG;8V&)SevBYc`#7d4TmDmFv-hgAiy^~7Nk24G#usud zh#pC`A&~)sn!}wv2(mHBC{O|YSFpLL-Kqct;7YQOz`R${(i8kD64 zAiv!< zJLJ-ZA5%4O4JK-^nOlh=Q15Ot->`NI^66(>Rfiu}k^hH1--_1!xAt=&Tsf_S{482Q z9AHb1fL7@@SNgt;f+$kgtF(MA--t+;TY%&?EpQM2gmDw}X?$RU1+vuiLd6YAir9FH z`AsWcPMI#CT+$km;`$1)LdOpnxu+kwe16+7W9)Ws7R_TbM6sg1N<1H+#COrR%X{Zo zc&pV{Z7ru)A?$O3PPJB5Ow+@-td2??4)9KA=4xpoj?84aOQmV4p)hvFYX-!YvPf1& z>jP9v4v%6n8>b!K2K$ytAcn`udT19CR1Na&-pML1<9xCh7Xa@z`5_9~8JWI4JXfA0 zej$v(y=BMwz-1FRjT}b=c;^TqaDh_iz8&ncH?w)vWWx?d7{NAowy6MZ&JgQcSq?vG zLtXgpymEMvOqzWh^(}XBox`~AQnt9fu7|3rF2RiH8J5W`O@0o3$>$V-ZwO&N zS~rD`<1Gm)To2J>zYhA9_~f`(5ANpwHb5uLq3hLoEJTyezd_#GWsUUeWP;+-a2#lGw^hqEbGU)W_ z(93$US|3MTRn+P|4UEMsL1hjS2g5dBDhZl1CU#xIk{DR*DLxrO5!TiJo>AbY8P7wz z^kTZyfEZf&A8q5()mkx0d zyR5uulbS3Ls5eBv^L0qpoo_Qw204Jeu`UuhrZFAK++jjwJq?$GIS2zT?D*Sr{%O#G z_}qpJIxFw=4vgBDe5SKwC1mqy1c_%j?Yp~y4v!M#sB8i82{)oqTlA{X(F%gQO(1vJ0k>laf$8vT%!Ab>K zij7*46@WDOnn_d%*K5}y@U@5R>n-bjK7%%35cWz{!2AH8LhCMaX!F8i4GUn#N4e{v zq0Fm}i_weu1e6C{F`N;QC!vFU^5aeBW9*i_(rf1vYr@g_0yiAGrm*f9U#bJYoF&*t zd6(;8+VGA)E&j;=9T>2675Xl~CKO2Chxn++F756MUO@Iv&C!_Q!PreR3wUTeD-2hrhQmxatqoH9l2fZzv2rt{%8lizzI-GT2(9D}KXy-j z_*k%D!9?}oab{Mg)#Oa;4wF+Rn}od>cukpU4y^pAK1_|M3h&?%Jdk1YO1OOJT^u6& zbMWmH!YB8mP)xi=YGi~L%){ox$1>M?Y_YGO+7BbxQJ3TK&oYfCQyibA z!SIHVM+GTDiH&tss@h)zD=@F}fykw~9HnVMWLTN7@h9L!*o_ODGHkMyRisE7FbM@f zzkB7wadC_y_Er};qcB)={`Q>hUPxt({MezJra$o6T&23Ox*v#VO# zEHsTHtpt3Cx&PF`P!|+d2K}6ZDN|Ubc~)a!B9zCAu)C>bPNgN?EOuuuv)m?&RISTSs*1-A6MzDg0b)ZyHrku=To@` z60ow%Z(KR}#cge{9dMYnN(@ZKu*G=n*B}M^YjB%CrWFd$NgzD0Z~Wq)|1We5^8GY+ zu;EEZ-I4tXv?V;1eIr!q26VL0bA5Qe+;VW^qKrZ`z+*nTtB0EyK}0eS=%)>0?cRE5 zK={nHI=(p+_w0rhEgowj&5mxhl{t*2ndn8liJUGCWv|7G??%+<{_Wd?TBb#nlX%$i>lA2% zC%;a*vyH3;yIg+ukyZP|p%W`fMdg-r7i{!raU@&L2oU+O@2DDG@^BmmOSdT7$=8DC z+MMnn_HnC9`bDKSOktyc3_S(*`PJT(I2VBU_GPUl-lxJW5KqFwkta^J)rq4Bwh(%30BHR11}&Lde(q3ZZfKXu#rXq@3qYQVXHfJ_KB9gPDt_7t z)7O!cx)R3RaEDd$z_WDf^#Yypc0Ba+VjM}P;z@LuMkvfSZtpL&^Dbb=CND=~X=a;hVK>Ej=VW}>n zgL_uQ;vu5Hu6TMvjdb08MEJ78T_*77DoxEfk~4PdQ&80%{*dCutZ}dvc2PWW=d3Hn zrzP0(z(rLRaS2_|=cr&Dp%#gVthv%N1$w{Lmt^;kd0 zj@nHp@hg}u7tq?}?Z~5%Kw%*zc5Uy z6Qw*ik~m$rMt6%}vWipFotxKGn_N>!(mV8l%TgxiGOOZvevUV`Yefa&$RJQNK+ked_?<(U02IJPJ!S$Zm!KV#z z&JyX>cF8FNT^I_Nqh3mD8vQP+Ig!z_@px=xVNMpC&n1A4wwrzgJ5Cz_QYWA&uQ-AD z)?{PL6UiuuOUO@`*}wD@dtNyGpbSrO2UW~@bIcA}`MpxKdW^oUM!31L?5RFInV;TZ zvYxugR9yPdkdc;SD3?VoQ7=#qLU7t9xo$!XiFqHMpzXTgjGy<1dP_7>J zNkoe^zu?4{uv{qH$+wrMy2zKJBk-JOQ*>?KuHraEtbo5ig`47LEF#jT!RNH?GW}bp z6=49y-43KArr_CKToB%k)L<5~KMKI}s}xF%x+vwvEf)6J)~-8A-dtX?)h8U4gqd;8(G&gG=V^=OwpWy$4n^Tl>8s3!JpXNFJ++~RU=L|`p7+0|e zB0Qg57#9tqzKDX_moqG)5%VCqh!5_K1dgcnXqa5I6dgQvr}$J_dcUtGi*y~g2|z$o zp3MP7gT9wsBpChtB2wVe=jK?lrB`>T%?$KT>CPY-p+1SKu{BzTvs&MD2aK-7ljUV1 z5w(oMeBe}mS<>fx%T`<@p{&- zvGv7NNAcgXo<2>dW++4UovW{{~^k@yJkp`Ge z>E3i9i4;D*woHcrLWV$19T};9N{sUwJ{Ud~sMz4C_zN1TFPmkJ!D{6=|I?CcXcM6f z?sRfnod8B?TaM?PWpvB#MKAfGcvWrSL_gFy$~%Lry-idigJUZC$U$C-C-8>z;1b=EUQtai#+_bvqfUq3m`M}dD|@eVhxuof9>8!UvyzWW(Zhbq>&murkVJSUOiz8nmN-L zz_ecW74xh%#P9u+-gkKZ*Oqkaj!0ttU+^*3;*{oUb`Qi?X@&6xdHZL_dYg&1pzYRv zr*ou=k(I#Au_F7BQlv-R?xN-vgnN=zsTMfyKSW(HjoQX;p~fLnFN0!i%DlBRYbJ@X zEa-Meqlczv_Kw+M(}pIJ>F#8?oZ;7O>h4|o3eXMWzLKWqYh0(8A#WPV|LC+P zZ1c2q^Rg)-{5s%`-l_N-*1v;@+Jl-UrHPYVLg=7?ls<)5lcLbkEYe$;CE^7GEbqz{ z)TdM}l798w^K-%`E$OH(Qaq~#-KWIX`Ha(}(VRIBT@!NRq7l754jYG|CR{vwrUBaG ze@u$F(lA?gIc;|lacD(>$@jQ>XAwNrvOot$QfT;hc(mu59 z$s`(#Xeo!P+nb|cD=!VrK0Yj)dUr(%*E#AbcDCYra!Wlk{R;L!yH!IJRMW0_anPJ& zR$!EM{8Q)khgo56==Z?)&>4|ib0`k`-yDKNL-Kv4BgG|`_^mCAR2?z2NvRZ{T#?>a z(8|)#UCLo*y(Ce?f7kg8gioNKX0|^}e@oIi!SDbfor`54Cp(Ak{WZE4^tT4JQh-rPWi zvM*?amW@dsb=918_Jbi(dz7*|JC>XPe7oC0WN1|4`#fos$8#x!8DLrJS?-&WW2Efr zf>BT?QqC%oPk!s@QtPdaPXlBWk^=Q;LoGxLj)P4#KFlyRU+-Mx9_ z&A^Z$5Q#N{nh9_|^A_IYue0cuh?BDbK6C;n^{gXtI@WhlM9`w$E=u|q&-Fn&OXc@v z_M?@yDd$wV0(v9I10Up(Z9_4HhOc-d>`acFf$D^UJA9@;+~8$!7v~@nsBCc@aX>n7 zBP+SU_SV3ZIj9wy_^oj0v0DacAFa!KJLhbqxqcUummAA1!Z$l`ZN@(AJZG6Hc2dA; z;t?FsfL();r;_`;_cRNushC2^G=I|KAd}Z>3XtvsEMS90M$OQL9BOE1px9t@2iP=U zx4+lw7Zq+I%>**dmctF;bcE)v>jLKiempvz*D+9jS1ceL%veVP!v^_V-f_wj*_+wI z8&X{izevJh4oPxxvLgu%KlbTCb*`l`5iI;udDeH6$hLqcxbs(GM7kmXx@9n+d^HU6 zS5NuRNPZu@wXMcjfnK+wf|+u_8=R*y7HriM;@ESo0ZGSTO^eBaFtKL(i?z#ifE4~i!!bkQ-m7W=uz@Leb9}>qzjBiwT?St? zCmkp29S}22eNQ^1mFTi7)>I5!xwB93sAPi+Sw91&STiPzC$UguO3|n$%08w&7P+!_ zFl>?G0s%#LpTx7RPvTZOn4t6#sC;<<0f0$)(6qX6`EF8fol4?kc)?9*k=zT`)zVTd zUG#R>cVyEjMCs0+ZATVfC}_chpHJBUZ6?zF*>l`S=0hH%%vh>S^UPz?*^C0t&_0GK04%LIcvfKiXM9qh+G zjRt50ShPx_;z&w!Te-0MFVAc|?1b@;$)offkyVkAlYm^~;@=FuId{$wG1WPDdwelg zyRU9pFIqgDIO?vU)s-dXJ&j62C=3RpUED>u4%Ypt zsS6fC<(;)~hrhJ6*EX6*jHdbAjGNA?6*TzZ9xI#xxnE6ccIi5MZT8*Q;r@Yulil6y z1^FEO%m@%yz2`>7&@;zrw9|QmGAF9fdTT?X_f@CJuy`!V=^FJ~660G+W64Mt5|yD7 z@pYhQ(QnV!DJK%1ff~sr7Pllft!-Gbc`0y>GH8i}bMXB(KFsaT`2#qj31o0f0jeNe zqwqtUR^}*0WaeS*4ieOa{r4vYt+BWsjHNyoYd^F{F+oKZFa5ArZf(m*-vI=X~T z0Cas6Q(E7dLud7(cCBieG@v-G-mAWnkx|~ZxqJ!S?MNpqn?%|zNZ{*K>+te-&BGG; zxCpBb5eTK<(3WLba5aKXM4E-0<{J-jUAw&e40JV$MEzrD-#s2MVl>g#?PW{mB}MD2 zUG)JaD-DFPSXXAT4E%yq%6F4E6@Pef%wYGaXjF88ZC^C$jj~1<-&Ht?hpl|5i@Y2q zLfD@PyP=22QXuD(=Z;X0g7jTrg1O`4vP5>mED)V&?TMSo-0;fH z=9~zG)owPr)1^P_GC2kb02G{95AA+9$1^I+$1;7jT7|YWZ>0rvS%&b5>g{0^a=(jz zxA7k-y5HVLx=nsjc|{I&QQcop`i@+%4j4*oeTE3FkXjMwOXgNVTZd(9VDpouwpGtfo10`8Q z=>E(`<{N6Vc1rOPeqp zo~PvE23!)OblPq78dKuX!Sur;T4;OJWz#5sR_VSmN^|G7^aE~GHwY)Ne@gXv*VPahR@dUZi)Id~p5hcm%-qSzHln z+oaY&e6qmT> ztCUlt5J9U!GCbvPp*wq82ee$O=b|Zc+0B8>je`w&m}{E&XZ<9}Qa1kL90|K5WRdgXyw zwZAM>wYk!Kd7>$eQT_Sjd0X};!(CHJiY2vH0%lq0n2gbeq~g^XNa}iXQCDmf^FMBn zfMv1|-*$_+mlVeZkgoNF-42GhYVNh^F7k;-qkY#msr@EAvx%^<1EI(63&WEyP5Hh4 z58tA~y2U3^XxgD&E56eSd0Ez8@j$Q!neKn=ZXe19^h3=}$2n}4^$m%gCOLRjUFY~* z7nzr_v#Vsw9B4BE27mG4ssXLd<#l|w5KT;})OebiBV9Y+fG6Hw--S*pUN-f8yM+Ju z%AQ}6>iQbO=zWy6#+;=(6T1%pE~+1hH7delnV?CnGB78--Ec%{Z!Keb6Mfv*(v%b_ z%?)3wKl(ilsRikJI*o4m%*aq)uq{k+*e@I!J0NUZIa#a&l~(I3CTAtGANj_oc5K29 zrw^Erb}Z{g3FiVIpYF*q9$`?PqC)nPDU2S2Io;LuPj3W>UJB8}pX^!7U-&C0y)?_Xp7{|HH9ci>6+6Y__x=B7RfH zJOrCSSiI)}8q+&BvYE+)k2ly>oyF^@GF;XmLr>mikF55}nYR6^nTWj+l&D#Gnd6!-fI_M#EN?Z0g@?ftZ{S%{4@;?-^|xAB@+3 z*YMalgeS5kL~?W5xd|fHzTIS5FMkw%m8w%_sjE>cP=TO|5#Vs`bz1Wk0I+T60y?J; z!uI+o5h%O}o}IMrMooS>)OI$!rjHN#rj&Vwb**qgo@PBRH}H8Bpc%O9Tv>a z1*@=oQkk3;IUw;Xl*6$?(rQ(xAydl2@rVM6AxInQyk!<1Fez?f+e2RqQ`dgU)D_CE z9k~TX1I>>P1)L)KG-MAsvN`E2iJDZ?WJzsyGklV=BN9h!Xi%k;h}#9S_;h8FhlB4< zopklR2={GzcBD5TNbA=n#hOV2FM}eHNOklgtM?VcV@Ozx?#w0>w2{!qxfebpa&|RO{Wl^m*qKt$#siI`}8|v2S*t7#H_)#4dQM&RHO*SvW zY)&?O2+{|JzbBS-pF4he*IDMZT}4NIStaId=&od4&!@Ghs84SrT>5N8?40e++l86o z`s=NQpT6=pmxMPVnF2r0>~Tzz1I*KjHXB{1lil8V77|12ZIewEROlQ1Bs!`!6c);W zZh5?rKe4Yncg#6|2yq=rKiIKa(nS8^%2u&{izcww1^z;fgNZQS*#v>I)Rt8Wz`BY! zeNsoJtvcClfbj5hns2b;)_9SwSb^cYI(*nqEOzf%nAI`2Mc0USlTA#QoYvk8?@L=Z zVB{84mk@X|vVnWsOY*%QF%V40a$mI-FP*AUl?h_UPa#n)wquf}S7$<{9lx+F*TKht~o*B(?lKefZ7xy#x=v<2X`lE(_a_JMzk z1d>4bV1-0~Y)C7yU*yw5?36M-;E{cfi++LMzzn20R;Yje`H@NHN97jISE{~0YvbZ1 zb!bY^7xI2z%gA7|*9*yZFP6C*RHXztGgB#yeiqD>$DnUnW_f!^-CNX*FL!*(5*l`L z_4fo_iZw5hWoW5^{sdJe6;8wU1CIC?-rlocWq*T%JOHnzIZQ*rQDEO#9}${s9Wis4 z6Sk0R1O^Khl;@SADDAJPhsTaiOL^$|_|~UP+b>_^(dk^EP?sw7xmOZmmE@Wi9%8%9 z-SydaCphhTL`sf0m?CgFM9z>GtCC02*76=hgo(psGlki#t3QXfN8ee-VV#rxoNL#u zdZ7ZFW8nJ8ZFU8;lULcKT1tHrTNHCsA^KazpvgjVYfFgD)&~;UnZPB>y^sA(W&t}h z&o=j=rYBC8wzUEV#(!~(vAkiUGX{Pf$phLh-j|+oSJ{gVYQFP*CVkQ9LDJI+vn86H z4wH*rT~(6Ky(EiH=V}>*+*-)fF7{j_^ z_>X%xy*~hx-&44&IOB_XfZ}qohli_FUIB-p9R%9n%4&hfuM~*`Q!q~$IamQ#;XHWr z^_qU%Rg@S~vj1wVd}IUo2XH;eq?G*By6?#;CdV^L zn#xWDFT9rfK)gC0YH>HBbS_M>2?3qz)Z=^I{4c+2oIQmFqiDBG7_RFY9ggkG14rf- zKaDC8=AL2dIU%W=iGnT!!5N#T(Z};SGXP5RmYi^^#}2M^oagT0FW$teP5%J@Sb=<~`jy>d@WU~W!ega<~J4+5=#D&OX z+d)Rd#`e|r>+1V?HEL1ZdqO|!Ob@TS511=wZkzzE9mZ^GLgi7V@7$s1T&kib_AzaM zvmcbL4)vU0|DvM;DFH;Q4gY12k)`k^ip1q$uZ0*n4||qU%_(X_X$=}YYl;L!%1o9Ha`3>n#WJwG&v_(H-o!q%Z zD?M4^=?a(Nux)BJ;GzH1NsGp2Dsy?ZxHV;A66-BO3FXTVEYxH7+LIT=P=e<4*DN#H z@B`|1xs*jdId-;KQRT1(25iad*$aQgSCSKDTDu4;fFVA+sy5pF8*){e)FCc-?b7kw zCLB!xA30>A5v2>ti1L-Czjz-0F{bt=$)xsZ1#xj>kZN5!yga6)*dK5FCKb3-_039{ z^BFi*oH491v|(W7?;7#Y8t8^9{F#j1Sy?4Eyx1iuyCs!t(O)IYhM?`tWeefF11&k% z;O>{tPi)*`68bk_@a5OJA)}`C9BGGfS=lnL)`9JNo&_;#u{aopBTDG#ZAg-bqw%Hr z4eu11y=(Fn_WcEkFrX`!Cc)a?UrjIceVWOS#}OyB`pLivDG zKO8ZpqwX)`swjmgfwLEdk9KCp0b%tFY3hW7&dc{}%;c`nKCGYXIU6qA_K3!}EUcf> zXi(uvb$;tCy`v<#bYdFvNFZ`GIm#-SlRVeMJ+TTOnR~@3QcU3sD>WI*TI0TeHLM|E zrr7{<`A;Iip|{}Tbzs$NnaLS5K+a!;l83vIRw^soO*_Uc+0(8Km>pB0b`@oa{Yfih z-4=HYa5s_Ox(Ue6iExTq=%6bJ@;>t0HS_bb;>`K3?{$km zNPsC&02b9%iis@sR2Q8joj`I(N?muo%top&6(=l_iG|0%ej3Wd_aZFJJS?lidykPp z1WkYOrqiBF%)^}w2nG=Zt4hh?;@Oi7H*3FwgQ z_}JV{Mf~2L$vpzveZ(H}CtpO(eZQvmD1}}|z-ZpFb6-f9$&$uli(;RSsRL!y5Jrlx zDyUVA#Vox@ZytP|(1+c&W=KVGx33v~&J)A9HES*uplH1W2uikQdEFUdy&V_15Z#^5 zZ`YBWF=W&QQNL4U)UYzxE)T0TpH79c0#yB#H}Gc)(u7;L0^QPjuq{+FHoPk3N9uJW zTOx@S!+N#xczx$|0`#OE-Szx0wW37?b8}sW+%1WLaa5yqQhEH$=e0&H{)9CDkHv0BL3i4ZA zI@$iY)q}vJvzFGwKC8>781lctm#32Gh1xEl8FwAr@t-WM+4 z?fyellzEmgVAnUAhI^|zooA4VB2j<5wj{wDJqVEI{13?-oH?W0w=vTnHO3M&kzDt- z-gVM#e+elF`rdPQcC9fTv)n=4Ow#NufBQp?)Hz?89sF-+y%;yC>g2K5Hs<`2fwe+Q z^3*~$gwWb1%h)`oJc|SrWPmEVIUN5a1Re`TIZ+9d+7}*xd8z&ah`D zB#c~5LqOLCk9ma!8`?ZM#YY>1L&7_yQA-8;clg~id|zi?=OuqbvkV*!1c@wqdI)b5g14AX>&@Natat zYqz#bZxb%`D}Jyun=RGR2V}fgi01wdD(P}IQARZbJ0E8(F9Xhu*&6ByjhPUH| zNDue@vgcv~$i6$TAq)2bZUm0GpQc8VE-d>G9$&aPhfjf*5zQi<{j1`9P%VnhC?5OB z3yjlA>^EM$yw4nh?hP8iVFYz98-uAYY7iK8gPvkGxt(aQjP=d+zTenIw8k{lrK+jZ{=?f7F0 zv<@@igA@hi4$0oFf`W&|$NTN2*t-ZLSz_qi5;nJuumD3qyuZtC6F5TSxwG#(N%NB* z7Ek_Pd(D-f+aVZoVBt$vHiJLC?p<24o6G?t!d(bhYK+>Utm65W?cAkZl-MYfZP2}oNv< z=G&Piob?l1X)A2HVCf%yse_B##gt}!Js)}`{Eio+sr@nUvH$4aHuCPd+n-?05H`5-fp_0q(B)k8pTu_=~w9{d;TPYi)U}Zg_(4Q4h6Yy0xI&f`4qjl{DKS zLLqKNm=~c=OEYH6W4xGb{&sNJh%O7-~ptL}q=_!1bNEw9vAssIE-*G2DwCJfJa61enYEuv3B+7B57 zh<~z(2l>BR!{@WR$S9b`r};^{81W%7ff&OrNtNz^AhRukujlyN%R1R?VA?s`j^#6C z#J5%jG|`6~QioJvs17=pW%a3j1l%42K(!@-Vsrem+A9or?3`D|5pl-n-IK3OrW=>B zM1Z}KTmC@qL?R$0@319_0h8svDMeEk_`mPwv2!gr(cKqxI!kc(Q{Oi%`STbuL0~(2 zortBN2jqSX!}IgQW(xBvw9i@Y)vBzwyOzh}y&)=fes!oxfieg*+*e~cVL-z z=Jcfq$Wgw=efqn)bS|*4?#CIWT9<2??*w@{%szHr$ZpVb%T3B7DO=inW}SZAh;KG4 z?i5dali>xzhnf+_oj#0$ep}aZJQnu>FT*NcJ-c=2_;BS5v|*)UEFW%R)q26`ixdl- z!`!(J0eGrvtN@1;jXN*alG9-y)EZ&ZO(LW&+T%WHdyTI#A8QqRU>l+$6p#5DLE11r z^S=0)g$VW;Y^d&qW93M&c>+s_G+6|~+c7n!I_G7(cemXeX<#Zj9+QN~hl9l(ZA#ij z;dFf+9AEnb$^UE>46P9o`Nj3>^lfNV-y=f``QMch3HGLO*ZNL?)D<3t#h}QOXa-vc zJB_%&@Ks^~IxCZJJmvd7y*ggq<-`Vy@1|}EEyw6XPEC@nbw0&ScIdjfrEZ z<;-leuo{$OOun;z)NcRLtGb+j!&s!KJPl#`?!f#J9#)seTZJ|-tQvQ0zhaR!j3Elo zy>E5K72oc|fxz4Pa%pH>Rmq7JwKr-eV94aop54=YicBW|q0F;vnJTAy)VE$&7gcD2 zjogN(kX-h)N>|NirO{CiTQJ+hrF)-Y34wE8Yf{4Wh5?)x&v1QtLQ^a-q7`eKpWYYS zP56_UeYURfm{LMgq_QhMRdM$EgnSZnI(Nn}_zf*MfwAdliJy87 z2E)-(wP?G%pZ4YZrB7YAm(lTdGK|6KVp9t%Fd&DZmI`v zthYmg5b0vbdW7`XpbU&E&y#*D0fnRh0yv)J#Ye|`+q?h!Isd#pEfkk#%cbl|3(cq1G+0kGcoD4^6%mC^;I$=2nNgNm}il!bC|8VvIhyYxfli@9fR=x?|d>fC`F7z6MEd6re0{r8{&5- z^hU1)t;$u-SN-uyyH?TrZ1X)oAA|b(n@@RTD%RWwGySzV&k+Z*CRGkcH#I-VXtfkk zn!ONUZ!~wr42iN}Z_4ZsP_s6g(s>bI#d%HtM;%;!L~D8iMmafrz?NN7vz^;)F)NcJ zf_KR+*PG}6qdTKTiJ|ahsC+@^l70#u4pF&eteuSzpnqN}9xT-9{jkxkT zcIX|_1+kov!=EXA6DYfZzgl)c&OWtLndj#dg2mcs5TCK0##QEt1oOI?LMF^Yk-k9Q zlwInR*QfeJT`2?#pNZX)9k(`=JFI-C`m_R4=kfx0t&^IWlU=)?zP+6msgWFxdePxa;IG6f>ew)g{0ZxbyY{&sO$Dq%>uI@Q+8_!YmxI6R`VbPoQrMF6!^D zfO%NY+iqFKjaMT6S*P$>sdb;Yj-)#qC@2Qu+}koJ9`26xoRBv|Zso!0eMZ2;nct9r zAXyoQyeOOgUyOGADN_}C-kbnMeaB&s5$Ki8#`FugWzcqLzdbV>K$82naH9p{%rjddj&@7fHDeF)4yKw1+)ReLPuaJ>qay>+@{Wv9wC5*=rT+uOYLuJ z&Bli)6&M-=+GqFoFcL)6#ibaab*}nXG5QD$%{hUefOEIAEp8>0+s+)q4~Z+8hxQw@ zUnxLsS%l`~;Y;|-<4Q}yM@^qIcbkGBs2D4~Mc+U&^u&nOKaCP|ncnOTNfDbYx;f=P zAGdUTVSo(Oy%j5gfY}7bJ=>%TxAVq3d5S?O~nH1hr5)@3!~{t}b6XZvJuw$;Z#)w&Baa zW$ng^7QY3=#XRA5J1EwORSE)*gD=S+7>~Ohc~7#l0k7#he_FMw#p$IOZ%dvD^Qr(v zRDyG=;h87O{rN<+1+Y%SWl$0GWWT&RfaJ;(PR`j(a)B0=N`qVgQ$)Fh$K{B>Gj z8O4zL-(Us;LzaI}>+sQjUB7ts+1~T%C3x&$EQb-^bIAQDj-LDdtXS=<-}+L#641eO zMj(|hrY4KLo%fNrB5BR{2ZMxsb_Kr8{x>O_NJp5JPg94=HAukdp6~N5cq&3?M>m2s zUY3u~9o6=q=EHILLO~z#UVpX#OB#|&z` zet=|p{#|93GV6VeW_;SQ?(T(VO}RaC)GQ~%MdGK808nLtuc}eIkmP4`QcQ2x%Z#4i(u6)U$1b?RK z)#b|H6~{5O0N?Q6ix*I+@o5(&XxbPSlUT&weAO%2kNM!{dlB^WB4;=Dz+J+#k51-p z;#p8P7u9g=Mt0DemU{(7Q!}t^-43r+Q2hR9D>N+{?+R?1VSVaVj&pS9|4eO0`wq%m za4j1`+9X6~-@jkW0fO)Z;(Rno9yCRtMXIflhddM*bkAz|Xr3GYzAoUmYJlYm32z*S ziu_+~xd1fl{HRGBo9tEO%o zXqPnXJ%&6M+!`z)ihnZPfmF59FRAW0c;rIz=HQyVrb!a(x_uLs&2p zoxG`^;6Vw7L_$C9rzfj$J)|j95i+=HHK~lGkA7C&CNB8GlG}*)SlworY@w!JzYj0=ls{pWL}QUJYd~Ai4YoDh-d5b}6lF}S zCR=0?__81xN&L$|ateqCPUFmDgfw=znBg00dHK0ZExT#+b#|{s;I%4k*{~DFLMf5* z{0Dx>cwCH;Z3BtE*C6RRnRr@=rPEPBzZy`(dr3paTdRGu^1Un^J4bqkj~HWL_r75R z^~zq0&}b{<-+=_hFrh56h7s*WVDX6kFUBu+-u-l>=niOCM)-BkOc{6OpXpc$JDntr z0jboJa0^JbzuTfXo97e{M1{0sRQh0}N2Cx>5xZ|xTA(&=wBCIqB?+F9REs_j|Fwa! ztv?u0E=F+K6oNM_Y2?4RtR~CmBkj1jZNM)VWWl`Q*)b06;Nv*26b#Y6xwmZpgM
xgE1 z`4-|^S_{rr)`w^^v4-@6p`JNYF=hXUWm&a(5^eIU+l-L7H7H4kaKGDGPT=axh|-hV zPh5&6j~;uzouy?Vs$=NJ%^TD$70xDdd_Cek1VRM8D0yHWOAEZd+>ZpNY#xh=l}(@+ zJ6?T3PO`J^X5MHC342Rd?JDq{0_lI_IaS(c`*h~_`Ap%1Kq;r4swc-5ct|hAbkN(Q z8!D^FW%J0fFfFpNT|)w@ZBUvJTmpfg99Qhxph`k^ips0>xt~iFWWQKR^TW2VVEJQ0 zz<7GzQbv4QydMA~nSkRyz`$V4Oib=XM_;(yH4%rKbsA&XxZy{)UGeR}Q52Z0UKJ;6 z>o}*XCc9~{%i}B}crJs|d#&B`ryKvdt@9TO@!8>B&l4j}aHqKbTkbP@lz+O7^6-p4Sf8vaK}HzGrN&G)(zKw;DAB7^t=_O< zp<%t>2yi~e2aL->m1U9SzQQ8UU2c~g)xEGR?RS;E>FRwXMh^g0an;RRtqnr=-v@#= zi|oYdEk{q&ekGt0wG#nhGpFXa6Hd_|OiCxT^&mH_Yg$Kv54?Q|mux!Nii5aAZ;W5= zRB`}8djuM*GP7ETjsD8n;{S(KKMAU^!PDm8j6-a~HEvSelE;wvy*CF*B zH)%6K%As?zv$_Hjbfb(l#{a^3F4^^Joz}Z#c`HJ;mG3R_RKO0tx8pY;3zM{`N%7f9 z&~cia?kV!uHh>WnT;Zpm)L1k&=YIkx9{N<@FkY1IIq1ak)D~laK61}h#zWw|tGA+_ zYfJ1M4tu4%rr~=wR?!d1lww-eSgir<7tLpXe!m)hue{+<$}QW;Hk|D27feNp)UOJO zUA7I+ZHarEb^`P1m)2#Sh*IST`1tqu_~aOY#;nJHexQjh3RBV^$ey= zf*kxXb<4NDV%U*yI#o{asub)I3$>#Qv36L1#9m>*=cu!c+WwvB_WkH-%_G#sVf9O5 zOUxkyu&^h_s->qz@v?kCy!J|CA6LOX838tPYMfI%34J+rEbPJ#b5KhHv0ZVugfjr8 z;hhk{q#n&9*U?jw`qK9czv^Qb-^U?)ZwUD#(bg4h?32}{kb`0@$?9nLkdAxmG4Uyq+h@e=A?dsNlwyEl-+XERy3GkB9t_PpAnzj1)tNZ~63RRAT zFoI_k&2@#YP#_}Cz<-w=pR;z7HmTU>rr=wp@L>#cL*y$2zc)U!(cwpa z_1>vf7;&_-q2A`q8%7MwoM;B}pwyq>V>XHOVouDW6soKL59|YoUS`$-qJ*Q1neIMZ zfOyAObnFDFIAZQAg4VRaf9vSpAOsEy?EmN;v2ai=7fgXhJg!=j9~aqFW3DLcu#WZr z($ErfF!cE*c9Vo1vT*QMJ?HGyBD?ldt-Z1H`%=px(mlHj$@c&)IBF?C75HdMlE{*ZT;lgD-G>fT@{snnnubklQD5Yma@it{CLV#L8`7 zN`36EF_jP2Q24F$tbRGMvNkLm|WA?6_Xzzg2c%BKaNva z`BA|N^??>%7`AR3)YVvLFwW46kchJ>)X+%QNf&FJ1C|!Px{+1ODU`W9zsv6K5!sfy z(u^{`>ZmAn(qxVBEp^-q$5Ew}{4dDW{`PO7b5jMm zK)SBAJDv@(g@H=sfq5m7aVG5ZDSs|BcU76+h066s`H$?7i^yhEc%G`~^U8s;wUc=I z*^+5V$$u-TOpk5o;fpS(y;@@_={|Vz+PKldnVvQqROvK6*-&9puQO6(X|W+;H&rM*p=0g*xF@wI^uhe$aqRb)`|TVo&7 zM~Cw|V$Jv5?m1V+3*sWHuGZze8+6nHA(*DO2`6F@@r*c_$;4n&ynCfZj(|-3^D~0E z*m}F<7fZ_BK?1|FX?f$Ynu;jV&}CP|sa0yfIx3^Dx?GAUW5;_X+klFDLPx5HBJAK) zs%~owf7C>yyNVVk*_t#>v_`GQq3W*);w1Xi$%sH-i|2zbY2&HCJ&MPB2TTIbaQ>j7%B(|e zTGVtySS_E<*A-EfHXt?{Mby_Gsnz&$`h)TAfc!hX<2~{noA$zx@IHu#maqk<;qqq< z=Lr_`g={bSD8e1YEJO)80&fXinUU~V4m0#W4QclyS?Ct(!(7Qz%sGNv>Z9%*yR^Vx zd7s(#WX18PCwn;1DRJG-;V@)dMU;Pepr!V4`A#{=VFYclj1K)?-a#%F>meRgvz1`d zL4mX-iH7ph+9au?9*eQ}?eFv{|7fX%`YJJ6B}j6)T7UYuXKwyUWf$z$&D&Ucn6xYw z9d_GnY-b@!5{bkMci1$7oU6)5s~h@6+~|O34&`cF#VT6{*>MAW1bTB8&Sn`iKIhJP zQ~(|ty27}uKy4Y;*p>b%2$P6?i`k8$>+U=qK}R0M%wJa*b=ol24h2ZsAK)>98JFQy zo(;q_v-Q62HN-b}njplEZ?N;*YIF#v3GjW6`RzZo z&zh7<8G$SRUJ-Y zp~_g%oR)6x$G7z3*2bM{w+7eWC*H0KWr(Kt0c?>Mui94X^hB!q@{)?)o{rr$(zcj{ z;PK=rsTEzd29Qjjh1S#-2c5o(3MJg!NCCQ?-t3~0xsV)x^rhy+@ARxC{V?7pEM(gc zH7j5t19DKZp5e=uhUsDt*X?hqa<8t3DN4Lll#XJj_gxTCj_eXZV)H9IzZpj>5rRI0 z%~Q@}-yqtWcb}*0-3P8S7&D41#n4)Hx96o$&dB$app}JXV95meU@|iDgD(5cFkKT` zNBiW;$5eYIHFDSBW}0uQGMMB>IDg6Koj>}gU~Ff-o7_yJ{cU8#<@&gL?KeV6GtM7a zL7x1ivlCPiY6pFJT0mKh0QmWLy?e>_qi{!(`f7X5k&lWaz(>~?;(%4rZ$@t)z#0!H z;E|AXZyXAR6=G==o8h&yzYRi&8QLn`tc5^SQ9$uDTLW%8aV-G$@FAe~P(gru%mN$`0wpDxl>m4EK=%6_xc`#DJPlJCa$`U5ZnOR~&Oj zEu4umEI$}Ko+J>tbEP{Gw1b;(pqxNCK>oZfSHB-j)B6)F)2-q@Rkm4*AwriEb#)$^ zi>rx36q`>FjCVz&T}vKv_R)BBVTTODEhfG|Ao!G&tQqS1h+l&+U$4DwpzZ^ekjoP$ zZ1Y&h?Ff~`_GgquU4jUdGkB_!g=a{R+sndaiwY>vM&>KhL(?@NWvYdpfg1{VW6eDU zZHPQrY4|GRd1(6zJ#AkU0+FiV-(yQLfPwD_a~P6BI!Jn8&is)mjtm85iEY%qa+Xl5 zs%|f+!3xQ@k(wSuoufx-Gn}PdrDFDf_puI z4ETpKG-V7INz30+Xw9^A+048!#8JGyQ=rmnb;v42xdEcHS$~3Q{jNQYotI(#Y*~G46_IYyHj?xid_UP9$Cw?g*7+i zGjj$ekxA3)U?!7hwkA}HCcBUuHxJ2E#3@*?KGIH?-R-6%zrY~~`rv8_=j{xX*OHzl zz$h0o{8FhZGK_PyyNB+*bIgCIOodSf@uC8^RY0!J`z2It91J4@kdxikX>w0$`_Nuq zAMRtQ$CtTt*?SYV4#JW+7RtqW%vX($_qh68oiX;~qOBqF51t{0xHB}YqO=D%PicVL zU8uXI57ru2L1FigQ=9yypl8N@@8Xj)&$FI*l1;F9ZRL7*5=KL`mPrQh!hVdA!YR32 zBYAhI?Hwx8X%;<>vLP5=q=PtV_2Rn{Y&{H*2<5CUuU90P`^05t9;wSr9GLTzx8kKf zNc#d%hn&mDf}|W6jJG;ttp1{zqIaCUK_InX-x+J>&^bv2=EcN36nX=ltfWl=g$%o^ zrq9ZWCIyW*S2rs=q5Q<&a0QJTS$Pl%h3`87^^EZ)6_1`q?O#_fmRp3&X8}4YGvK8Jn*kUj zLS{njU9J}IZTYh;G9wW*cz?+?w%IlREvM!~;D!89Tnx|IJK(KnjHo4jB}9#mT$ve< zn4nVKA=7E6{86opBBNKcOARVOsDrz1;gDfbbs|ei+EO7$S{(Ez@u_+o-q3w9@oert zu7$5~*Vtz+U$AmOkt&W&(embN$uo+c(je|mia)6ul{A3hx+&F2V6rv+TuQTWze?H` z4fo5R@7<35!0p*!XRr-o&!D-9vz)8s^ME^2f$3kq{H(bt;o=Bop#S457l?+qaYLi3y=iqS@UC(Ck=xM@-X^%toP z4tgubULti3GLQ5nFPBtsh$c)d1Q>+fl*#pdYK}tkM)*6xz^v z(@rIv*QqmKT$uZlNw7yGwA!P!*t5AvNoFh0J(Ah5p%SlUDD-}0^yZpAXzaT8M0%EV!ZqVQvUWg6DwA7Lg}j+D$%Cdvi$X~#5VX@)s^(v{CT6P1w-x6OdG7VoFjs((~h%2{xPbTc@%Rp-?DF%%$x>!0=qX#nk0(k z?#?C{K~d|m5E{MwA7gSSS{@8^GCMfMBTEIu{6k%g>tQchjf>&oV=FM*T=$|$|NM9? z-JbPmntzU$IvQ;QIsYcHI?GyV#GgR?Cj1cwV7m+EfZc zbs*#p9>GV??`1)t^Y|X7)7Hh#rVr3C@CS$e1(INOopmwLc={VVUqq~z+NFLpBUx5< z5;mx2lIs@hib}*8z~(N@A>teTX3`9XLW2wq1@fanVZy`{7u0LET_0b^Hte|_C+)V4 z9HS;T1k3QyIf7-E7F?sMgg@Q_E@!C{C79H)d)uMMSK2^=+MUly4?S{QtL{|c<%ZTa zYRy2=+%{hzp&G#yQ3veKc3wTWH&feX-bu=Xd3TL0gOav8VSElz&IOK;L!p(wF}YmE zrk3e<;YZ(*+=scp-(J1e7#2|mJ?J?!9%RP_?TKSv%f25rshrO^lNkC6hEgJ{Su1Pg z-0j#cedH36%Nho``N<@PapkvtFp$|yW}dpRHmq2^vFcnHB@hS{_o4LwB+> zpB}>!+KqU1(4}4*B0?B%D^@4vQVCy7a>WmHDBAP6Sq5&TsB*G89YfEg&m$Bkmj1VI zWT1Vse#**1F+Gn#eXEc0j=;IWvtl(DbWAXC^VB&SxNBtz1$*=nQ5PJrLyUDtA-8Vh&`SXm-JICqxAW{I8;OUVbfN~&p zce?Z_i$zf1buim57QSY`zK4yl8qDJ&|2QKzRUYndQo4-`)AmmoPz_H|f{85cm?~m8 zR&N1X0I~9^_#p4U;JlU8DVG z`B9o7@Nsw#5@S#V@x>^5|bf5{rdD93KaGHR;^S0Mylg!&TP`CdNLS2 zR1YN_Eubb9BJjyj%QO!JJFEtT_n_}*o@Uso27#WAKUa;F^H2>#R zQEJaEq9OV922+b+QpJyF3FebjMTYzHKTS^ug=80yoK%B#Ky6#mSCb9cR$Aga)Ej@t zM2$rIb3*p<101RWPS}7G8tbqhQs9SS#U5%66Ao5AEF-E`>|Z7uzh$$ zf!0>=yKoj|7*P4iW;@KP^sGj8N7bXSwI=VkEdf0^9;hb22fX9_!vF;f=yaS|DU*Wy z5w4WX%E=zGTMJ~-l;HM3P8ZfZQcn-GRi{4;z20K+4sJAcM+Xk`9!T$qZFwUXlbr*G6$=z4GIU*Mp@(WJ~vR zP*)6*3LA%X&pgP4AFrZR_?jXZG~f?mJC*PcM zWQ(BJ#2yAC{Rjm32JdJ!mTR(DCu9w9@e&iYL<_7EHy?v69#z_F6X~xcu#xf;CDzQU zead72@VA`S_uFN@Mvr$j!vv9R&?k|Y6bP!qz_V9S;#~BIKKXs**kj1|YFra-g3-9= ztYXQ5Lfi>q9!>lk6lJsH-?nr#_|m%C{uBj4oA#zS2+=$&aly(5%MrhQHiU_bgspLJwv9CpkJ@_>|GQFZvvi8~;DQ_?;|#+EiFSgY0X zwEUAPspOTP%%0ogQXB~}@s{*WqEKOdy$BaxdKP_?kt%zRAQ|g^L>|AbXFqH-=&)q+ zx`qka?GsP_Lv}djBmeb)`hFGThm2npD2IG|I-Ztynt){11BP+()&J z8f!oDF+pz6iTvK;79Kc6eQ(sJ1owk(;UIq^4}Vpw~u;NzGA=#C$`Z6h!9S7GJO0xLq%R}AY3x@*J7xg`*u zqRvi#kS8U9XJd~HZ7Wk7fc}21P0@B~%m}r1+gc*)^g0;H(VlVt-9d4O-P0nU*s5kK zW^b+#K(kScgb+4SwBt+88lo%@*As`=k-65yA22`hxV8e8@-JYHC#2PnOAoNLySF$i zjH|6h3(vd}2Vn|V3z7+tOIp1DLnWfAhe%+;Da~I8?~YKl2Gkob@A+I5kDz_piR8t8 zm;?1BGWA?L2~7A$HF^!_k2QS~Bl_SH7%9D|sY?n7 zBkxHmQH%d8Y;!&+??TUqQ1DF{;^B4}2{C#}r_^Dc%C>#i2{BwPK>9PrhX$dOv62Y! zCz&M5L$%DKk6njyg`a0R(3#?h?gtqx}@?jo2*q)|Mwy->p;JT z_1$~faY0$BU+D|ld=I!@^5Otn%bC?BbP8;iOeeftaTQ1rJVXf3lF-T#BZ_nW2=&dE zdsYO1qkPUz=&xCF9zy?gpa2*lSfj1vkky&Gx1^v;^~zc%7|jG|D1>pmK`WT^*s> zBDim`HI-QQhH3$jhL}R$rp95Syq!;_3egh@O;d7-5EG9+p)5BJp5=NO=jq(f6d$`f z9QJ2Koa(TIl$?0;{t8vx)FqKM`R$00e2SJXz9=UVLh(s*Y5~<%{2CDQvlvgjWxb{g0B4wffikQ|6=zty_l(G@1A|sB%x~lzlv%ME5JuRsANCg( zWHU;Ct*3o{=8O!q?i^T5@}^$8t0BQ}67CSDL+Yq8tKv|QEZp3Mebua6!|Xp>cP2p; zQjS-e!`3KOXflQK@2$(ddoS1kz^dch6)Gp&AVWP|kFXW*SeUVlFexyjSAKTBiOxCJ z5vWVvKdwmt^{pO%HcV8VcIM2JU*wPKU`2qUwvDwB={;aK#qHjq1v$`8)xt_-opF>} zUit4bdfaoW_cQt=c<;(#fEZRUD6zC!h*7MB`#OY8<`rMwcB*Hi%))gLdXR_=SHsO~ zhz{kxQ336b)=4g<`t*nwAS1Y^ z=V#nAfLyEhn8cph0u3-N$cvpGT>%j+7+)(ODd!DQujMDe)h%rXAwFjpgRFbzhwUl@ zn0wTO)Lmh{1tV7uhDbwxdXQdh79v4Qp3^LDf?@KaL=OflsO?$9OPK(mZRErcmTf9) z83HSdCXxgBMNA5za~A!L*cP;LB@fc5&OoOcBIKS1Go-c|FNX56uhC2$1E$8vr3uI` zaT${5Wb|amr8GXpO~z7GGS?&{S^_yusM-+{lgNSv;^E1Rof_S(Bk+vy=e1tZfL=!k zg*AtEtkvQJ8LC12sl^CA1nfXkTIC;K<{7uR0=Y_5a3Yu#Mwom{@-4MlsBlLfiW@yD zh;W16IxU1ok*ITc=JN(VsBk6^jCWDAUE3yMeifc|O<-+n!jW*S+q*$FrhNYVQ@VLjzx#LXvzZ7?+>j z>qk`9xENn#-w*lRuucH_vH;7Sh;W zg@*(n{Cm$lvp+>+k&9%HCgE4gBRNF$w~Q#qjA@SiG6~<^-m-=H{>?Wphfb%<*xj$$ zK|IW(U+p31^ikQ{Y&QSQ_b^AtbSqp{^y?kY@{!JW*e?9mbVGpRR#a<3KNdE1@5$w4 zk-b1jA_Qt_Nh9e#8zEX=nu7(F;XZ*4>S<@3ez@!Zk5GATq$7!WVwC}cdDQu0#?0Ze z2hafAe3K6XT|sb2ZNBr$O!mWp%JQSxez^+lyMti8+JHO~z50Bx0Gix3MYZ|J8M)9ar-871o6@iR}P1XW^k~vS}!+sMRyu3Gc-*o zunmgDB<_g%r^IDm3wwXy#OLN;IJxBxCmq&e>#$6W2{_1+^9a901K<3dJpSWBmi0k0 zeWzNxCoA(PM4Jf5Frcn!ae8d-3$whlhUBi$jsO*J#PF_xlhKs)aHUtwOR%(LI4%_f zcZ%-$T;aB@2!6oe!5UnB(Brn>m1$HK$x9r?6uBU3Yv>bge#o={%1$`(T0ET{FZ$IP z0uk%Svi53}YYxs9^7YQaclw_Z>Wu0@RY0(z`%%a1`R!&swIFvv5rB&&!{K1m1DB`p z=|vLA`gy2TPl6;OL%WW=otkh@N$ol-^w>=-K;b{?}uKV%JGTrpa~p&`t) z;7H2Tf+0A!aCt5Qouc_b;Av|$y^vRDvuhN&rw5H3+{%c5S*V^{oPC!Jn2zbwHs$V) zC<9$;>BZG)0}q};#0fMo^v9Z^aHv?<3_})y?b7-Hjq6N3Bv$ri(}7)uJh7luJW(Iz z>e)~3{6gPHC>M95P1`w8#Da_Uk~4w_U?A}BnP^Be@p!Z-^%CXuuA(z6u!$1ftCsL- zpuT%R9rJvGS;(Z?c7XlCGAW_@}z?c)hj)<<~U?2`LR|# zaf}iPha}`8-3Ju_mP?0S41P>FudBj^pEK=jy||q3>a}k_ba2B_UcY4GkYhkbY7kj_ zFl)EbNa~8Q4n-yhi`yuFzT8(6zaK&gnCI@PkbZb15GQge!~S<@f)y6*`jj!-ZCmzi zaTaqHM(CC7&M7pGn+$$$u3PT+rYv33Yk)_P%X4jO*#ekfklTNJXd55(VOM=C7+R*m zP!6m5x04e4AHdK73WARn8h)C6{OMxxsw`KTY50sG2mNb20njGh?wbks(HNCO*;v9B z1HCzQCjUc|IjsAwM8Up~EtRThD1jh4e(#?=RC@qt6!o5QHSa2Cl5jPI!$`3KV4yH} zb;VB=r8qy8ah(?{R&MT^N)9F?x?av-KjfvT(~UncD}G3g_6ry} zbU{L3jR~?e=lmux!hAD++7;{ibpdR1{L@#ITa#KVM*WpIzeMb)p36iY+=OtdAy9V} z=}B2wTT`4miG@cN0~z>D+T&PSLArM#LV~O@BYK+W%L;`PD7<-Qu^ac&E2`#4j(vTD zCm?LLk?Bi!%pMI)Sw(+J@ZJt?eZ|{y&*PYgT&B0SxHitWHnqzRRVYyW)n^iM_BfIs zE^tCWa`%M0IweG9X2>fJiFaZiD8S{=4-7&6l%rIp0c1m&O{XJeX%e0_(~;YH+;1Ep zR7$9=>vVzXLbEv}=IE|>JwGXLm)#SlGoy)n!mC3SZ~`@^@r8FNBAZWGUeM=5mrg9t(U`Zddc_ zuxC~ROHohIC^3MPDT8u1rjdVeIf6FBit#3E+RV#lPdjzipNS-B$p0EuBvS3EGl9`1 zP1uF}E9W*4F-wQ?Wo&ata>eHNMxi@!fOIgWGnyN@RrxsMgs%;9etu z?^l+Lk!~h!ncDRI51E^_jBs4jPT5JIQp#!zukZ50z$`fi1@9n{+#86Ob1T11OyIsH zy#UNEg_t+e2$+2QONx;giv>y+yvwT@0vG);p;XM+(NZKuKMEf`2J4OR=D|X*5Dto` z-0bgNN0EdcrGemE2e9M%UGvFItKBJxhNOGdpo6hv#g10b0@A(5PQG^!U?c{P&vU@4 z?9i_LAIaQ_8Bq&!>9bau-l1J%!HFLYQ}cFT-=Q)5+#i3j`#PpgcCitV@S`_}&cYVF z!=UV>s=J+}Cj3+x2n0mQyKaI&*->H3f*wNCpyVooI)c_0(@N$fJ{2bpwSDl7Q}iG# zyjLyV2W{G|+DCD4n?A7!68GCx(pn@i!hzU*;<}fH3!HX8SuB%JGjB>B2+KQSE2}0n z1o0R7gT)ys@?s}aEv94DGl>NwHlc-)?weOjPnjUJCI~wgWQpl1Ndm$-sATI<#JOy? znsQ>MnU2Ef=cB`F>?MmQ0lor^{FX2iK4zs5g-_YF%I|JWt)K8o6eD5Dl7W>m z7Eo)-8k^hNKno)Fy|eyE3!N&&upoO6oD=Y$2P3XoIEP}jPzr3VR>fybEpIb*6%EJc+Bt?}G%6I?BNzFS1es0!q_*FWnd zaRGG$a-zG6s4LQpWGs=S1YMdN5cuSNRA7vM@RQ$+C4c<)7OTT=jQxT&GS@8oZq32I z77a~8pJ*@>%T$3I4-wS4Yza`d>OB6deCpKjjfHr*T1QPiU~`*nCq04=hHn3pr4lQ& z2D?kC4hAYynI6@BzJGL4&PX5(rBBUNvz$ka{&YiXckeLkrAA`>qwNTkIYzl^qIMqn z4i>bdAXUB-g11h9 zy3Wi>1Q1Iev$bsJ&Kve~gU;JcwPR&*OaWl~A@_O@KXX{iJp0L+6ZfnHZ|#304u`{9 zZHfoKPtgS7*CYIP>@f&rN7Q!>^pK)om^M%3+1BMF^ds+q;sTiaYl121tx+#h&Mwvg zD1$k{NORjl_#h5yi;PE1H0~Z2xGb4mK!E0p0FHrph| z`>M4;%09YRENjtm#msp_Y+0Oxt{G0lBIe&0Nob1llbd8?19j}IW~q71XrcpQXZSt) z1`VRL0!OMPCi~tk^uk6*F|Z2GU}vIUi{z+$^Yd0TT)7^SK-wv(Oss|Adg*E9nZmSD zUuO})G5|C{%fCY>V#1gqKFCeG3eJ$GL1q=90l_x|01`>>%8x3 zeB+>6eyGmcw;By9JJ1dY+2baT-xv4gze}&Xfpg|5mWE4zcY+H^4r@m{APakCS+@e; zSBYUKxkXe5=>?KAdR{0)s<4Jb+5zaDmcU-qtSuOK6-Dn$2(x}|&k=wojx&#PCH=Ks zQ0?#qc82Jem1U#Ttt#X0b-gxE+CLuv2yyJwp-b4 z2}LB-I@t6x0@`TK1zy5T0xnM!z_Y(ski;OrXS2ru&0TSXe=bBP;0`olHK|ulJqEe5 zf8+T-CzJXc)9ELcq0-J_v>kHz&x#guZ*L5!AWRC}^i~rbZs<=WUsXXtLR|O@Q7Dkk zs*40=wwQAkk>_2Ia%QI9Cj+(tPaQ*@5{gSg1@g9f*(KQ{{b zV^eJE0-faklC$Rwr!TqgpE8{ScjKstdIQw2Youcl<+Ir&$$H60@nI4wgE-RM5N{DH z7ugyfCuTtC!5#tbTgx!I{HCmdm!4u#O_B-CsP47W+i!25tRd$NmTMZC{Wd>hE3jxw z+Yk_HXZSb`t8DC~laZWM5AWk1!0;-oL6;p%=*KK;XuN)1nHDpoe&z6|SzuuD)%=b# z#c^^gDPY;4aCb}k!Hg`=C49)59ZYBy`jbsd*hqL=n* zR55>YLzd-CbE4<|KBnwk z@ia_|Ms>xhir&I1X6Dkz*XO0(2#cH zz!Gr?aaY=ao(~(A)vF#?cc<1xeZC1Yco)1p9W)~N7I_wK+*?3X)@mZe)M+aCGkSaV zkwl!+BI1P&aX~2j_!iUv`);uv+8VWf1AyAINj6$%cDQp!*{5ocJWJM~OR}Jz3cVxX zuknapavA-ehvItchzRQo(Mivf1jR(|najt(N zhTNldagvgY!0y+{`5Tr-D@>*OA3|8vC0Z401dFrmh<@5C8YqsF2{KeCTF8##bH_<=-W0O&ZeS#NtJ`< z!OlCJcWX>=NL1xi{V7Ea5bZSSEwIM7y+#tA@rA|$|t8xgJ$`T%`>-3=mc zA_llRjdE-s^hVPAzXqH%)L*YqQNh?Z{W{@xtN1^D0+pohp?o>YFW`pdz3x=N<*Y0x z!1sfcsHTF0^d-3uoJR4DDaE##z_3h~KepGOH)Y5(BZh$BRQd=+-O!%y@#;cxK}j6f zaiX9TI9zQKYCsu5!$;!AiMk9@p5JR&8nR~k`nxMb17A(^cDr4V0I}Ehz6s#_5&O>852hn=7xJD|MlX6A*l4E1+vkZ%M}99%arp|4o*0 zqA6L7`CS#f>w1ixTF;&Jvf_Ycwxg1RArrzG6c$ZgudormIAzyo&iijDAczv?Y0;u1 z-=?~FGeD?+BU;r!@afP2w)w)bgf`G%PSgn>pkQPZ z(<$DRMlw*IS2+Q;C8*9I81wrv7kt3=r}|5Y<7aO`0=UO28V1=22!TI$9Bg#KN;z6H!0($Hg zzd_6bDm#;0>6ysyQ(T}~Zj`OD*ZdXBE?%HyWM`w`Q7nc@hhT=U;g}ZebAUOpUR*@L z>8kwr*pVd^dBMUe0W48)tO%dWg<+27w0A$Ks*QX*97 z^YYa0+XQpuGUbPO4CDCE^h@;fTiP=03C+{5h7b0*Gf~OOqI_1+`hJ4RF;geHwyzBH!n^XPk>Lbgd z>kq5uKlholJPWaEOJH?4>rIm0fObw%{_-iYQl3abmZ>+OG^gsDcEVfEnn~X#2t>|& z{0+r=%=(#%;1Nt~BJHgsZJnLncO>^mEUerva_1+&kD51Kitae>dtXN-J z!Wuw9EVXHf;!yf5(rVM1zdAz+fnPJnRKLMRrF#&&vM0xSeDF=QDT@GmVjD90NG;^T z7h)o%^+PQas(XP2`-0jbuwEoKh+mAGasUWh)uam!9U5>D47tYH(I^5Bv5lzwm(w<3 zO0e1Lw3t|pv~WeG0Yi{q9YcTVa%4$F>tc--Fb^f8UEv=1qd<!LW*QXNeu?z-ENhqbHOtkO3g0wSWO+ zc1ef`yRtanb7(n#f%U?&ld&X=X(CgLJibF#R1|om5@f-%r|%;C)v%)Q6Z%CRFENja z(y)<{Z@p=g+HQ5+4p%GMWb(0j4oY0>jJ#~05C&!8Is#I?e{>G&gVl!-a}GAJ86j=n zF9^`Yc60zINJz-ueihMf0z%2bGM0|x6Vuqmn0v6YQ*CN#-YQm_r=FMz#?zqk25fQBt(Wz<*bZ7;kc}6+l2EOTT%N-rxZ+> zNqx3V%1An>3ThQtMPVMi}mseF0~r&*3tG~04ES2kd*{5-ts^Eo$iX-oZo`N{Wx z%=Q|Bb2f!(`MfXVbYl-&Qi{3>P?d(qBXo}lQ6n0!-}U<7k(K_LS+`a5Ec*&n{G~A8 zu1A#OvRt)-qqqE%RQ3rOR9gGlG>Z>LW*i5QdF^aknnF@1UopOk(17+eZxN_@vbDcZ zUn2SCN{$z&Qu_X^W(WThc z3mKG{U$qXR@xQ~F*WR`P$>rJxL)5~wEX$365k;@!3q=>0G_v~m!{#_n>shsE8Bs01 zPE=?LN%~9AjPD^MS6*@|Kbl9w%DlRX3GXh*~T*tNnz-l4{Tq_5Q-HfY#|TCEf{V)`BXP8iMF=seH`t+cicH80^CUi-Q1#>{a^%1ri%O+Qq`V{g2-JnKXt#@;%i`Y4^VmgI&*{c+HpS8XFQI}PU=j`3JZ4mF;9;~Qx=;}u zgptl@&p0B`?Ld=>T=mdPH0C+o>=Oj0zCv%H!KcrfBv`s$i1I}bTB??IP&7xXJemx& z4m-igURUK0@q6SVUG(+mpnRK*e?RL`GPX$fvDjSsj*iH!edTMYc{c zdMOhgW8W8cp|AvC6#%b{oLq#Dw`YIe4=l)RvDMZE9c*+nkR=@My!>yVY)-J*1<0&b zKp7Hq#yW7O55(T%T68TYU^v+y=7R-1HCKv8X{E=zQqyUH7f%h1la*m=5roT;iD1(E zDVN#>Y<3^H2q`)ebrE?!rvRG;;GXQULR97n7-5!jZ6$#t0;+Yi*F~8H7jmWqke-hp zTk9AGV43KVVrp`c=9SSDrAK9v1FKd9r^{jx{-_pOLKig%#_+>N1LoA4ye0&K)wP_VHi+T!ZBG?eg>cy7(kI@Tc0=f_w@fJ$U0k!9 zt3y4yz-OIG!Zu>|dV?Xr`rWKh{1o=&9N#H51*D*=!Z20h!t*aX!(ug5cxl z8^4~PBPyWST>K9ieG7HSA zPvt=!It`*T=5sD`_eDaTGQH+jm#Q#M;$EL)(%jXik^c!H>rNEl0dxkP)oJ*+*hxOO zgNXUsIU4!LP93hU%&{PPB?|WR6m4HKmBD=XW2;qVXa_ls6E=3knCEbGdX-a~<5C-`P&s>FQBVFA~~J65VJ&{Qx{= zIpe6@jt@MCTf=1yni^bPC*7!Qz8q67=u;i2qUMnK=QTid8!bY8HPMPhDG>lj3KB6A zfWg9gt(Zg ziKiagM&uBFXvQMLOFY?UG!?4!m*&5JLjIxqS^Q0@j|b6?TFxhq=iZR5wK?T@fnj8^ zdAUKRE!s9^J|!`(pJ@oLXGodR;4(r&gn*l4uJCs4k}UFBB$xBsXFLHh3|Xm4l?>uB zXiJ;)cc(`tSvLAVAx~p4ki=_E?}iKZY}`r`g@zJN%ku*qH9uidV)Ux{Ih!;asn;_v z`s&VRIb#7r{a7Kt+q3FhN8_|xp>Hk;WU)}XY9Thq)I~v5o&f0Pruqrh0xp10F zz28=IBB2t-DZO$dZsobm;i!;D_guH%O$C~pmp*!1Ddxi?oG{0RO9kCkag{0I*>+#A zcRHW@$8V!E{Bk@ZcxCZMw4(U%qrz&bY>jk4;Lji7tydB)xw^~)PJJ9+gU$&J&%W{D z8oEX{zOA6ovkPxbJ*N`z=Wn+I;iRN*z`NfNaDjqV252uQADO1F%S9w0hXI4W1DS~G z@uf)ouF`(c<8o_1p&c1(v2N;A-_m+aKD<^P7JnThbbXPFm(^QtfqL2DU%_iRLI;}p zp#;apD>QD^m{eTDB7ym@IY#C^GrNkdE#BX74*7XHoWL^DUR%#-wh@r(EU@y=s{2uZ z_V5r~W#xNI#qyDA*Aen}HOx2iw>IT`zMqYdF4|ioeH{5iN-)t zl0}k!x&?yK2g5=Sy#4}vO$k11unzRnAJl#sT>c|2{AySQFk41|BJ+NrD_b6q{MWq4 z(3gFwqGJ1x00_{b(?D;o?Db{zGNqeD@ky|`QUAlEJHNTU$3~ACm7>T8qcD8``s zpb$ZoIKVMpkH|JS9L1gLs_RUMy2-X}G|kK2bN7%(T|C+d$GW0K&qf|g11xPyb&%1R zS3E1W}BmIut51_LdXq`U7jwZu@5hK|toR{%XFcD#`O> zDFJHmv#J2-x+AmThGY-QoxEE6M_=xWBu4VOJ?^*)uzdGZ87s1k*~>f zStAOpv>?2+IIRSOLM^aPs#S9WbT*gPQ=_j6oF@Ozc1x7B@U)7{^THHd>`;PIyLdQ5 zga3>CBON&@KXq~Kr(xU@B9wKh3vqkNY|do3@9wMH9p*(zs=7htTW+!2^bD~{iay~x zlN>+&t`^*83e=I~Lw#wYc!f(AK0ld>+6i#57e%@uSPh#Jwb)4sUcXYcQf|Jy&c(a!WsNUQ&dqI&JM7;mX=H+n$| zLu*C2@JG%8v3|iMaT5F+q1;NEdnrpvJ>YXkTGQDOeM!9PN(0-TjInS+Ua?Aur9EKk zF)ZH2{+ApW1hOmA`*&!vuJJW%w9fDHMZxwD3}iw5C6!f_j{&7d=o&e~XbN!JhT_o| zlMzLgbiv2t4W*KG%nJk;O^bHd64h?Oc=whq*k&PKEO!k;6-5g%eVRy4zpVh?9szJ5D$MCE*pmKBxDtTX=>$Ps+K*W%E$^ZgRLM zyvi%bEJ*Zyh>t}6B}cC$>C3vh8(UrGW-G0YS`FjCsKJSW_hqt$TiMO`I$|Z?4_=K& zz_?Z%pY8Kzb@MM{+6pqsn>PJHMQ9yIwx3X@%D@u#$2nEW8<*hcrcth*Nj>%dg)?lj#mk~j*+C6C04lF))sG!8s9@O%CeR3Xs?inSZ!e~nVp#>Uz#2FxRRRm%F z1n*?`gM+5T1;+~_K}2J}ZCXn;ySGQi{nG}SkTF0^_RvBKDj8{%&-iSm>iiep;qxj% zb*)r5r=iNz)ArV+LZ@kZntzN%ZRX}dmWg+7$2P))6uw)MlWA>rP+uU`_=L2H73wQR z>s8A^yoQKTnLe-n178@R(mHz^+EZd*6YVBCMxtjzYC7rU{{(MgeKvxgpu-H*XcFSx z2JlC}EJ|ysxpO{$U@k|r-YL$eLQ{Dz@C^ia$q@W+m&Wv8 zC%SjVo%hh9n_McJiasf7Lq(+2gceA|zs5=F(lQnzHQ14gQg(UTWcOQQq6COlb?1@P z?c0BhwS{Ktadx1m`(lxm7fpIkH65F{Kos_gn<)|NbD8||ckUMlf8x0uVd%8^9u9QD zYqrEYqlJBjPNNdzdL%t9j}{$Uuyw6zZ z@R5cnP^O7*7Ww(Zsga5a`&5yd7ShBO9)45fOr3uD`4KV+XQdXWH*eL>W;xx!7{!2R zMU$()SWqubdAOHfKb)^Iqe1e6a^?Vi5stHft;FQp&wja1Yr@B>yqR^0LY!7RghQ0z=`ndzJ~NoxP`7hz3w zPp4o!>HYv+!dP1|g(F~KRyD`8QIvO5Cp!JaiW8_$N(CdJ#)q>TfBwwq`YQ^wikd?D zSUtgX2+c7KRhjilI0>S_&Qddn*;S_M%v%LJBumy7gjg?{1%Bzh&pxD^jXjINyK)N@ z)03cVb+Ns(t%X2YR}bw-`_i$VqgZQnSh3)k^lJlc7Z9D3>LRYP_!Brs+D|1${S&dU zJ(=QOVpd8U;BViWyi4@8I)>z5mPt(=2=s(Xw+Bl}sIqPmQ&Df%E%-S8g_;!p5Pdkj ziUiPor7)G&Oa-lLWZJ_QZO#A@6l#I_2{_Q0tAQCd1evX&8@*3_rzU$ot`S(A66RvY zDiF)6vd`Gh>BJ*QP#=#q#sz$sKE3=ud1VyXhfmHzhT>)o!z$ZJWYFi-_8ZFjlz_BVJN1XR6mw{xFZ?rK6n*{g)t)T}* zmxu^}Pqf*J-o~jEY-Z{$o3bApP+iMjm*t-!KRRh(0h%a_f8$Pl;*R>hnhv%f zHv-vAW>Qm} zL6+Lqd|Li8>Tb80F2QhKfmCra(FCR^BK`caaYV;_he*VVgx6ll{b)mSgb2_vx0qo2 zh(&JuQ*-Gm%G!afxu7_ji)H5l*UOq=A#gJ??UsRSdg{o=qYAgu$5a_p#r2>KM@Cr? z03V%{=15EqbGK5oI!<#32*dkDJH|EJ{MBPv$S`9ToWg^^-Lt3ZTP+}i9EWp80lNC= zoAE&QmSt~ZY{WyMq zD@o(v_DmB+d!OiAO%b4{VB3KAx5J{Btgw-wHS>bAas{N#^go1ozHs#f+~K!9uobA- zG^|gm0V3h1iP#8=q1Vl{Ym1m@)TF^}8 zLWIcgHgiH6c}gk{a>cC*(#Ny5n*!%Ts+o*newI$T6$8hE`M2`|l~S%O2_mLk7h=p( zG3-^D;OZK4VINsY-r#~8_pEwGhqm;CVl+gOmD@Dv3UVLz_tkJ2M| zG?1&d3Hq>3MVRAQ$Fv1Ow6ZI0-mq+zlR}Vd%5%U4{;lM)5iB4dH~pTb zyd-PhHHFA~R!a0-mEbn)JSV>IfA5LW zh@_evM-A$;dgj3ZtLGxeexRmEf*?u0ov^8Rh;6I}=exb)d!xf4kC>jzRzFX^t3|Zq z6Qm%J1$zsZfVg-|&KlS&pR|O5PXferFEOedjY_>QKq1Gg@CPBMmhw8^yK4-cT@%a2 zSikmgXJNGSm@?CeL>-BLAE_!12n)#22Oe%edXp5O&nem}$TfCT#KiF&%>xV=(4>I| zKm4KNVjT%Mhx06OOV3lcwfgK8V|mXOVe%xy*52WYnP=5M~t!(nsO2g-bfaE3P2-os+pnH_9f%zwats7xopHq{{HZOW@r z5<>k!JfR<|w;@$ez$(&M0m1tVI}>kwbD&hyIz<3hJ^9e*%xf^{2DS^}eX{FDBN$I$ zlp@PHcqv~kTq$z-Sa&f7hC#%na+YbiJGJa3V^QeniF4Tzxf&VLbr=)QF11QNKX6%% z#1g%G;w@9G$0Gg`%BCW?va6xf>~sriNg>%;M#W84TJ^zEBDE2-J-E)dyS=kmw<|ZU zV9t6WH#zH>CjG|dq})Yg8MXs|MVXppC7Xo;vo>k7CuPPBYx%(hunp)1;Ut!;mvXv4 z{AlfrN&X}#?fF$-09Qrg961q-?bIzSl{Tdt)Tme0COY+u9t7i$!%buUmFs$QU~ab) zcwt3NId{$Hy4w5Gw3kdkk*MYkzHc1yvjXxuS|hsL%7-?97|BqFB0mJ$11Mp1C`u!M zYVn4PPPEoxgKyoXXS5RFrR@cYyQ{O`BznU$kFAHFWl7Z%jTtG%75G$ePE+a>_l&ci zEa@Pf#fo{nMUD@QYPRTpTpSpTq^g|cHeTlw`7w)pm#S~ z%OqILDlX>Zw|uTL;-~6Pfk!<5dy7#MD=G_M)N)S7^Ic_a<3sfhZ_9QtiH838ij~!9 zkjk0sg+;y)#6IDj#rGpm0(knZ6~Z2d4IuWG2@mATHnm#~u;ONE5`>k&-*g31*YiXr zTBA73zxNNBhWUM?$4}1=F;n?&wK`BboaGZQiH&{g@VXGZTC&np@d)Q!#3#7rPfqLG z+Q(IxXbPr5=c$b`S#eo=)=3u&Z>_;Yj1XY#xeU&`fKr#o3;Gp1x0>*2_-LRwJzT}8 zj*RrRcX6R5Fp_+m`1bM_$=MfFypBg6BeMH?6QP9gIt5rNK*v1I(47T=3&XCs;R&hq zr$4Vrb>*+ZOT7n)E?6f?Q^Ak6d@?Nxc^;&Dwg=Z9xj8O?o>k~W=y|4Dpj)<7`@{5$ z1Wh_Hui^Xd$oAsysxZR}6Z9XcT3ye<-4@&UkD-3odG0vB?b8BQjHF z5OFFM6|Bk&!<(huem-oD2!m+rHufaCl~;ftLSO!YDMn`Bf!3M@CrD>T4D@1lTyN8y z@31*I3=9r^wBd(I}kpk2b!kMaCa#vY*H z1E*eBQ3ce$mln_`P`mKF^Lr|qBWQl`3eeb4jESMwZ9Lm5c} zIa6K5vo&1oQz=yod3u_?(iEonX#fWJA1|LS9+bMJErS{nl)}b&1;cA8J_=(k9X=$j zKOjKfCX8Bs1jsfMIlBh(z@51ZZ`T4!-HS;$6EHewH=%AxU*us5)JjuOLfUyNeGL#N z1E$#LEs?X0$UOMd+QjWFWx3CB$^r!(EgsIwl<-I1Dv01%i-5X@N0(j_D$j>M;bKt@ zm+Ni9N(}(dnwF&gC}BChl-Wq2-a>5}!r}g=e&F9khIfhJwDg-A=buIXJ6FPj1Sqy( z-BmVhu?{H*j>Y}C#I(q- zZw9=NJmof=vS3qTi6~D-Lizp$$dUk91CO-h?oCmgc_0<(B|U?_pC4!>br;9f*&^< zV7w}gy;R@&XGFmY1}jS&RzhS{d}8`&Qbwa(j=CMN1=KZXSrSESs_py@_>To!$=e2; z^=A4)`)CO0U^@PwwgVopAA z)b=>l(0W41N{beLIUXs3t>};Mi5oeMmJaB7FQZ!?nIGU!M7WuZj)=Y#R%wOEOHgV+ zCUrCrSCezcmqnWA*pp{R3w9Ihb+^VvyqjL_r1>sxWm=Pi&YMd1q&`?Mtb;HeGe*_N zec3U9j|?J#8t{9a<7cgu;lT~Fw*W^NI$A)1R-~*V zQ(1}9Y^!PGj_t9+JFI5!S(Au~lZrXUBGB^NC)@OX%+%an%*7g5y@nHR+<*GH}HtrkVujz$jtf>$`PjRi#3Yf-Y2CmsKLbNitRfZf7nDwF5j<(Ta4Yh8}&- zOyTl1Y>6(i>!`k;+sTb_7odHZ#gq+${R_R3j(%E#a9~F|`HoWj$YiqBIDA&=lsbEC zf2Ova1e4{w@k-)fR1!{IP5V_Cq@L%bU**eae3`Mt+68_GUG$eFe6|*?^>$`#GJ+n$ zV2{?hSu6aaG--2c_GIqUgcFrJZKzvYDsvg5uH@w1>f3f%Q-51WSC8q389bBh*4))j&fLi+>7evB(pQ=<0`+@O?nYH~u z?b1*V<{s@9OubjxkRku>ZOA>Q?KK0b2KY#8EvMBGHhgebMxB`0W2z!%eqlr_4U^#P z#$CR#_B8gb87k^Q)KGcrBBfCzhu<t*|g-*&d_Y(w$&$duJtw1fm+v8iZiU{%IK#1EC&s)SN@S$^PU<;$NZMuyx2)&zHn7Uv=be zyu2XsmrAS!n5XeX$pHXmoOMtRH~6rxjf2w6)YHjj`p2#SBX@vEHey{@oxWV@maq-$ zB%@yQ4}5&t6;y%B5|+bZ$?EhNi^h6V-rmt>*-%FIGxofhJl9i zctMFQxEM1&l}b|ejtyz#Af=p#U^GdWgES=9!*1nQ#M}=BQOIdfRS1W;gm?T)-8qP7 zN|m|9?!m_`UTmXF3Hhy49PvqVGoV;`K+BkppIYz%06rT(4Gz&YHc{Z#`Op>mF5YJds&!_R6YgC#t(4z5 z4o@WzKR&?JEi7K5nv8)(RjcADoUYv|ityVj87_Oj%2*L}%)_W^T3@8M7!Z!>^_O2b zL@Bg!x^RI74@7M4#J|ZYw zgB=g3ALXlJy4Oa)r_{b&(Q)sQ7oZmG9-kT5tpg%XwI zYIEcf)KQ$aEoI_$vyrms(Qy>zZmjTB30iOWWza?r3Mk0PD3PncB8C0Mxf)Zs1z-`3 zMB+I(8Coeb)@sXurUb1uS6U>DuJ9h?8tvGyNIpcfCt#am2R3_C=Dx-n;;SZvmpHr^ zJWU%lXIheEuxJx|LxkJN0y-l{spOwvfe?o$?%gEMco=*CR4{cOiAgn$ezTO8iK`ci z-Sn3#%lf9YrE=I2a|Ghy|A?KLs4$102f|PEjG-QU*C)a%HTy_gEyyNG<%1#KYtB0w8K>K>lVC}l*ef@NCcfMq#!4G%jnwwRC3Se zjh8{Q`Cl?5#bxIYr^^?20}pf9z$~r!Wu!5*mV5l~?d2q{CupnVDkeWj>Iv!oHhm#v zU7>n@Iq)vFsxZz?$D#P@fXW6N&h%TL3ppv<4N58ld^TTZXh54y#Y@krynlwQn5Cu7 z$BA^9sXOrvbw!@eEct{qIZMD-2xC~-ug`+iv>p8r4Y@p^qP|fn%3T(ZWt`3(&O8vf zGNT$&00Q0}Pfn0|n)|7+@`JQ_bw&`H8SQ(}(RtXk4d>QJ>INlE5;}>l8=IrjO|hmftLl;0iFE$T!c>wt}Rq!&IH^NsDh2K4WF9 zHlM90LTc9sbebQr{!K6du$%?AT`Hh3aOLU}wGFl0Fj+1|^IPqFB2mzTbH#?J&)nBcULh(OCA%MO|Q6%Wh#8;$Rq77ZGvT0$y-3C4^fux64R#=tmJkK$iF(plU)%9O%kxfM?5 zu#Fk>VJ=~lSu5qlKYJawsu7)>wkG=5JY$`GFaju|$5OZ)h9L|WLH0PYSqsZBc#d1c zPIHBlrt=%?U?LeLB<9w1(l?q~@*EIbWvz8P&pIa*ju31`9wF)xFuuGXjf}sWgoL7B z=;~@;z|m%6ZaO~v0Q~H_i&ncA zg@hibwK|H27>4RHx4hp9Vuv||;XA~oQBsgZe7&)7Hs4eIllY5L!d<^&Lh?T_L$t+d zd~o}#|L(fiyy<$dEIedH;X$>-K1#X`zLmmg=~Rl83L-R2UC*3mCVd(_pmFA3H_cBk z2)~OX2LQ0AK0k#4>tqIQ6OyZyaH=f>YkPXvYL=GwQQ*dQ@S>DAQO!_iaZlkcXtfq} z#mql%d5uVqbHQB}L62NYKu@Djm+*St;$pJIf2-k=S=;{Gqq$u=>tKw;Ax!Pa8PHaR z%MZ@;t~KUYr*pyAROH$8YU}l>d_;5SKo#T~D?Dhy9rPmG6&$4LFgwcH4C zu|0y~`IIV#$M!CiYz{pK&EE4&VZ)j@4I<$W?UE6d?MZr51*_j)U@;rq6{a0L@V|?q zM?K-mIDw_>%{>k&$dc+O72*d4Hjx$7X#8WB+-ixkHJ38E5jccU)oo*&v2@vR0BT;Z z$>Vqpp*i_bI%82f{uw*8WrRf`BO4j4l^S*4Hy@8LikH+SzVn6!G+G2@as4qW+E6S`Vi;xjSYv#TKz;rT7QzMKk3$a=*VUw4gLgqPv)(IyHYsf4p;qF ztO97n`;poR5=k6<2uk!oZRo4aM`OA^sGa(Q6;}s@dJRnZxH*R>q*{SKH5)wx*h7r= zE6cZuz9f!amVInkYBFTL{_S$rfrYWHX>EXaXwCIn`2@GZO8z)7 ze;Ceaf0$(1cJ&4C^_)b(39f|s7f7N|X9V&eP(0vI`qOx!k-%ye+~u?pu47D zXdyR{b1ZS)q}%Yr0tr5cW2OQbZ<=h4k*$ ze5AT1lx}~vno(BSWjv``!|<3XX7TZK_&XRQbK+ev!D9hZ*fX%BcezL%Gp1y_V56N>in5$6VRCX{~9=m&m)uO)KdhOO7*?={}J80-FV zMCj$AVlj2D9k|1ZjiIDBA%1d+A?!nLa?VkMW$uWs3mZ<(lbP_a5c59A%mkFV))^0S z=}zXmD9w8KDlC9xqulkVpi0_Vo~{BB_~YKGr;UdCPk?#N_ni^JNS4-A>vEOKPk)|S z)h3XaTj5@Sr^8aVb;sD4DXVr9gQYKnxsX(E*kNHXos4^pHwSKu74}c&1IE-(j@Mp< zHtk|AApC;oHrq)4hs(7Li;Yf*lPG2n|E?r0y-WZvnN{x-yBc7ol)K9KrMC#e?0AI| z-Y6*YR`5hwCcD?k6%l%Vo^_t+_QQ2z6AsufNOewt+CNNVaU17#HfC#7x z1CmrBVzkRb{_I!1BUP?mgc*X+pgfDxV1RkD^%E3_ym-*0MCib%r$dglBu}}|-)00B zB^Cg&vLjKhW6#~@@5&)OdxO%ycsN;m)O9%TS`hKn?G4!^}J;-HX+MOw_H7* zv{F<@=iNMx3!hMIwQkt41g&_L(f^ruW3REmCd~!*dpbosqlg9Go=gs z=G$&6=x7C2M_4FG6G;aPmX}1GhlV|q^N+MaTM1$u`e3&U-CO7d7JlW2Yz^8++0vF- zXPJ=EcgxO(a^KF8+*zLbH>xV70*83=zV{UW zC%%$JuI06t-5w3OrGhsFA15R;Gy;5P>fyooYOv*kM#L}@^rHjj*_iBI zW6}w`mF;x4sf#zl=8K>L1vR`-_gUv9hHthvElB3B79>7Lx6MFc7uja&9$gt+X|8E% z3);jf7>H#F6J{M2?|LSu3YrRn4Bqk-ZJF=s;=M^Z@La0d=3MM|(ED2z%XR>tTGt{1F^9E1+ z)^UkXe45Mh`Y>!M{848;rocmE48YHCQsQQpPa*TI z3OCzY9w@f$vA{mLR2AYk{eH09Tn!0AkAH8G9~1!#m?R;=C$HNjBU8q(f#}>H`PGWw zDmlEj!QdcidG+OR5OG1sLd=+w1ZKulFs`N)LFv~Dmtwr6_UcwsZRF@07!oLs?fR_pSh`i4C_iap&?F~Qu8ZafuGX3Nh& z2fIAf#y`rlnltzx3fczrEmR?mp4Pi#=>4hDKMM#nVno?fn4mV@k=?I` zIQ}#*gAV12a6Y1mr(6%A7zHBzH>J+6(#?LmL8*fK?Zy9pkKfI>%0yFLIIF-psn zl7OAIx)FZkaF*>e{*JwTb%amP{r~zp&x<|1KBqS`3O9r!S#LhFr8UfRydG&W4K!%X zf1^dLtIdo;8KCA~r}1tp-EF@&T+_Sen3|vJyuT0%j4+%4jtjqiTzif{s}-`4P^>${ z^=Ps3t0hdj-3XKg&n5~7UAjTVeAm(jmJSi5VqRx9^_$Bh^wPXyuheswB5RT2saEW- z{LkGOv!}wC6~rCiHcCHsqPoJontdrOwFslo3&?CdIJ|GP#Hc|(uati4Af=!8Fd zaYFL#A-P!q44*us35mV429sT3xjohm0=p9Jg&~HIS4Mn8I z!?7elSL6M$UzGuG(|1E5*UBAQ3R9M6q076!d?0q1C@V~Ewvo8{Cw}XW#Mc}qaGj^U#iwuiH~|&SuNttV z-cWr3N$7Ha&~tz3G!>)BUWJbkw~O<@Y*PQtxfr>5#1H^Vysjyxeb##fjAF~@D~U5s z;tcztVz=8aVe%}2>4b3 zI{&1TTfqC&`PQl+4n#Im%1Aa+hpd0V83iO=X2iq7>uZPrd^laW4eVOP#kzZum97c6 zk8+;M@M33=#td|rH%77zwoZ{?dTfJCmO(ALPbeB~%bWB#)T0CHhi0>s$@SgPJ$I@v zVAGXIu+2~y1M|P-mmL5_K)SzDihm8O{G=Yb+{6TC*Ff|!mRfM33j2N@uC%er8R*pF zhdN!8{sMMZtZB+|f>~ZGCF=YtMNC>QnnZz;U>(j>Vj4*fvU=z3DB$>WQfoGhnxeqr z3L>|0*gGcGUXKiVV}$KX0!@-JjSMWO8OnrVG^Wv*EV7L<**{SF< zDZk_tIom1|rwJTb;4*}YhEm9WJySB{Z6*2^fz54Yca z3SyT?yo`bDHQOs4Uy_oJ!w*X&8FKCsAg2YXCvCR%In*`{%iR$!K13<_XE;^f|8she@8cU%ku=!8uZA*4QMdTFt81-YgnI` zg4wDl#S*2Zon%ZS)X(^uOuETSw$JcGls>A+OiT>+GYd1FmOH?N*EvvRY6*PRY-moF zwv>$=aITbQmZ@Ltj9y z%fMbdi^vrmq2~2tj7^v%opHZrk|M1b4)wh1TbiNxtQ!#ln_P14yAvVrIQ*l~1kZJW z?_tXiT@bPZj`6=he}uien{ zPhN=cBs&T^5^Z10+}w^vxUt2sY=F2|Wy>oVb=l02eadIhbs4?rOs#YwuL=mVZY2=T zVW+iMZ8m-e9XqkH7EN-`JN%Sm-M_3r^LF0~^k5^$)cNb~+b6BjkGTsA12oI>EBwCQ zi6}Zib+sREf^*UQC75;|4{0_uq!Noh+|Q4$?UGjG5>hG);w&FU>~EH%*7s-McaMgL zLK5ASGku5Zm{9*pISK@x5)?%PGAA1TN6DHzR;F{}x6*Qu;!?YrqdRPWhjXmG$;3y@ z(Ck}?_9MFZT$guSBf~+cvsU|&MebIX)dqWIbHVCxOgR3Fm@2e`o17P`6Z6GTLaoWa zEAL4^wQr5^<8{szg{SvGGKIEEU?C61IQ;HJF9I{bq9M_H0gpt^Gb%C`I~*#J>SY{d zq*1hvMj%_SxfKm<b=?%7Z%t{t=$fg`f<|H+=>|K?dJl}DROIQaC_Z$r2xMjAQ zYdwSPC;&s;ynTtc9%e*kI{c`AR0R9jwwsB462ReDfGFlSv?OMIxsI+|vhdi6`7$Fv zRf}Ju5u*WG^k*c33Y$)lW#wOcJ|}>8&mN!X z%3;eCa_PyYT;{V-2#($cDtfb?lamGi`h~Yj^^PThrGrXCpj{!kCFs>yQ@>GFdZ;pQ z=60mA)bJy=9|W`pl+h6&WY+wmcMVvT_ac|E6^`{9O}1a8AKQGITdav#gDPMd*Pb)2 zcw^PFv{4X*bqg?pF_9(#g;NP3~;0<)Pu06k&Jt-!h)_~?*5`Mp&sx544BX6P9T zVz1ShLrFTx2CJ~7mBF0p(P_Cq;AYb!5#b?YoxIodqXySGo(ar}fc89Qm!Sy%Iz~9x zTo|X6zkZGZ%`^+%vb#P4fPmogGXtZbU3%2m<&0E-VSM*|Cc~ugJFvh3C#x=*+iG^y zdknZFHGB4Cw%9I)XU^sCr^a$s`5jroUphzAspJJ&UR3~)guKsC3SuZ%XFP60y9B#hiso{Rn6?_TylVvS`UV}A{enc zkgt@OJjN{ja@Ik}Dp(DKH=`0~boWTgq&JSH(l~CH-roH?@!@YMrWvp{Ya6fFY@+fi zoaJ8rRp;QDtcy5h(`wsms6TpmY~o&?Li!KCPX9*+#bv)=Y{_u5_WGJ4vLgHe+IYbDFK&EFerQ}goS4Js8k&z#-luaX_^ zPpq+k_lf#YqsHB#x6u|ZV10^V*@Iir>0lVp9y*c6$A#lnA%PL#Kh7U8tx(Gx>_l<_^<$rE=GlErE{EO zdqbpL$;q5xUbmC&2G2Jr5ebIh6rH!iXQMV+~*yk-kDCC zm^H)1?nx&ubr|6(Sj4L|dW=Xza#c;Tal&`vEylu^$M0U!U%rwb--?p7{sa#_ka0!| z)V8c(SkZemsY$Q!kkQ*)j|7t}B!d{A1T)}2$gU@VtHdow!s7`; zyUk_tHlz`r69UJE=%v%-@!YqiOYYt{f~V}H89jt?zusD;aD=iKa8@HSX8ny>N1qgp zFYDy{52xzg}hIP5lcu=*loTtrTU;t;7U;Ul%tq z>xRzfUi|38_I$UAB^_77_-GArec;lSm3iv^*c8WVA`0l8f=}UwDAXsYZN_+KhC^KY zW;R#_L}Ojq{hx&7%Y|79y!g?x41tG$j{6Z-xxY6P*H^C!a3x1&h=ibv89q_mWRO`V zfy4SxhCvnovpOpu5K0oLG@GtEpho0%obV*tQce~cLI>i?PDR&*iN9SLhKWiysM%FoQ7;#=9 zQP5T&3R))yzlc4&YqnlYHaOB`=ZpEp+`s5i=KX)-uUcPPygk^RJvu6EdfQ z0YfH0DVOaygeyXK^yNR$uguxjsrv^^=_3oX#|`y?!0yhnzZUSz#^aG+D{fe}MjP2& zX7ffo$J7qwzo?QP_vb4UthSHbilfo8oR%?tXn%ctF@e;vJGTlE5;I9VRr1#XU0@T@ zA||RIBFNgB`Fo-&%Iyz;M^;V}R*=+X3a-P_%eY&Wk5gbLgLaZlX-qui5f9)X_CR+1 zN`Kd`mKwd>B4z`57YU#p?-%6t7p?Q*ObjaC0=gI1f@H2skGPfD<;{E z#~rQCPx6$1)!j(APb#Ctbg_o>xH9d`LXLuG*I-joY#|!joaC^g?CAOjW%K4{h1R-c zlX2I`?TnQF__^rUuJTaoaGcj*;fYxZF^E}tgo+31?U-XtklMy(@w`?w;N^swnsxup zf0ianKP-!#JKJ_b9Cl}0q|}kH4IZpX1}Kzl4p`VoI$l(>4TpqBH3j&bBBE~ae;<>0 zGU;?&tlO?Y12N3U+&N@O1+s06;SJ4eC4Oh2rSHHcd& zc~+Q)5oh%z_NK4R$C}WSegHi0z=6S3dX9n!#9z~P%lO;lo(i#(blpUXy$=8D!i?ra z-{?_lmQq^qr!)}SKZ!vs>Tp$^k4f)jOc}j5!~PR9zuNi;J^8#r8}Bf;tSD6ZJ5aWI zC)25>LHb?KY58~NLvSUQ zi4`%6x||Hu9mj39E6;-x{qC#K3%HelZggEg zvnx00M-P~Z-}@U@Ed?e26XKnGYfckNQMtM&a}@_|9p9_v3neodZTw$sTmmO~QyE2z z&NJT&p$xvyOJV@Y8-#6yE2jw??x<74G)VIcoU@v>guRgMi9tUCzrn5#fINY5F#L27 zScQKxot6F&?ca0{O^_H&PEk`&X{9Z%H(W98LLh`n!)^5Qe)36YseJdcDNQ0En!?-f zKIb3hvxMCaCdLBC{T~Uzr)-S=EJdi6kph2$E{k_#?qL4XujoBJQTknKD!T&>x*#Q( z9?xlpH{&k!T#ZMOK0Dp!hYMrso>*F13fV_?yF50_3@t~$`^@ea_KxDKa^-(bi#8(r z@#$JhHZMNo&l*6XsR5SPd0?eAe4tK^dijG}vd%{B;oxpO8ilL%A2jVwlyFNRA#)Wr z-hQbHiA!OixYr8kLns8R$*Ad0Cj+VlXUvSr#+SbXID`Bj3bQIll=Zs{_SLixsYYv$ z_ZaG?S-ZHLe70yHe!8CV@3I;q|ARo^{C1$ND5E=mh4PeE5RS)lD=SC@rdt+`z8xp8 zT-$nvgR|22i_Jze4&|39E}U@ms~B>37LibIN#Gtlpq(lR9W;KCAaW{bdrB_YB9W*B z_NYo5WVufO@3Il!u$UZ)#q|4_GKdpz;>({)D$iqW$3|Oyh_n8xV^}|@3-!4)_U=^= zZ5Rvtwiz>bQ1Fj}rgH9KPL$b^0DV_k5cEg@w~NB1wVoT;n&JT)fm}4x0m0 z2hF`r{EDp48+$rYpQM;)`}VAVxz?f%%w4F}s=g1-CuXy7Ps)&C8f@!*tM=yah?m|R z4Th+k**M;erXuuT-j^T^OyxRL)s${08Hu&x`#^qV#=lpdv-Qw1fy|3;jq0^$V<))M z=pkJdhV?28{#lVYCC=m0O=2TmU#-$(XJd5x_+N3f$EB4ve@kT+AFL3$t@mGd=QqS) z0XD3D`-UqgzLqI)yPI0f6&HPnV-Kh6W-HdtJEl>ka3pxn9E!)k0{6eo5^3qEW};tW zB)9WBkRoXyH423zlL7TBJ2QjZll}s~2sV+xi9KqZ1Y&<=9n@2Vc^hYHd?kM7u$sCXrpF0!NVNa}(A~5t(I5F(@xNNx5fz!vT9Ld+I`E##1OtPcN ziwB)l3u>~Eg$;$K>9Ji_DPE$_*r;G`GXUm@(}hf2cy-C|LD^7j7!Rn|h>Wq@*#ka} zVw_h{#TPhOB1`*f_H6yC1AXWjM7QwZ%p9Xgv@TrzLCzS1^5Deu;kA3QO5r;u4g!(HXcV z3O9wB512M#edubwU~{5Be&BO`{3+FHHXUaWlH0i&7Gho!p3o-H_qW%91R@;J>RWGO zVONlh0nt@vr6^VQI-g2p8U*pQH_pBhi z9Bj18J;cB3mf! zB2NkRfPwu%u62G)yEjY<%_j&2!ifm#mrkdm7qhdX7I3f!+`9{_tdUaqNL{p@0^fSk zTg7!<*csL;c&ZRk(&9Eg4niJw0ho@6^&I?SAMm|-JXlD+k&3o~q+n^g5s28O4j>rxty|wwo{la? zucu|8)Nh5Zl@LZHid3%+&_OM|{LRRy}qY6wZE1(@v@i&gBa7j+!!5?kGXbduXA6=_eUhBnH z%ZTju9+DhzpU#q?!YMOaUpi%Tl#%ckFrm56WCaYZesy2q&L>&-t+Kx{fKygFCba-v z#QoHf$$B1y{Fqgb2PXSeH=Spm>3Q?$EoXVtKmR0EuiZi}!Mu7n<9B*wK*`X!5Lagn zcy@yr+8oRVv}a4YJ-`6?ctgCBlZN3$ z*Uvr(9^QR-xAsMk@H_Z0ZJo>;fPC3>ATOyLi zY#pbz5oVS+E1cPj&L{$4XIhWA2zj7d&&+JWxZbNe5%>d#xb?c;u!%dq1_qlF1Ze&yJ-*&EU1Fd02;baR2FXmJct+ z#VJKffGJi|=HTGpnf0lte=Rk+RPUE^@wwX>(j<0hCFc#XLDCl3-6LTA6}yI}(&inA zM)0Igg=U#UGErSoAPPjd>#a`54E^*A@qEo@02l_{j<(wwDw%gW?6IGFcjUrEL{kiJ zVgA0*qfiXPT=UVH|BMH?_jEUPfNzt-jOiaGa z)pd%sPhTx~R()0|dy|D$#xN90H^6!ld*tbS`61*H!$2ZMBy9T1F+*>gzRBqh3}+0! z5i>lR;br0!>?S3M!@-UFV|{h)&XLdb&3{yUnO9!?umiXU!uf)JFP?;H$OqJUD zn;xD;MqfGucd>f#QvTP!DOD4nXe6F%gXPNTF zlw$2Z9x_|fue{lj6`l_E#=5SFa3{gF%;y>q7aZYySRe7g*p6V7+y~C*iYhJEXG4E6 zA>aGXA0N(PFY;6?@xVmtVpPS;b0u}!xNA!&cK;AriU2vD{PNU(Z%iA16&OC9j0rO< z5%l;KWkankH%I2+60S9%W}HZ)@!8)>qWPb$K?otD|2-urnG=0(?lov2L`L+v^6oOI z1N27z$YVK!Cd(QH+pe$s&*`TLae_@AeQsa;7!v~k=!RyXF$Zdv0aehi+Uu|YwBuMk z*FtDmX>Iq?7gd4g4Ae5JB{NBARY6VLUWbz4jY3Dw={9|6?WbWWmpXGdz<9Od!O}g0V8LU+{(T`5i`y{%HI9`ct9tj?!gM&JG&iP8o9WC%P3YG~t>eNfdM3f`MMjRg3 zuZlZ>4C2^^Zwzv~6DMP;&2OELKpVadj;zw$Wt!&3oa-SWclKrrg&=f=XH@r3n`>?A z=jPfpJuJFuk{|hEaTaWW-{T9iC#=gyr}YI{TiwNNT`vHE-N2hnlIvH8b?-j0bhZxU zj`7RQV~sY1%A`5xt~bP65nYRshk)kY)lAmayw*)QkXU~B;w*>H(kC|7i}CY+F2}H- z!rmhDvk(2d5x?VY)5mlvMbBUwkz*VIqjU!kOM)T{!oMv z-@2}JARC`Og3$q7%@ zXm~gh2&I_TAGCzRDbriP0@a0MUu!VPzss>X2#4c>n|()`GsxbA7meE*uabwG`$R$h z#Bp2Mbx#HrT~oG_{*4B8USG`m$!N^@cIK3{6=;6#XPYq#&Uj~zie;C!6S3vNky_u* z9=`{_{HAfUW{RFhF~jONQoxb7u7FkQgg}wXSNEOb`u|yw^1i)oR^uUIb`v zJ-NqOldxIcOn`l#%n45sdYCRL6;S-^gzlBZMrQwCAvB~ zx^s=Ny03!RTz7WAb@V00aiS&liFAW_66Vn5xa!MqbWogpWs4bJaMmR)FY6I=+^G5l zOzssCdqP&=tcB<{3oJ-)A(O#X?TiB5G)D#>ncN0Jx>Bh{0tAhKb*Y1|rRvkQLlz>S zHn>3+8P`L-#?80PHlx0P*(xYi$7b4&EU^_z*2pW+LPso5qj!exM^%8SxofBdR4e5; z&UNhpAP4+$x#E<#_cS2)-ES00v*%+ne;x2mB3ED@&QLBOyF1Kh(Kx%rn+l^Iqv)Y!&s6vm)#fH|1^ zp+-ukuV|j52_6Y|nP5@~$hb%xk%4xFV1G5(l`GcpK3{iST~=g;e8q8 zYzW~y(MbCpQX{z{!fMdHA1FeymQ2aJ49_5#VXz(yS|Yn`@bE)EAqn#X+m1t>z_f)LXh4@oAZfvZW|`y)nEUvOu5tp^wW3`~@d^D~p)Cob-lQ%YB!0PUVA^1SW0gf9(O2VvLW^_Q zuYlliH84Xuzf)!mnDg5-70YFMO5X)%wQy6I<+I`E0ZH`(BxzKG=>ZK(>f*;#yf2d* zPm1!(r}bEfS7*IsAKFh0s!EL#WTV4CRg60(5m+kk{_@mux|hb0k0{9?3hoBQAI~RE zfrLUTJNVN3Y@KzX4R6;o-?_1TD-FUoG`f>3e1yIksYJF$TBRC+$YM5q>Dz1%Kr3#^ zL&A`w@L#q)5@sg`bK$HkP5NH*U?^RSYuw;o*WPp6f4eIr(@|5lChzJ-4QdRm;K-Ap zPJaGHJ)KO5**ro_EE2|8ZO!d}2!{5rvIYB&zp2j!;_v6S@be^c3W_S0dfbKn5n3bp z_hAgJR#b~vF99)DItM!5Y!%A&88qMMu-NS^NQpLMo<^%e!->FWtXss)0E#^nkhS3T zA$JyoFM!|m=vm4~A%ym2`^%+8tVpk-DUcSocIXfApl*gM?t7PgN9~6>%N@f!&)6>~ zpHWOk5^?Lb8=Q1YY$pAe*OyrM8*CA-k}r+^UyUdDnDSW9R1Cj7a@2Fa$eDkKK~xFA zVJ&Xfbs`W6%M(X^1_*qM<xE^rSGM6xJ<^h#U@Vn8DxS}JJ`Jjo^4sxMUnxCDCDqRNjx3XTLUSg1u`m13*b zBxjonD*iG&x~@8C+b$x>%c|z@y7lT;OH&^>=;9W@lEA4Of!ZfFPFy!haDUlMt)EvV zfk2Gn%8urRazx515wv3d%-p8*N@)*HS z{p>31I^4x*ht=$YQ^{_58?|l*V z!F`8GFD)Wu6lGhn2a{OYKQ+fL4y_Vfo}gJIsK^Q4#4gy>pZuB(BcTIW(E+!J&G7_S z4)m2LtkJrGO6m@*B~^#c4CAU3h?%R|`f-E;e^b+HSN!`5958?Oh_{Ct=#8|7Q)TmWL5`2D28_pe(0N#5D_~*wkOe^X^>b+mL9+*=*atDT; zT--LYPQoNnS1cvHa^3W~@iSiVQay58Q*9N9`R~)JG`D2b2NytbcH^Y_nOWaQaH;h- zEklnzSZ@+I*1jc@+-j4EwTCuPs*O`-O_G1JKF~+w6pq4}BXm1nkwy{WGXlMbuq@!Y zSpnK=yFp$Svi$Eb9zM$)u8kdux}1OOS3A&On>}*v5L=D@u6y6EfBY(pcO3J*(2(o< zgUU~O75_Ny*wTlx+Y88=L!*_rw-LhH0o}qx8S&ifC!U~ZJ;IaR9~d{r2l-&4!jSHR zOpAo6@1L>I`s7%#9Y6G|6EsEFhZ)$WUU=#cnnkSS>XjzrE|B@L5kXJZ=QY1L@*v7Y zfJ7Pa-tPQD^W;T=WydaaP#Xp)q)`AAa_GV0Y*#>%b-^z4JDoBWs3_`=RH^7(=rgs5 z+djB>m3gmKEmB?D7r+_eyUTSK)*XnwgjJ*^Z7?)+7(;)ZC`;n$t@;536}(0{`Ed;{ z{Zs8BoQg{E^1wSy38e%KaP>dFQc2ETpdecQD3;@HZ5VX{qReVni+EPTD|_`kWIxOe zEXjS+IL_g*{!Di`De7z!S!la`#JllCK;6k4C$Qx3kZF|3^g}MXf_T9eAW{1Zkdy%4 zEDrRgDuGn?fN8^pX}deWw)udL<~|-Z7lj$vrlY$HFe+|_A8E(OS&@&#jT#|YJTgW z-MnBlUwVt^9)pNuC=|BZ7c5UlEis@VsWZS5z*;T$pVs;Tm7Q}6G^Q8Ok5wWa-qy#L zpx9!-jv|A{)?6o;(_t;hFf?&#pV@Wa0!e?*=&{XT_T&nDt(3>G4zom8h;7mBOxo)I z3(AjiW?Iv0-@z>w(puK8$Y!Re(bMbv7PS*fD89c*T+=hAaAOCxl9|GNEw@-=EtO&O znKFFsv@CSGV{)yA4))%-jfnSwrbTVAidVRIKhzRArX0eXJSr*uUiUf0^EaeNd@cb; z$%76D`K;58oa*_Avh~Xl6$`9{zz`KK&ScZjKuwM4CLMxkfi28##0JFrGCfMC zf-NqsImWnY$KJ?%;uU*W$t`Q+v5tfSH}O5yP`bV=XKMc&b{g9`DZI1F*IrLSdp-9= zpz=Lz&z|YBj&e0(AuCDuqY91ngN*^{tzd~!lczN)MgK|FQ%gma;w{&{%=*{ z_3jH2B{myNI6*f6^9GlV@9Wzn7e&8rW6Q$IpJI0#rvV)?eC}-)f($=N^UDNhDMPpp z@|!-JtDQ{_CnX>WMM8cfq@^49U3RUmRT`2!?km@ZY{dX?`KkQKO}yWNupt4_aYyya_f-fM*hF4yO%U`mY{){3UgxY%gsX$u_fo7 zVDOu%$$5keEtvz$8WvmqP5|4ae?s0@)^Fqa(?g*igdOdF&%uxM01l(a4_GvXDB^0Vu@57M&$Cd^Mmp|FO%H94F06 z4t0&Hx6l*C5{Sp&P>xoF@H^GXAp^8BY=#8%7a7!P` z;0iF5<&WauRHl}U-zkkR%Qze+H~NkAI(A8zS;9^`2m17|Qul*OaS{Cc&g%-@>1Dfc z*;5TekydI@!?W~LUDAM6Uszyb`c|+Y`T_K|K?XdqZd#v8>$@8$Ba!IS+OUqrhL*iE zf1|&f;r4UOoRZQaZ)pNC7D*bt(JygfJwzvj+_ydz+*9umm#f zy$6q7_c|c_w}VdYFewg0=72x8?WN` z4Wfool5_!n(@DVbu-5mg89s3$C`dN*F%B&cUu)c$??ZRv@^g(C$AD=%-^KP#jmLZs;dsLBvH zJqzaT&p^6w+m{hpI3N#Nq5VrmSia;P2Ix;aV0+HVS?vI|M8mY2{YFM`cfB_eF~<@#XKl`srwGnh!g-jZ@6Dli9vcEF5bX1)v{VDmi<8pMHFCpoGSE$L9_NzCaO zD(cXM0fy6|}QL-aCmoX}r~_vHSYG&sGk<(O4MWYnPg}^CrB}KK*g!>yy-5-@t}C+tE`z z7ii^?WDi)S@`;f6p*+zSEjko<<~>FZFw+Be9BMXt!Hn3aJ;1?A(GI}z;f z3-%}J6E#IBCMPu|IIsxhUw9NE_p1Tkrd?^z-4J1whcE>0#F64Y^~ezBwDbL&5vO`v z7J?d528o=v_pUG}@|#%|JWiU;8i>Ow?}Q*v8BAoW?fM|9BHNV;ad6p7yUP&X3)Qz7 ztfxqsx}C4Cr9Z(s2^v!77GWM!RPtH4Mn7HG zOzi{6_wIJgpH$VEZ{j}PJ{l~|-j*RYDh`Ok+ZjDGcSzO6Iz2M*2;2KPZ68vrcd9vpxazZ_mz94}k)@eC= z=XDPc`f87>CjuiMktug}H=V^d$wVd0AD=^L`-ws%CH{Zi=%5h&SyQqO&HNQH=J0Z5Uqvz; z2NbrEK^c_clB3UretgGDFz_81__T$%U4>rYMoDQss3R%DdC#>at}O`pX%e${CisOi zs_n(fgIfaPr8t?pk0-ZvD30yA!U#<--xUE4Kdb=g%vf5?$J;7pd0 zy`!T1A4b@72IbGqW!$v~8lZO$n3)f{Vhgl%sNk&q&PO`E6vr@Qc+LDzC*>A^5*1$( z(*BHJQM*FteiPbAPezOoH_$cy3w1PMfhODemfwn6#=q^C9lY+kpiAG1bv^$%=njiR zL*`*rfqW;HWB#D)oMMLR2~LL@g9uY$CI-9^=A)14$|c=;8Z%!pV>`e<$NJ(pHV#JQUNB^-KD58jCtzGa|Kf)Rcm1 zGA335qsU=X(>xD?v64|-Z3u5Q$z_TuF%f+W%EHiiMvp!uF1|~?fnW^=qT!RS3WL88 zv-pez0wNtDCm(*-QI(4KGpZ?BMr-(?;5r3y=O<81dqmHoT+i}L_KoWE%5ETGF0fTa zEA;oU??|Qm8DI3(qjgg8DSNpfvinpzq<2|?zn0>^wKt(vPF|vE>=l&LLECz^GTt5z zsGD(zvp`%QW26td=pqu>yF0iS&4a$)FYujkZ(6-fr{J&Y3G<|$OnB8r0{6i!C-Y7=@yT7hwWO zt;o+HitYcFV_MeR%8Y5H3h_O9&S7vmD98_{D&S=@`tRz64j-_Z6XR7)Om9b=Xbu!e zIixG66UqsRC?biZ>o*P5iP`MGhIU2e|Ci3LR~5LzSfolwPtE{EL1(=p{~ZW$dRAHt z+4@LTm-|QWN?Yh(EZ2my49*rZ#xnlzo^6>bL3+h_!h+Pmkd&)U*{ZK-j%WdT}!g^zovfQMhA>~nfXbiMNU|j|50=kkx z%HQBg)|C>IOeNlZ!^nGXze}Ea%2VAUalOCJzhoh8=P$ncdMjz3+0Bp&Tl~~lUq~I; z`JiE}++FmjL+y@F<+C9_pCNgarOk~_eJX~m4#SqX6?0amvjyO{z!d^UIcCVf=IuTN zTEz}(LSifPPUE$ie9>s98CY*ZGdAX4KZ6_((<@_WO(t^Ma`?S&Sd$sM(ntP>`423V z`p}$OA-1oz zqb$!;0rGB>?0&jxW`M;tBS)Q}g@=9^N?`I+^K3FYAXlnUwA}BIUoU?pOCNF?TMpPL zwV>L#40d@2_Decs;#@i4HSxNb5Q3>&k;=m>jY=8otCNA0;%h@$bFC)VtxiFvD$n@m zgiP_qI7mp%_*YPaSR5syh=2qWhh}YQ=6ctD(ytIdDn@W()N#BH?l5~%PV;?pu}Z_( zTt`!s#KmZ$<{=R)Zf9AbVTf|AALljPeu2ED?(9AS{E!Ll|26Wn{}l~YjRUj5g2eqc zRaX=Xo#Ok}LSRI9s(x14wAeNv?Jz1<`B27*d1HvHU*^A(a82!f)7)N_gWJIu;_5pT zwuxSJRv&|lE_cDHa&DmcbOMc%T}!pN+lJ5DC&pq&@w)47*k}2)jjM-p`jXVcehN&1JR%(_BsuWZKu4zglEC!btWsa`?VP1p~?%f1Npawh&au6tN}Z!R;1k{bX@ zS<;97aY`E1?vMW{+pQ>E{9x42!xO*9Tj)?4te0e1&6(AwQHH>{C$x zY?{hMBwP)V)gC`=T=7abGzL^o`@LBV+GX7HNw%l(O(eEkL!&w(;|?~0p z3wK_t;WJMYY~@X1+>A+j+;>ugUo=0Jii(sQ7i$C5bJ(I!k$Z#bcB54V24ZOLslgVY zuJN2=GYX~*^7361(GBbu2x@%9h*++#QUknm?;V}U*s$}%%ma56%<9XFZbY}Ew}|~Z z_i#RVESRMB-|Hwi*Uef)eDj5{d1Sqr7m+>-l#SYOI~(Ei4n`0R`1p@X#Uzh2XO}tg znB{_aRJcJj5578<%05$c%ouCSh7gltW^|bXD&U2dz)b%wUzIZ8gvOVx^QQap;m8K! zEk+bbK94%UW^sofGz8^4sZ?7xS3K1#E1gv0XMr5+nbpqX>4Wx6cs^e@0lt$u_+$Fr z1ritY@S#UYXS-*uTw$Xx{KE%1MK8qcsfGPxk>36|Tm=V%SQCAf$72YIm^mX-y`V}A zPSLcXgB}U`z`!Vsj&hU3SVNDoWn$1`{uRq>lprp4G67tXE)|hs&)MI@+w*M9r6XUB z{mJUJ-J#F*qS~N^e*T#d`ei1UI&OP z?xrfOK{p;P7zSa&oN|`V%RT)%qA62^HyGF+uuaxIpz$YdF4V6r`qj=k>PKC|ey_Hv z>!rt7)r%~m=a+CJSiSU-ZA&qN@U91W%%65pt)GW`FHheSOgU`m;)y_xXGBCzFZ-}R zZ#Ajn(udC5t+ahFw0b*0x@qe5^ZD6ar3mRDruQe{bO%UjjiLndT<8VKFVVKx8Jc}s z*v-v$<)k8x{@n17cjqQ*j)*$z%~t-$Qx$WgeeyRxf{x#aya1Kawg411$~Lbjk=)Yd zQ5%oAMZztvDCCpxhOPwc*l`>U=5C(Cn+(r*71+0z#Yu0b661_C_MdxgOSZ}Ckin^m z>YNgU$y64L!}HBR6eIQGi=n%G3<^|JFq2)ts@-eKU42nQioEox>b=#bhk+~@oqaoc z@=(2ZTD1AGTZ7l|Xt0Lx5rXDA)@+Y5Kqc25peLbFW2BxkeWxgL}aFA@G^Fo|s{v`PQeQCd}!9*JMf zltG5E_`ReCc!bKt8Mw^v6poK`Kc%-#<*&Ha6U&fRqbWe?Z6HOXz@p~+$QMU&``chC z$ipd%iKEr=z~6QM+{v#`Hh(M39o?w{Wb>1bg;}V+3XYA*V!t`=o?~F|b1%XXFZm+O zCyW`yhvg1qkiFl4gBaYe+)!pcW$IT%xTz_NUFatG=lcV+cILh_4oo8_yQZQ{XT;7J zChs}S90_V|OV42ASCpdi+M{~piEkzr<$OCb5v3w#BR?{AhKnA1SR4mw?Na}Fa}Z1D zJ^vN;H>?;#NHogS@&iO)9oe8!DBRmeek?mVnDEztg1VxOHC#BL1P_-nP*I83koF3U0=gB}K)JQ?}I30ARx&IXT}CMMn>BKGzl7Ht#U?7IAUT z4*2LC-U6I=!}?kl1HEK7=Q9&ipxz+K$qzea>C!B7+K?{GTHG9*D^2&zTwgZd8&Om2k6=93%y)DZQ&zDGktjPEy;HrMurST zo~qbnJvRe0B&$n0{t5&#zBL3MiI3CJ1JV9+OFvy2O#R;Dh$qxQ#0 z!Y=d0^7N?qVLZ>tU+z?KziuhOw@J$&n{Gf|;M35#4P)XB30geiXd{kx>^%P*@I28U zye8fW%mY{7#PcjXi?1>1=P13RiP0{^HcQ_Ku$o2z1o+J&M`)fNDzt+7&N)vSGg!O)YWNzZ(~Z(puJ6;bFTqwo~&WLNy*2o%Rt!Y4uK2)f{zV6RJOWtDO< zDxKI*d#F>QVZnAOHRK;rmsqhI@7{tBI5lkkFHxst@)Lx&eJ8jU`7m&;Uw#oos=p@_}u*YR~RlB>^@s z#eEr*9UeD{g>t(#AuSt{G5y8vF$tAoGOalhHdy9Y`<3ApnFRJXm!kE~%7kYTv=VsDB~n7ds2 zxL4|rOl&xM#OE+jzX6&pOj4h!ST#^E>>V}1FpC3pJGX$SJ#f89$~2QEs@F6_7~H%J zv&?@iereQfl2$KU2da4ExQiAV)dZ%GQWl4HuL2q9*j~6Ss>p09vClg;OYwVXUo9uX zh;ES|88T#MBxxt_;aNgS>0pZcukcsEmh?icc5EykMvuup)4wBF`F^xVM`o?=;JoeC z_Cd^P5JlW_Ht+-=`uVq<#VBPOG&fDz#L_ z#X4@jd3Kldt8dA3=MR{dM5-B3c3GfW2ooc=rzJ<7-XQ|6JWUKA=fJRFq0BbZ7V(Fj zn;%h?b7hbRwOYeO0i}B$>p&&Pr7|L+2MN*)#S>cW7?&jQ_$IvTg=w9{$t?}lG z)0xNT7!7;Q3MtA=q|l<7d483-J$3os(1Iksir!`eGSD(LaL6btI6%^G+6V{_f*(W>L`}$K;fy zRLI7{D_U6_Xo%Ns8>b-nCpoHXT&h;JZ>_Z?sRmdO=~T#a&5#Z z&p}dmP7@ew^z`F?WNTBP3{QZb9@KUYqjgtFZ%pI3`sowMNF35P2D%nB&NC`V>gMC+ zRRe;aC**Xi#_68iubCivRM^IIGT*#~$PFQUs|bn&Q><7)e=@uQE0ZKK&1~ zzS7pGv!Z=tZgRW}YEVw!oD-|_aNy5CJFh1CU5t#U7r20QA*npj(Cs5PPX#sH6@cT$ z&Y}4c~6av4$obH zOJdS47wqqyD8ooDA0mV$@WF%^g+o2owXIK;^sk6V;g}Ddt6glerlFnR^Hy$<&5`-o zxWb>kRE*j+De7Uz3q0N%ne(m5K|8Q1dZK{MQHlh-?2tQbZ&ME>b<2-rDwW8Te}tv- zu_ia_09#)j#<3?V4TT{uCUo=8*LVN2XR4qru{^i0SQEasf$%|yCKUzYs|bmyvW<_r z4y)axk6ow?N~`se8OP#@P1J_}BZ{ukau2qfA1x+NUUCn+xvEV@>gGzP8YQxv8|T{z zZ{>jt)lls>6;a>m+e7>clELJ`n!vuP>tWf_H4dhf=sPqw>3TGu7<{@?jS)a@wX|cB zP|3(WMJD=824lz5!(w-nORFF-hFuWug{|nhLW~$hjNQpDxS(*jz4ZKvYmHHrB zf`2xbpDO%ne_1xOn&I0v6}%NT5q>rPCRLhYReK#&X(u5P>bz%s!)s2yNU<}~6%12| zyJUnRg&C2s_jYF85AjVS3HGV{eRtWIubj9t58D`WnLQ@OWwapD?$OG zPOVBW(AIB04l)vKqqRM!_j}_L4-;|^vV}_F&CeB$umbNULl264B1VY_$4V9D9USOi zFNfXNd=^s+EiDFjLNn&+m@yb1N~wVnYVC6PGQPsHLU;y~@yf-xkHTK}6g9>5N+|0d zr$P;4r!hikB{-)dW|vy5wToX2l zse@?SQ*r_8_cpoYpK|-mJ3Kt2CBJjlw#iF|yb$IJd*!eye1hGV9%9#{?wg^uu%2=> z5qLKUCM#%r{D(@{6Rl>u-J}qd9QRhVrW&6?PPDsr3G>Mji(2A%vAB)iK;k<1iBzI? zQf^I^t4uXCzdHI{jxGaMg!?Qo=9zZY7Ao0VRRLH#wM9qJ9_ZsCdTAmnZL^V8@l|K~ z>z-w+JvpQRA8l)0Th+ zptnv|D}i9UKegoGg?xZe3{vackFxtNkyI4|@0jcCkUr+;uNn@ZiX!4Q#PasNZdUkfiVmdRD>AS2n3}QBSN7o-mGAZRSA8amOu5r{2wr<5fawRKESoLGewS2<*CrqRS}APUM7$FBzwE`t3YnK}=bvkss{^$#Hqg)3 z9T=cK4<9{qMoZ$_t%Gwd!?V4~s0z8scWy^KqV z==d<=d@qVXZ`oQV%>nzG_a4p5YakL_ak0G}5)jfgD@{@JW6HQSr%lZ@$^D0crAb5j zT}f>s)vGuq;}wP9CKrF{gHC|*QTmAp zn8;PXsx`@1)D$*n{4c9N0NPxF0kF#*d^g&^IfEEhzK71qam32E9k#h2n9e`}YGpRg z-Bk~eqxwK0a^R?{7+_viS|bWPcN0o6X`&i^N>Dzlc^}_q5tiMWG7B2nocCXfU}M}a zTW#zdJORp|N%o z5xL)Rai|8XVn)RiA+2V~7Bx_axj3q{N{Gt}@K@}`+T_HR$rRB8DCLX*otz;HaR|Hc^UJ;}3t#(B8?^d<`)tk_2GS&B4z7;T{3uUjDjkNUg; zn7Dj;WHCOUbVa^T(caP*!HQL5obPTfP`kwa7T5~B-{5?A95@svWh_jS2<`(>RmnsQ z;$qkBQm85HJ$CDg&Aj2uQUsxrP8+13~XNEKm1qyy8JhyY~6EG3+^l0_!D%Jhu*u zThEC8#2w+`)~ixiYmBHG=T7#7Z5QGcc(!2!&i{gNT~6cO^A!m8|8-I$ehE1ELV;vQCORnW9_fu0Vn&x~u3_AONMo=$Nq; z@^s|xSTF*|+30g5PE2rAe*Oq6If7D~cTnhMrl2fwNZ0^`Ire^2bciu%#jB=sd<)cl z#@b5y{#sm((neG=r2Xz)=pecB9fId-BN{Rq1-m@7t$CW+#& zy~gv$o;S^Sy-$}l8bgIv2)^Z#(Y`3yAYeOb)8?4e5n*eCid0#saLPk!|a5$#CwnpvmIa*343iyETNv#?dSjc4} zb03q?eAAhbVVeHRg2%5U3L+IL6@Un)fbyOJbcJo`;%Y~FmT(Dx-2E%m(l5J;V7Xd`s=}kS0{+-{w6?=4>#>Pw{P+b+!UVl= zn&RsZUVNugd%hx9K5KK}j$dcj86HHT8|$l+sM|x^u8MG516K)>DHT5a%KnuPmIm@b zoJ8-DhrRN9JQ8wyBoF@)5u$7~KPznxMT_|I+^mXR_PxOrI0V_F@LlsF?;rbG2D8%O zMCz#|r*1dUg)Lk7`C9&>ui5fFp!$i^#_wxN;?H;U4&5E z1TzzQqcibcM!Mn6pQ>)FV!gN2PP;Ifck*2;ko}88CzN1k@$L`=PkFWD;G3$CGeJs8 zRXT;1z^KmSJnbX2KoR`6rwbYlXsn$? z{m~sw;>EI2(2^lI1q&s$7_p2VBD$}7a=Luk%2{EZagx#h(gnopf_jCL&G476m^FYZ z^QlkOE3`H2M*QGC3^eM?KQP1uw8z%JA>LvSXjJGjsQI-!cTeOJN0E7N+|;qoD^zdM zGez^u`m(q{#HzvxLOK|!LSUNin8&xG3p3xk4GeZWiUL~w+E8dmkxx@fN@NRs8; zAvM9Rx`ExHGf|$%+*%B;V{)XmNGE1C8ycoUab8cvE*3>My~Ad>a5gcZjCNs)=HZm& zy*yv#O=ymk;f-j&HrdZQqH1;^(D5nd=6f&Lki}8S{~ZLrFQ-1EYAkQg=S+0T^}l~~ zh3LS6vI6+^{Auy-avIzD6dNFi5|u?jV+vnT!(x>jQ>;`QDtz^HHMnPGYq_ZN(vJj{ zzK-j@Hv8ImCoX|4FNu44FEMjhC@zGOo|S73IWbrbS@=YxqcA`aE|B1%B_Py^NOV-- zF7z{sC(tJeoF z`;+F~m=Mg=Y~Fsf zw%+3^(l^~H)6)Z_P9}4xp%BNQh<=F0#K{^no}JhpwXU3QwO* zZC@rE!%QW4bh#;MC+w)6K!YgMhJuwG#s2Vb*QyB*$eONE59c1&Q$>`hqR@GnCTfm+;~Sbh?Kj|g!> zDz<1idbJa`6)YQ4Jp-EIm4f+4u3;fsBe{o=%8>dnljrM!yK_IAR;-eG+}{#&)1Y7x zKgPWuK?ZEr{4Rb#u$5}PJrp@j=mDe#d<96>X3iLnCR|!{Ltg`wmMK6%|3Ly1X-L%j zEljyzTZ%@gT#0QQ_C$9WemiJ-Z$RPJE+6?yCMrFrHZ9Zh^#(*vz>&BY^ zCJqvqx|owCIdj{BhTC#i3igAYr!tet08_nQRPggQ6z-ihk+`!zz_ycd#0?Q~uL(H$dO(H|O7B(iS`h7B&rb~?Oy~S&MSaY1vktS!y)IYIiw}6=^|3$r9{45k( z3cXAo5gpaP5Zl3skwG!E(O+utv2MU1w;gHoV>de;8X8JmV4kUW@*=k;CI0IDfAHYa zZdMYW0u^(^$*H0Bz8={IOfq?LxeR1=92z(I`62w)db2dPL-~>uNxZ zgpv&VaF(>q`gNmtwuyr96e3(`o^9qnm$3~P5v71h5d(RJCNpMjwHJze+fjh8f%W!l zQi_}QeMf;e9k2H0PIZ3PO>h5{; z?n8TZWAamI56b z3pCzAkHFmm6CMJz#&?cU2fcvkpR6p+A8Y(6~n1Pp&RI68`aCEi!fN@ zsJk)so&;v%{+nmVtgq;rwC#~>#}$YE;w%N5&s>p~`|F4~1w0s8hQ@Q@5e8%`|0ILS zM3thZW5cN4j4h(5^0F?V^2J)9HAQmy{mS&SAi?-;709r1Y~KK%)YVCG0AHAN>mz`O za0fvhC@oOkAM(Nd(&mq;=wq30AJbXIVm{JyN&Cz)eb2)w0VZWx0javF2tSW7j_CcL z_E>HJOLI6PYu9oj*pQ2)tPZlPTVfjzw#pR;*eJfH3Bfsi>_c=;XT4eNzMylZFdKU( zJcqM%NLIeR(T!q1Uup~Ik-fu&a-kX-HRHMX*Eour$+8^dZwJnQ05Yc~ENMd}afhT| ztNvXom8vRFkfXsAT9yU{_zWda*5nq9w!WGFRF;9^TV~?~H!nCbefrhG5LIx1oo-JK zZMPPR!o2=54ZFzs(s3}bvS{S&ARl&F|5Uw=7>&`HDLm6-fQc&JSH;H1907ay=c0!YA#S9f(fHh#MNQZk7M_odNy(C$VY&djh!iJ(Gls_cw@ZIbXZeF{gD z8}!01$$+0pe zM#9`J{nMAqD$OWKgI#3}XWyc8jBsg^AQVFG00f9n@{RC+($iEEnO-A!V}T@>T-=Sr zR{ruB63~h|acpXL1RbhobPnnTbpMf?g+Y7&prHtEhM>tZB5WjQ)Ype|n`l<&lqi(3 z5AX)4$9%5)()bmh19(m74s_9(<*&a#I*G+THeNCwi|(yc-|`xtv5**}?0sm*?|Ntd zoFiFnsE>z;)^;~Tezk`H?lsHeU{~ieBI+%v-*)U-2)tY@O%a~HVeK{N3bnb>al}8= zi}<~#$s2Tr(iXCevaqgO)KO~%7fzlFlTcnycH4859K2_q_ z`bQHXYip;HHzM~I!H6PvD8ibTqvDGxeD(3bb%05zo>KxQ+TgLKt6)F>+%8kO@Us&F0E)Fd=FkxQvUkaCAwy1)}r-n0lK zVc546h2jwu0|#F{4jll8mmi1hXIZDzRlzW8*NtU;F74qb`JcAo$j8iCCbg;od~xSd zwSn?~PuU*Gz0Z1ee^=P&P*@amY`x8;J3GOuk?te+Vt-x62=k~lICGLI(q5IAX7n-T zNw;YEGqD^RfA&A=GW^;G*t|GLda692LwausNbHpuOaIsm?FBEafs&-F0jglV8xKu` zVd{W#a>@MqQnxd^4?;7IiBFe@=JnOwkR&6A0FQTuv1rf(h5f@~x^z1jl{zKz5iXii1p2VwP*sO$oVd`b3fSJ48d58_=}lxsXXD7Vpe zrup!Gcb~dNPJ1=wmFokGA4n}Fnv;+np#b7i;^Hm_39D@Mf61NvKqFSCFpnB5jz5Hn z^QS8d0gmjCFHuDluEWqT_g%g_>XwLHm3&ydpU$6w_?rC_+U9*1sPA23DS~&gPUC+0 zx&!|5pgx+o_&OIjXg{}mDV9lE_Ei?~0cP4qLGz3~j)pzo7-Ph*@;Z zc)FaqLQ|iM5=dtXWv-2iBgoG43yfqqu%;G{;J^tYTQi#${t4{5Zg|$#U>S~}eR4*;JxxgbiSDTnvLkHq4>Ubii95|MWw|ti{*Nt76onU>jluU~F*<_a~)g^RVsgJ7fPB zYyu9y)-IblIp&b*+a3U4hjYIlpT6-qm7zcCq++jv0X1C0ZnYakux`=d@Z3Zc-Gnyc zWkMRmCdC|a|2Q53ts|wcywo_kiD@pbGraRp>CQ3dy8l(G(srN#e?k%rltJ&rUw!F? zTqG_1Jg4S}#{UR%-mVEG!(nUjFToL-2InPzJf?gqbf!6k)aQGD+*+W+u(UX1HQfQ& z3$b5hZD8Y4)&`U3X)6;)N*+NFQRTM3+#M_+rKYAuN!#NU&*#w6@aSE9Im!Y|bX^S> z6cLYi$rm$=S84do#G{JI$geNd%pGrX`qbOMA|do5v!2*&P=Wx;+!amB$q3Yk&6M%bME;%w_`DkWgg#)*6AXllLd$0tYqemLgdTE>DhtZnonXU*tO?Dfn`KeoO0YhAhKgO?9 zJnGv+79-h!4NgsWX(vfyS2e^{SSquz+wO*Ss3Ht+lW53H!D+TZb$#t8kyXKPtyKN6 z%~;+bD1EjHwu#!>%}CAFbrbwWwerP3?qvcP(EJprq}%5!A0IZ^DJjLgN}u{T<(RLr2spCgIq2M za~36uuAlg+yG+Ro_p6L&1e0?M2DKN(Rx4Hn!StgbeGs)xR6-2^iS`U1c#vIhMp%$> zsJtRW4Off_Pi*52GRDN5dif3p=#A?_(S95MqjlaeW+rjY^F0sZKe!TF2q%EX$m%+| z)oZ0rNM>Ht2V>Ofskk&A3j4a4FAy=sB(#@FW```o9|TZDglIY%;x@{MQ8^+p>b^{5 zWqQ!J4`qS$OCV4%`7kt={U`btYRdc`X>Dza0*LjZ2=W>wm?}tW1seib7)FRN=iVa^ z>h~CTY)ib%xcQ!JOh3gh9pFSrP8J=hr&{pLT%&}_%}hS`hcXG@{9l4Cz*f1^ngs6G zAtusw77%~>FQs!mMb>R#4Bx&q>UrPX5Hl?)8&&uc&#@S_fGCL$m z_dO%PAfw#pzZ*?YYsX3+=+^}1M)t&KSx80JDRZWN8d&t=WX|O_H+&G$GSQlOd!M40 zoZ)~ABPhJ^;b*^PSJQR0$_Cmf0+pvdz+BGNb9}Yf%4Aw^vY&ux^1=MDJ$AUKxZp^J~O& zcvh^lM&8{@L9c@<;06mWl!u(Js~CM*T%Jsb1=OlmBP+i&Lb%rvUS|FSUND&T<{VGf zKW5&$Vt^`Dk9VCLsTWv9w|Z6PRW8QIeeF4{j82Ie?Y?!pYvT9^-PG4;_P_F2CjF2! zk#yonpoXyrca#TG=Wlx+@gU}h#Sfc06OS4$0m`=QZ~>e~!gxx`dY z!d0c@T=lsG<(I|H)o<0Wna5u|c!Hh8NgwGjbM^o&J`t+lKk`y>m|Izs(0yms(!T}0 zGL?4lEp;JvA89*phvPAe5;R}eszH7nS6q7?ZW&ZdV9|8H0<@s*p*tEjCF_o6^caVLMp7oX z2uI#I0>x<=>5#qJwz4vRo};5B_&qIw-}NF6=yi(1SJGm=#)p zaer16OQt@CbE00W0Z8~usG@n#7?0ja&@&PxosLZ`<1dTF8zGyk>6G(Lj@LyeXr-fq zk*YJjCV_RHb%uWIM`%^GJT(mfi6#oTY;E9DBB zxD&KAdJ^3oA?vYoP4YED)UZu*@75ua@Y|x?v{)QV51L9{VadrAK!-O@saEu2oT&He zlAu-em)dLy3j>4-zlw96*aG?yh<#6!8#{zAs(T4%FM#sEjLUCj>m(v?g>q$B)|RT) z>sJ`q>7oPPlbN6hTIOU>0o7zZnVJ?z_>8)gRQ66QXf`}7w3xSzxu2%uWjGC-OXTZP z6?f{`l06DDo*V6%S-S|A0P^ zMIy2=TG=KEszFlXTKC1a`09O=ovX8IuwC?FGUW6w`?po#fxQTQKsUz8sA>A@MrK#H zTGb2i(M1vUH=N;E40mlVC0w$D&KzBmMwprR( zZ2jjR2GZ$|w3+_G7#tTIR1JTb7om7Y!wTy>#_1Z=^ho!-fwHoGLm}gki=-yc$&@|3 zf+Rdh=sZ#T#QIi?Z{`-4DtR0ewsWns7s-lhjF*AYS!Z-4%VT`OB!}P%XHKc&U0kn+ zT3G1&jtUcsS*qhntCoj?mf9+RhCHy*Sp4)R*abWYliQk3hSh&S6y(SemQQd-S z>Y&RJcI0N7dUD?Mfr1Hm7+%Ov?`p<4u)3}M9oNHy{spr&{w664=ABsPirb%RE^_l+ zO0OY`+<1mTX9`t84=A4@$_2#)+`v6X`s{hD4!HKSx?%ghdbsncZz{M1hrp@RV`y_t z$yU7ob){0dkq-^xsyRetBm$J4C?}EHEW%*5#gHR8$1p3-a{y_;i!Sm+1npKbIR1Q@ z!w^ed(#?sL2TkwI1}Nd_KS(FZRzaZyvfvITiarMb@}C1DaUx`-N$#y0>0x#1UIGYk zn#;kobc!4o*wJjc=c89Z)Xy+8DBwR>S5V#f)Q?-#PgR5Qco(<88v4G$ewPQnh7J(V zYXDQP`Pq&E|3-sipoM9$+8uP6rGACaUFUyiQ#j}2&GX%|oFID9ghw<(*-2gK37_%K+Rt)$t#6&0O~ zLd*?pkQ=|*29v9SAiNC{?s3yiFc5G8zDo;6=3YWqVVic zVP=)|AKh4xPEL-Kj0BmAO{?@Jc}#m>y_y81qe=pdzvY9}YhV6ZAG_j%{~T2Sk-w3tskiCyiJ zF{jcF#!Hl~?>?G*0nt$A0v{6Tm@eewEk`O~JYo2u0T~(E@wtZP6%SbcmZYmvWjJ9# zxf|gFm{74$nb0~_{OhA-N~V)R*(ahEEq-MI^yzQulA8yzFf7@8dChI$Y-ATXl9RYc-0>lma`Ng$|%vZ$JFSd@*j@iEGH;_*oXJR<}z? zM;sHW!L^pp3lN(^*{$+o5(?wVY_|BFko`*ACRVpL@26L9%vs{c1#UO?X76-bT>+92|w;16reFmgJ~ z4oJT6xj-CHd;hKG+m&-u5*Q=@(m^u4xm*BGF|TCgdCjLj0%eE9v&XvlfTpMriaHRd1;|7O(E6>Xf*Cv(p3JIOw~ zE<_V%^5jdk{NuNsHh=xEd8ToeUjH-Nph=|195S!@b^)sIfS5J@JUYe>J+JTaa5A4X z#>+lh-6aXX3Z9z^ll>plb2bg1L8+aHRF~P+fWvdm1^`;Xx4&N}LWAcXsmhT2Vm@4m z#i@^c0PnC{y=n;niRW^c+Hli_>*2K*;O0}OzALg4xqxb?bsi!u`&y1;mB$kDT(E{J zb^!0`;h*ewEvKAsNjC5%+swmtf7?#zg~db5sI=_7=9dnTFz@L1PdF(Au&FP2YBKyF z%K?paP#x3U9{s9vKm<-Kd4Ur(PxHp&lsfFrz9nD(QO8a#$uH`Rph8KM%xB2S@~Af? z&ycJGx>&1pR#6fDoOw%$Yc~8er5BtOMb=O^Nsj45Ba*Lv$%VHh5wGNnt6wF8Rsen) zo6xQ3ReaX1X%6N?!oUZU$ziH^#I|)u40-zrHsV^Ynd@HPyOkTNddqpDRDhlMqc?%) z6e3Q0i@b8?`a2dlSrA3PR`pstv~YGxv=WQJs+8>Tyy?{FZs7Tf26rU~6QJQ!%+jJx zYVGPU5LIO-f{^6j-y(RqdwG_#rSIly4mKZfpT?6*}Mo8NT+~?=X2vawd|X z;#o|o^rXnCYL19n>xkNuLfU~x#?laI4-}Jj`3#Iw89XD%CK{@S4r5(i<@afcOTuc8 zn+%Uj6y_ws-G?B=#z#y5)(gbJi!w%tg?uGqswhJC@+U7kCM|)e&3GFwN@z{{%x&WQ zoOMY~7aV&?O9@fs(p6``G;x5AM(WUSVmpDMCfxy?hr!~j6X}lodSX5bIx;G)80tEc zHVQKVEro6~(chk394uK6oeF*Fvt(K=666KSA9_y%v-p@eF z-Bao@D9Ju0F&Yl4pp^jZ=KuYo4n|2=wlP>JDpj$vyF_$6bzF6>xw zzBt`Q7gZ>D(I7#bVWeN8Tj}`_Ntw#Av(Z|EHO1iIG85s930j}D|10j}reQ58_dnz{ zo^LdR1S65IivB55PGoiPrzbT%>;UjShKOk1RxYV1_DO?hC~Kp5_I^$(@{V^YrVp;- z+6L%*h!nQMrV6<2=;EY;(DmLq7%m*L$u4iB=bb=|qPpsI;E(WK)Ty47Pay3RFLwki zhhDCJj41~|Ua#vJQJ*MK-OpQu-BtRLNicy=8;i53H>HQ^@1aKi%LYbs}e#b-Mu|1K#bH4dwdm}^+&*WrhfDG1UWMn1arXcXHy2;&tq0puP zoY@bda;!Q9&*#g>0DokLB5=x(OZ3}E)TaP$37A^(sFxb+?b17n)vx_EfI`6AEC;2k zYT%L}4zn9A(r?aRSDed8=`MN(UpQy1(_~JoTL2QB+^%HV&gfv5LlP2`MXOYUSZ+nh2K6`7K5nH3VL09CSpvv)5Bo#~+UyG@K50NP3hwj#HN zd6&o5ZK358v+wFR@1A=NLfc)De5>NHx3;l2E&D2y)3T3mVc~Fl#o}h)|ACu4)*VUu zLVhAwUt)E!N7{ALg5@oK^XVeY?Y+SUlyD_8J`wRWk(t;=aV{Ae;6ekJ#g`*2yZeoP zW%ObA`otW-RWbu(q0`b2L)-;pYfW~;j#^+ADVtkB3%!+WU!a*`veFazBZImUu!E0z zp_N+PH!{yT6*)9a3r%muD{ZONvaDEen_F^pPW-|S=lXzFuDgj4^*kM?j1?Xi3vs+k z91Q_|ia=26g=U zY7`=j!``gb*5SD(MrkgC*-|TW1>^N#1rUny)?91edj6GXj5DLH{=d9ijckqK5vMr1 zS96`GHn{$HfuT12vL^4JF0++hBPcE#lVo`jI0w1S#hrEP!?<4VMRE>vRs%%DxFjEU zP;i&oZr!BuPlOSusRbU=ltkeyCK!3o3$`(O5FRb(1!c7X{He65AI6QT0xe-_DJvzm z3b8?zU#)Pa_tycR9X^!ve!J^`&3@%?s^Cvzsaq{r*Pftz)5}vpNL~M(BhrfSOT^SB zB=G=i)WOj+vbezJ+#MhrqJp^)FEt+CXzp*GzS__d1l|JAk2oR2yd8bPO`^Hu=M`5p zdFckrrOa?CcMcd@;R8K4wy(tcJ`<$xhNKtCYVJ%GxyF+}(pI*PemTo)nNGYKbAcAS zoO!C4k?R~#ZP!8OA4{2`<2H8Sw6Z{_2xLZ%_Ls{@3>Wq9`Uy~zi%1}dBx*7NW+dR( zDX~1EVgO3|$c{@5hAwfBC+knACENQ>8^?U#Wo(U(GIlJ&{6owX3TzOgb$_usTqvF( z2~6?FJi7v)CuV7yoYI3wav}L2$tTrKhMY(NBV-fk9tKKN_%~zdcUycu$ySflXjyp$A^g{cYRPE9d|rQ>}2%Y${ zkvV{<%j0-L;z+j;9V=i(hMY=OWNeTCH!`~d6p-8NpvF27fxzDNZtq?Rbawun)1Q^v(FG3LbkPBaX~*YAS4&ALtW}(Xb7V>tuM>I zw<^rZS17mCvbtv9*3`+bW|{ezrQi{89)cJ~J@CBh(&>85CQ#epyRtGN8%sP>OBH02 z*!=Vac9=v`>dr_IP@+$ZYQR&%A|g(Y$CN*q=#D?t2}z!-f_rzoqW2*>HN<>67p8-= zArAriW`3SD=beKZIb;tnsrn<0d7~Pzh+j(JMT-aa4sI{p0H8u%K3#KC<<~qH(i)qa zS_Nr&KTpxO3ZYQK_nFCqoda{)L~3O>li@|BN6vevg1C;-ZyyP`j!g|wK_3Bj#Z#A6 zb&hj^{86}04EmLs;1vKSaeX6}d!V3nBbWf{l2wAcF`YU;q5Pvgtwyk(ofM^44dgGSw#m%8{#IXUL~AaQ=6RW+*&jvl zm|aLZ2Hx~`q)EB0_kp9_lgE{>D~gO8lL-&kYWy^5aw7U#bp6fqWVkmVr?eF zC#p1Ufs~>)V7C)&@9aX z$^ns4FASlPX%q-l+nmacSZxGQ>~QqU-SFzzgJ8A=!sGu&>kBM(;$wm&3ugqi+v|7Ie9G)#+s|}$05xVM%q@6cyMgL1D&`Cb&R|7p# zYhV5de0$NC=V4_elgF)A|LJl!Mhv8&12Af8{xLeiu5rz)lw)&(Jnx=7F12*Q5$S># zeZm`$$I$u>OGbCw490r&33yk?`ZF7$6K)-OftQzGen}MkxawMJrTs7GtE|}DUO9S= zRyzhX>yAhljIz17)Azi$D~epYs}Mmy6diXh4lmwsBzhpXjiQX%F7bp!%@b!Iu5>*j zblbJvyiaNl2DgCldTX<(Q;76&eXcE z8ECe4wAESs4`;DHBd10CK8=K}7TX=HF--0rPjvqw3{>3~3)S3qMsK4sS)|oYp`dk# z@pLimuL`MrxO#8fPk{yStbsRM`x|h**CB8>RKX~uPwr!i26@l{g-cBu|+;)sL}+s5i7k@Kw?s{M1jvG1f0ba zbv(nFqWo!#5dH|B&Hu$vSDQ6^%s7s(*olo~_X2??|Mxdi+@`cPjJ_brPS=o$HrZQdU%V)K7&3Xz=GUZ8 zK(ZGe2_q_C64n7;Jnx1a?uPZdhfw~W$tQ)w-bIS4ZWutD@hyhA=7%aLJ+m(b+`tT(K&Jz8hnOLynQ+86SGozh6Fk5S3)M=tITE$_%3%06jp$zjgrxRrnShPh*@rHVPcB+=J?*x_-y|Gf6vm zDEE+kbY|4XYQ)*TGa*~IZmUhih`K<9Z8O@_WcfOl@3!bhfU8xgGbX)5I3-^6z6|0v zCf*0#Zyp8FH;3B5zW5a+!KSN;?~N>P73D^hpvr?wZZgFb*DL=h(#}NMd;7XlV<48^ z&l=D;J9rhcjzx5H3^;WPp|kf^kIRIk5~D1~JV~>ZLzje`gw+8}PD`!t>Bqz7DowkQ zx;yiupmws1umiPb>^Oz``?`tR?09Lq&q{2XTrf_km$NMkm(a$7Cy$#?FKk}m5G3Zm zUZ02kCbTPZdio-Z$Y4@p{43zIGr%?9^x0;l4DHa?oNrw|Y|Euz-j0U8w*Bf=bM_ZL zv&NwiMrJr3sdYYzp7=&&zo}FB9iG<=!ab5h4iuL9h)1$3SXWe zU_Pm7H=z<<^y@`JkQX*bql#~wB-3+=@AxmN-)_(M#sUspl)c4?@jS%}->i z8HcNuZo627Ed?8)rs}`NkEyeZhqS260hx%IaHm}s&x?do>}z=;ymEk0xsuSzFo{{j znpWvqc}mbVOEua6pgSs6`V#{Y{60G@p`tD! zYc(kv)uUS+_X#FDw-JnkwIk`Hqn#R9&NjMPVKZe6Z2K3F=pfafDLc1QMR5lDsg19E zJk;@o)qeU5Zt_;@KVeWo<)B-Z*~Hz7HRCpBn|Kg zhFqA@3+z75UWN=Q^o>HBN**v%qR+H$6;nfxDfj~G+mGGTyvcYhv=tJ>UQAg@*fjcU zQ+BcVNgd=6PUh-eh=8BO31i)~w+juM^Awr5HTo=+*ge1@4@^1h1!v`T8BP1RHn#$Q zE2V``iP4?{ByJ{IxekaI7ee(Np5Ti5QtOor?5F;~rw?IN`m)3L{< z+fDhp=f5DZFdlmV7`Df^^fs#LM)d;X2;Zjql0LK%OJ`~T+V+^VJ1`KVb+LoqrpX`( zgGIj--`}^xS6C3KC3gjTq01%Vp1b`-lmq%^s}eL-=`4XBXE*8g8PvKnElD?ZZ2eE@ zw=S#9H>3iAut#fNC!^HR=`W@mp;&%leER*cg6KNS>k>c&ZFbfxgsM3Ll_hONc9P%5 zg#d;fE2#0EU7jM3jr~NHBnXMY_lw^(iX>0!--<+bPYdvna3+1Av;czp5sW+qFJRHK zs%}9zf+lPSzZ1c@xMSPO1R4+=rOrB5_LsOfU~u_Bj42c3e`va|Q%=@U99N>_+><(M z3$gq5q;;y(m`!U(nsiJ_eDR$JpL-l9(A*q|i{lMNvN?Ozk9%Fx^n?j&^m1!`5AZnb zut;&#U&1QRM&Cx|IP)`wmfI<@Tu#|N+6dwYZ7<;RqOX9@n(MReAsSO;nN_ik1UP_% zCu2O&((5|545&onUPDi3?z+#9Mb3}C=tVvhBV@~wBx>}KYaI!hNZcm7N58nOO|mr! z$iYa+CFOQ{L)s4Deeq_`a~1m2b=0$mi>%5pkG@SQMo%c?cn5h?EN|24!Qw^&S?sVhxwM5)}zaf*hV*$pBkTmnY=qP9VgZ(m&e18tUoJJyRv@RT*A9X z4YB8LhF7PvOwM8I!$?=UR{SBQEg@JX>rQ=l|?n{V< z>;;C%QqlF)$`(42*DT3aax{u0dFof`j@nQ4>}P_+P!p$10q0bR`knWr=eAO;2%q?7 z3@mN!|L8QWUa)_?{tox5PwD)Zj9zS&@dER46D~o95F8Xx_p=iYe~NP(T|Sn3ju1fr9zJ>knB8>>Ho{LpHOkEXgd{OV(6;_)}(Ov5m9_!ZK zo!PpI00booM#qLSw>Fh5E@2A_Jg>}$8(4PrQ8bq-US>}0v7e$`3w zx1TtEB!2}m_-BL~GEDb9+^$QuXNG-x2THGlX??nU^-(AiF~f{Vj{m zMB)Z7VY4E#zQQRV&2vl#2U?Fe>HZ5A_R%TUdqBlVX4=Dv+dcUlJmm$YO6;4{A||7= z=Z0nr$}Hcx(3n+-W1ci>=U9=2Fk4^K z-Zek*h=|PLKOblXpS8&MMco&|dAg_7UPsL1NaVDTFK2p0gTE36Vid9bA}#Nca6zkJ zZUWu>GmkW0K(V&~7tC_Co$g;NH|fy@dOfqjM>AO=q!w7UirYBwOr*mOw z{I>M1dfbcqLn{E(Kw8|x_xr`JCpW7dgoRt3ue19h(8Ih+6}Zew+*zCcA$mb~H(Jxk z-W{BbgA@Bku_7#o90TIdVaO%ci_wY?q2qK*qkMvAjCI0Gzkw7@?GjYFv-Od6SV7_m zV0bSMtKoZzL#`xU2g~Xd%e%(VaeBUJ*fE-p!ajPV9M-#$6 zo=3!@W1t!^H;R=S1ZiG)MLCSd`=f&qagGg?grVo(m@GjoCy}#WQ+Z6k{PdWdZ{qws zMl!Qty%sff0B1ML55(BFR<|`&F)b!DZCgNKF(!EAI`sS{QW5SWz6lehecMkVk3S_N zH2MTYLxH^EL3wI|ilgg+1w*vTX{;=cU5)DS?(AK-(ZH>HkV<3^zZD_z0p zudbQ8Uf$jl%xfhd1)rI3sE1q?3JeBm<@ob*@pgA-a4tM_j!&GBU!JX_9H|8?nj`8E8ie7pS# zH`=!zqd)9(a8~%9L>_=_8RY6tz9&8KYuf{Dh%AVeW?gByw z*mV8=?WOT)(mD49zZBCEMlG|{D8X%9N}XF@bmV^~&%9bM@UkCV)KxsFBab=YRa4P_ zpRb%D_`Q#Q#&Zk__8;%PV4skCVgv4yKVeLt*%_-c&fCCIS#`^&cY6%sKm4Vc}(GwfLwq3is_=U1LU z&_GN1;*q%?H}?=IiJJ!K1G}M-UqO8FWQ9@Cn9jBVaqJ`;r!OL9cDC7?kTvKehae}J z6vsaZ*qv@ZB9*}vGtxY_TKi2&TJ4{SoztX3@Uws0(BfD&b_^Oy{x64KaNciW+Wq$1 z6+8t^O4H^ett&dj7Vp_Tt$P}P_lZdc@{r4-0XkPTf12F=YarKScDXMm@d5Tty-)Y) zBZd^19Rc5r@kJ*pXIH?!O5TQ6;gWEDrQ(;FWSyj+KaBQ|fs=S2+F|!EI++V7^a^Lb zpN3`?O5r`$VL%fz0~5W=O2K%7@xOpGJMbJ;g*sr8<%`U=&S|3)yzcZ$>OnIEd+(hJ z5oN~2cROm)N(bFRoJvCMX6d(r8_!C9o+%;@wtJOXeQrQjjBG_v(M2M>TwHrAP>x=T zIo_>y?|MX92-N_z_|YB+0uHZNmL{bi?m%kE)_G zJ=Is~KOmdFj{?^Xzfrca+k<9k(bBM07G(VE{>Q^%_Z&PeZJ(A*mHUGw8@}946R8Fv zAO1gKydsERQu{4FQ6vk)xdQyU7garAwWqSf3vso7tpLvpv9PsNlWF5V<5M3l}U`-l^-G^kr{5L|522Lo!aGABgVHmY1r%#g5bF= z5Bv*$lh4)uP-yMz0MSjxrgLGi9^;RhiRfozQPlq>bvrDBI|LDxp4HY=xxF8u3U5N{ zp9sEX2FBmrYoHE5scGbD?oB_CoibZeZIr5jq)mpiu8Ufb4=B5o8_`Vo5r-sb}%n)Zi0!7GXXmr0>S+m(AH*WXzcdg;nO5!i|!gRJ*ZE$k+Z ze%09bGt<&PEb7f)a6BTz|Pp=wmp_cN_0gRq@b%b`7Fhw&TSy?4HZCL z_4BK|G?%tos8AviJP0-}%{1RF;_x2bm+t+tP2=U3q=@6PCu1wJR#!VtjgVjWrRCeHGwq~T}ZAF_SV_lahpsD^42^L5t zp`&i0>rm)ojKw!z0y2TSaH4L~hbpSEz}Xf+kI6uBHU60)CZ}1Dhu<5Y)RG_DGj(N zC6~c+5pNe&y+QPu>pj_~7KpU$Z8DRGWopq>9=B5CzY@4kqKPW;++ss1i! z935d%tk*gw&+b;_9mZPx+Ji5>bTmyz+Rmw^+r(_VR|-q5ERz+tJ%Y9b)=cuf0Os|P zeqV)HwO1He2L23*5c1CqzK00MGn6Uej6-+`llPTewOth4iCa8Y5NyY{y?QKgi6gWAZBRNl3wAri3 zr=kM@#^UjgC2=g0JK`LkfeF;Iob(_c-4!JN`X|EAa{o64*d*i29biaoXLl#E)wx$G z-@(2e{=8xXB5EBc9u`NxaY71#`@giJZI&M7+GlZRcrpm9scQD&Tz~F!-YR!GR>Er=J7fZ$nV2$kZy<~7l8kBsZbI(@wVe=35H(S zjnbx&hg>d++91vd30=7R+vBBlKAqsh%#Z!-WaJmFrp)qlMtK!Rp%buj{IT&euq34D zDn+4rs8)4o;=jO971HV@KW2p9^z_UK!!ymHbGac!zVCR~DF0DM9pCuI_EaWK)j+7>n%c5xcJUaB`36!DaybvnB4xr; z!r6=PNzt2p1ySJ1EVuwz9%twdanoSV+z7*%P3;t>8sePaxxAM^RctaQrAlJR>T zfLgiMY7cZ>@`+R-ims^@qD?kYc-v29S`*>4qSP-LrH4x= z16fz?NxL&FN|-wxj8B%qg>v=D#3#BA;i^^BAn`GOGZ%0MZLG?*7|7j!{hS;2U6+aWZY^{1JQjL4(z(Jpq8I^Kb;wgcsTK^kWVR<+pqJpEDD<%E2 zC9qknr!3$tI>L#QA2%gIAAu*+^c|T*9f~k@6Oo@nh|>V1W~`0iA|!Oh$)PbEA;{!eVjDV4dYjy-@Xl3TiIjQBv{jZ-ibm16sF zZ4d7Ou7TnA;{!}n5LUX%rd(FF=Jmy-iL2-z>1+e2&tJksU3FO>N09->=}-V?kf#t1 zM7~|+@0RalD>3=!t|Udkc!d)Su=7#J49-W(-$)$gD2r~b_qo-qqnYM>5pE1N|AVSAeOoFWmwn)Em1(PoX2X#)S4 z4asnj2SoVRs}*Xn*MwN$R6hPvIADg@rlU8DlFF7@C+?l0g-x9RR8Du)I_7bPa5NvV z^ou6L5vwGTqL?u4t_`~Cbcl8myjlJ}A9?lo8vY%j_rHN~^qRuTAyef;aD5x?MA)76 z4JFM`^1NQn7X{f@X@4qOC766PDD_x!t2z}}WL~-g{zDw^?9?gQBYYXIxXjxRsi0+A z*-V2jRGWx~TIWBQHgn98=0w41)b4&QQs_$r5GhkCBwKmV!j@BuTzgJ~FFfz7Btb)T zxY>)=j++3kcbI!{$~kK`)pE-mFW>bBwE^w6864CeA5vFX!E8)JM}-6XiglIMjqTJi z(NYnRRtXO1T^N_3S~u8WJ^Nh=H1h9!6w(CHqpg|SrC=`&f*$#8Eg$JrMs5~{6^tK? zi8$~YI(z=7kO%OWL?)03Il(w*O3jAlnp)c>Zrq{zd7gOe@dZ@?@>H`q1qa;jQff10 zsL9GDO0zr@-go>9bk(iAoSVM5VGRJq&0lbsPLk$&jk0ewWh4c?Dk*reL*?Gmd#EXshkoV!p`4lQF9K;@0VbUgN&|;Sd_tMQrI;2EOl~}47 ziPAok(xz;{a6qnpI>%{#zFz=)t@L9{pOCZ_M|uKp{U4gI-_5|Yv1?iQU;g3-Cr24! z&C?rF83Zg0?tDK?F{?Wl@LNS2yf@+pBT%k{V23TVAvJsQ2^yjhcatDe#?(?yboC-D zGvG*VZ0y}4UdocVLU^Mz z@BL`0$AMa!wv;Qrmz^IGw=o7$j=vkeXUWAn6zZBL^_g?Cq_)F~(6E)1 z!#3~b1uWQ1@+iI479GeVFrQ64z+YD{5`A&~_=Iwn@6NARU3KV=iDkd}MA!SwiXUh- z-OkRD_}slIAD%Pp?Z3G13A8*m6e`b0_!gu5*fHo4^Z-)x7PdS*pbg35Hg{?p;<_CC z-b#S_!@3`b-NHp$)6&Wc?RJ>u_ZxvuD)k=FmCK*vMX!vfP2Hs01i92$7oP*U6-lrF zn`LM_OAh1k1fVbs8~KIov`3D2(H|wbnV58$s*31vZ zGl}P$@%kxgdah9_Vp)yfegkpa(vgUYh8lw$z*m;MUzBS>FJ4gcmtNY4HuED7U)CY( zMYqryK;nGxg)SN*J#@Hh(x*B2-H=?GTte#YaT@Kl29R_ek}!y#X8Yp!XluANxa{Uc zyxC9zCgB4^071-SEy&Wa1Wn@aZrbi-@w3I1Y{7!9xrZmA@3!?FxF~%4eQ@DZ#CcRP zk17}SKcc3)m5}yY+ZYVJF~(u&mKxybuRiK~_%BY8^4cU?9O%-p39sK=hfHO2bSA^s zjyPVZ&W#|x>Es5dnS5EfBn^P^3QZvU!NS<+L#(eA)_Mu6TGcp#;CZr}xo=RAELrM8 z*TjuNZx{D#cxc)2ZNBVBI=KwU%5%lN6FHfq#D=4^sfx{U{^S5Ma~$sNjJ+kpQpK@gJz2m0d#(n@2Yqibd!@!Bm1LCMu#; ze8F4QV=Vq#PS!1Mg;qwS=*$$HugcA*c_g-&f5Md&R8wO)v#8S0d;0mcN^eQJUeyAL zHtP;Ox+_(pK1ANW`Q}QpUPsEaT|=mbxM{iAl(CRVQ<*IidCFoa&#z1yYB|}M|CdjG zo#_8=Vje8PpgWSX@PNai;!qgao@(jHzH#!+8C2E~HAekX?G8E?-dOwSy!sqWl#%b7 zr62)Stj)=&5;8;Pj)o`o=yjs zP8!)e9)`5t5hwU3ICpe6N?a+;ZgmiT)2U6xrlbnl^dVs{f~jxs*uhQ-Z?qC844#i15!eE?h!XE@#gsYaYZ*rzM9 zqsQ1co)=i@3>EcW2VbcrB$j1z3=`v={uUV{y*yA_@Nk}o4&Ja7n7Qn&X(F5w)S4Na z%ig%1g7~U0$y?W}P;24vI)|ElBK8;tFMuvNO`1#S>yXxrYb>Z5IAj$riKG!?UR9JlqpXyei=dgJ7= zj~ikAv)p9BZRY?j3(NF5oVJ$Wym~{^6CSaexN?R0ACiA?Wj3%|ee<7qWzJx16A@9k zpT@|V9TIcsmZppd^hGY&=@}*$ zTCJ<%;vMz*vQ8;$jmrF>(aG_1HDJX+)nA?Ym-uNn()LC(0EVJ(&0~Cq!U_%kkhbei zD==O;H#%u7|L?4V#M{MMN`;r%G1@ps<@1;C_y6p4o)76b$OraIJda$hvdo;}e$I?9 zCqozm*GCA3KRN*8C3zM)9lf*eJOrvA^_#}kxdx@d3Ise6=^t`{%41J>bgwqlwyMn> zckw&H%LNfo#=1Tgxnb%i`qZ$urrMbRfX0{pNWXuP{h82)MYPtps5LtMX3!-&uEoo& zElH`kc#=@O2hPf)F=?gw?6vMqDcS;(LC7q<2OzvoWiX{g-CcVw<01}%W~RAt=t)ND z0Vci%rSgDui*pE?v=2y$o0!1XGf3l!R{BjZkwDA*p5DBR#B&N`KV3Uz7sEEx5R1{9 zcJy!cHoIKr_Y~e&nL9sBozQ{zS=deiug}~rOxE3A>!wp7S|3Mgi4$sKEgLFVA;@An z@_J!lE?PsKuZVRz5gngjy)Su=)y6o6wqhcR*B`2EIxV_z!QH~N@t(fm?l9FRKFMiI z`ieAqj)LShWVL(Vv+rMN_T*lvFw$-~k^p&jQF_KEUM<)(j)4SG;JU@sBTqLmGU#1h zBDHHyc&$Tk0AoL-!p@+WA+aNB%>|S&j#oMEYPk5r(%Y1UH_GS$TvUs~p`VXdDk6%6 zcP4P$mQ4{aJ^Jr|yv7tU(d@?WGES+|wD`gekm@`UQy}j|vsZ!K>^ZB#fTSGq(<+Vm z{Xx!)w*-xEuK~_w7@LZ)Q2^$58+|2iS1GG&hXM7kWC&Cg>OEWFCY!7(mPAzr|AJ_#-E3UiJ;lai{tCuE0@ypRBMww02}ek2s3 z@ByCpPMO8}_H|miGOW2`uOF?-K^s6t3_ZYdWxoGDM0h8%J6D>5VwZd~;4 zJb6doXeJF4121vH)*U-6mL2u%qfCD9tA0h^T`yW89!uN;*0 z0`n$NGWO12I2A@%rGxW2%^roawpOqw$jR$S7X}F+nkN|ldxJeN3!zH zVr~!iKRR~0Q>L3-wvUFL86d98Qy2c~x?-o{*WYQ#p&oMqb-g!Af(9<~=pL^7hiMl5 zG{~t_-jaR)Y0N)$fPnQG06cdV6{33J5z_FO(}*UfbzH9IvvK5Hh$5*I#R9t(A8B0E zNY?ys^Z?l`UfZlZh&(3*m^|&IV2ciKgP+2zm|uKbWcQFF^P|EN*DzVs|F5t$Q zbYhNcdP8w@<-BNn3lwk~wTBpStmRRJMF}B`{MbKM@uv9&l>p)QgiQB48nvhF-#kJ3 z`6Tsl8A_)M_VY|I1-TRl>H*eTyEv-hkP-*QV>%UMOb zrW$o{0b7*Xq|00CDs)Yq3(yw)NUw(i=86Ds8cTmL3sP92O?_*0cxUf$P+K|$;j!5B zJyeB0QF#y|iRqMH)QL@BD&X9#yp<~h4w@SYMd6u&>LvXZ`{x^xtweBi{XE1g4OGaY zd9!1BQODg{7Fh~loh=C^c5v8GL&jR1v0`WAF{asNN#kr9u{4e$xRuZRnaddjqluGV4^ag~)XC9d)h zMtFLs6#DZip6X5(AM=c5#=Gz%TJ)3s;hQ-sv#yz0+laZQWu(G2eT6h$8=kJVMOCia zOmWIsJydUg@1)})IBYHMA1O*x<{0N^FO`SO7wZxLB7+N$-;R?DeOEMFi2FuWl??CV z!?&izwSB;K-$!Uc$XCNQo4%R<-kMqB)~Yyjl!&m(zm7(~1F^l8-2&+$Lt+lz9a|?{Y4+zgBVU+;0Ph70R!tc%R6>4qLzJK5XoQX& zjE6%gHvBfr+{a&!t(w^u`s+WXaQ_Vc`{*f)t7>FMi>sMOyocGdj7TokX5F0UH$y3E zKn%ne-D-WK_(EgtN+I`4svLrxu#qr#alqZ%02=CkG}NdnSwQX4zd@NF0p)QTrtulu zpW5U#OIwKobm}MAY;mgZKTDPdN)FQS8lE0r1KQqqr2pi88p-rS`S$e}3_RF(HT~~a z9g^pTANXOj1OW&OkmA*3o{W^yXR0ePEK1;nsPk2Q#M-uQw$d-OV>(H{1*~HFFw*#L zQCG_D_JXCP4Y`@An0OdWD5P4Rwe}u(0m4w(poVUG22-xyCGrcY4*2z+Z({tY%$c@B zm2+1ET9H|KZ9l8EOW4pKRP$Ahlab3O^OQ{M!)9A6V`h@tX(rT5GEg|+wvvHzE(j{} zvzB<>0+-%}*bv&sK*%t-c5vVSv%c}T+UQBK#vFN>ktZ@Za}{edA6I6McJE3^G(DXz z=hl0WMUdc0UD3C;?#zr5r<|KnlM3YV2);NeRe6ax67H!H=r76FN;Yu*xKy!7#KJi< z&?8UbQSw9jTd;h2QN`C0UDH)n(}+O3NN%=7JX3*zXQ%i2fhtv>ZlpxZO_x2S-$Ksk z-~fEm5G>fZr|4;c^F&MvQxbyk%iTXI90o+W7*^%EPNdOyQxe}fDYg+-77`Iz>vG~; z)1s{6;hGz{68R?l{}GRz@)~1_>i7`0N>QhF1m_hE`}AS@_p-}6uLn8bL3!e?kkQ6@ z*RxIef_3mK^2YCDd+XT-kzZCu8kTl*{h3jgo+c)~w>}7G>^H)|*U#2Eal_gNEEb_T zLbb94U|~JM0u1cv{(b(;7)BRwKuAoVG`!)(lcQlbE$nJ6%b0OS32_4K=WJuo4l?SW z`V{%(etQ?M>uM&?G;gW-3R)me1nr%**^tdZzltzbfX|RJ)?to2F-%k*l5l!g(paR? zde-&)QjR|oum&(*w^U~T1fwz@LmsZDs|(YUjJ-wXVv+5nKgU4CxY@nH<#j>zsWt!> zR2}mGNo5`cMd@y>x8^ah(0+byfQ7m1kGyG2dH3@Zc)eu`KjY z`dpaIHZu9n7AfNuytK$_ATcp!5*Z{}#dlXUu6mz&zF_iR;+!phRkuwnoo8GvPb3?; zlFeOvIi`cd{{XI!i;CRF+#~~x>)_kUw4&M6u@S5w0Oq3>KapWFWt0i1g(><;FUEtf zHR3C7C{+;*=G<4gtdUSLDZtZoS*DTRerLHiaf=<-U_^^{zbKTmSwK(7;d6T4hy-7?v;jQFR&`z zvD8}RjD3nD84~s@y9j50Qbc@&eq8;*^x^uJW@<0&$;Gha4%nwTp!$86b1^#u+C-{D zva{FT09`-(Qmyn^i@tVvC%t}v^dG>03Keq!fKnxWn6W6Uam{%1ad>Vv|1Z1rkB^Fl z@}qi(2Pq+UUt7W^NiPWoBT#iTIsA1^KYpu2+y362i~wYtrb1uV^<@NcP?qaY{(&1k zx?+skhvh6wK^Rh@Bz5}@4B=S?_W5yWkISCK4O7eU7tC1e@djQ;NG62#D-N+f?$R5i zm@nnI(TSl*`JNgYgMLu>vC`auibYfx%8SFXzYyLroG3> z9Jtc!cI7q4URFJ*N0O#bhhr`k#@N9+?uGH?Z2MCY2(&^%+AisW<9wl z;d8qpiCXuKx@jCa6KgC@gh{|7dqkUw6_N*~Vjgc$2kyY)r3!A({ z!zX~?DHhO3r#jl?rxX@?`dcn(2!`gOT^TGT*-DKO(WLka14YT(tM}44wT!(T8Ok+4 zMl;fTOPC>};Kq%Tn))v!i4Wn&Byw>o$mTdE!;o1mNH7x{$qGBE{Kh>5r5W2Vl}Zpl zL@NC({6Z|p|F{p)7O=hj5U&@ne@FTq5a%bqz_c;FP0Ze`!PaK~g|w)WE9z#{p)+6DTu)b<0OyzHt| z^G?0RpYyr8tj$30GtUx*T3LO2Jny4@)fjlUKHR z{*rdt!tULy#7dEDD-**rM zKsR1_q+Ols4RZT`q*w(TAy6m*g3J<{nqvF9(1DWKw;kZ=xBy=5+-Vjh-nD1hYED{L zhXl{{oWDm_*t@|C%OLZ%yaB+^oCHAs? z>L**fRtxA*xCjk)+zZe?gak^kAq$UU)}!Ml%V&O_^lC3TPN*n>YUT$rJNn|wRoG~Z zIi64QQBkxrJABuZsA+WN*5PJlDK9Pf%p&UCc70{kgMuWpp;D zD6LDJmGwa=?g)w}{R5#5s$eQrO7k#nq9*I0Gkg+^IjjkJa!zzrjf@k+tNShEq;mwz z38;*O;-=~K>&~Qh8dkq}vwbZTC>uVnnl{Rx)tXxZM|sQdHB7!B=h+>c(#v_?BS0(_ zD7Ap`A;q0f_8u^#COiP{3oerZswymaLg?u_Y2_0i3;v(V<``7 zJ$T}4F`|g9M*>7aJk2_~EW4K7I4mNrS?_`HQ0xgx7@IzZx?zOl`K{ZT{s-5aG8g?R zG87}+F}CCQtxQmjZz$9s$x?nB1+(UCLOo>4vEMw5i`MIRZjNUWaimbiPS(|3uGqJJ z*FEex_PWtvD}E#U3&SjcZ`qo*aRj>IC>pxI1jthfKl~O>fXY1P1kjn1I`v9WE?xUu zW)rMJP@>-4Kg9Wut7CnbJSgXzK4rA|+iZQLH9F9S>Y_h=%GQ?vw4vD94+c^9n#ZN_ zQkAMN9HgJV5TZ9a&M|@1*#4I6)sl|@>{N@uLlHjoYYb3=ZW`MRPYH|e&jJP;7D|^k zk9EzktA=KL%9yVJn(TisyDiS>hyh=4grW*iLUF0JFm}Pm*PokOyG^%8p^ZlAU znvr2s3ulHot&k83f-F}h8#rFQ1_T+f5&f@@ zE%@rUPI}DNnY6S@t&pSaDY`x`9EBse)B>6woQN)F%g2r;2ZiEyAs;3G8uErV35vIR-7c9CwsN@^;+5z!Ha zt$)dN%hW(5(2XiEPup)Uw0O32@O{5<27xmR(kw&-D!X7TFVsxa3WepU$(`JgFLN5` z)rjWkT*sZI#Ol|M$CF)NamP(FMkS()2LNI9Qx7#~nFdbQ^*D*I>ke$Z@A$Hp#}Wb+ zT4Y{h=kQOeNSVD)#tB>j>!!E3@^+m+p`0pv4{gB?1GCN$ekmgvyoHR?V8>AJfDDPs z6jHoQM}7B<=vi+P*SD=6&O*O-}#p6(eE6gG2roL`u*+xrrZn*boL49E+(CKdbjxf z1b)(UO?Cst5Li!bYur_$r5DJ`9@E8bdk2&J7YeAwKx|KO2<%q*OUpKW0*jz+e^sST zn=no1r_gg(<~+kg)t--8I$p7Zw^f9 zrugSG>2Zvf0d4#07}1ounjKku^)UwRzhG?w`uw6MqmB1v2Bv3k5I-*7Yi+50i}dRhG&dEAuI=NZ^)rKj!hra_Y?-1-^G zRS}2N&Ptq~#a-e^S# zTSr$0<0ER`dyw^%>UiZp&Wd$F#EL%glY`1Vb9eJ^jkv+VroR#1iTtM& zLlu0#%MgRV+ZBI3U#`{RdWE>(vvIW;lH+l4D}pdjc8bpn7e}`-F)igj{)4xMWS4mx zp{=8WKBy&d|HbzTP&5XmB1$ zDO=-{|DLyOtqr1nO1eRjp%5JrStsx1!Xs?;6B0uHs@DKovoYK2J6;EXu{ztMo#C>R z)Vu(0Z8$$Ur%+hnN~jAK6F-~R%)BX{5$Mqc$hX%=p7VC0pO5SeNfMx5KMcG`hmF^w zn#|G&;d7|QggQE&v@YNOT7+%6zj+vCltx@5Fe3rZmGeueiC8dd`kN6*9>^PbE)=|> z|0Nc85@URt=`wFM$rPyz`cfb{|0dbXlOOe$ko=x{q1dg;-SU5nS_W0Jc|ErfX+LNB)xgCjjRija{Ad9p>Xj=ydV-i${Hn-6j3@~3o@~B3$Dd`HJ z0It{t#7RvV>3fOSFoB)6HfmnT1x(7%d6GihpS*u zLaInJXGChvK2!*@?E+(Gn+87ij;!LDfLuMkJqNt?M_woO$q;OAzE{Rq098EEvDb$% zZACkXoulLwi^gC)wK=+*q$@O$W|`F#T8v1RMrnrvrs;$cV@RJtyD5=K8!$NLTjjFT zKV5!Pr@>30RFEl!oPT|RfGtjNe<_18XY6TmYf?BaLd-|z2BTtWlko;QGNzdXfM|Y5 zpq@^dk9$_BLqls?FAjW+E^q7dWakR5p?ce*;_0t|(a{s=JRNX2&MxPe#QL>}G7MOH z*UN=S(g^0-*o$6FUgqMz+?g}85bUKX@osjOsFIzjycc#KM}Ufh@X>YvvjZ|6%JY`T z#qD$SKApY+-$533$s#C}L}eX|xp z@ooR)jP-2nhWK)$~=QGaJvEqK^a zq90Zdp@F%(1nKzzmi{nIyGk9&mc13#vEDYv@D^0tT{cL{d`kv; z$1M)HumLoTY?a0aQ!msBr(ICS#OcY`(KbQ0TGw+w_Isf}mQt)1#&;F(%`4JMkdfK% z*9j&KpK!`8W6q>GBpx;tWf@P;r9VcL@EB)J=!Dw8his2S3}Riho* zTnMl_tyVKmuMjf=AqlvNXK>Pf#+QO=4Bg;kgP|6NE0c87rf*kUf~5X&Y`@BEM@K3N zYm+cNxJCJ_>=w!2k>Xg1OI6hokfk7zQsre4%Mu7WB^^wdgrcpgbptuG!wa=~ z&dQ+)TC-g8!?A<0y}eW3=&KgCk%(`TJ-cBJ5& zy9l+&Ywjx#U4K}V>|AF|{Aw{IVE{qX-bhc>(@8^L@ViV_kYKcIGOH9KfXOdjXo`hf znNdF&qLM|d;HgK@JX5vg7ORocKQEa+nb{Xwy4mN4rE$M=(D4{Xj@FE{Art!zo($W* zIxlSQlIOR^Z0laO2!jo~uAfo7u@80M#ZK*eBG|<1pXo=?pTdEed*J4>Xz0t1o%5z7 zWi(;+^L~{4j_i^kC5FKqL$bhi{5byjJ9O_h-|!wfBPNzs%qrD90oR@HDWH`~+wJ}! zLCFVCq=t|7+o_Vr#UV$9b6#JAw%>`oUj%HUDj^LDYwKA2)5?eld8=zSUb)DHM{YCz zbXcUrra|Kg`-1l<6I`ipNhByxE7W9+f=dD2 zbu|M%c%tV#$)o|ITQs^UfN93<%XX#GIOKD#{yMgM5-u%4zQMbY}$d#2+{B~*P7`-Wo)KaN;&Q_{^Wd_ zC1YaCvDls)x+|<5ZmG?&9iZ2U^e{;42{tS3V8lr8BH|H1t%Kfg2lT&Wme#*%I_^{1 zR42?u9vSEBhRtr!oUX86S%xVs^R~ap8MlsmR(5)rO|56bDT!*6Xh4*@Qb>9h<2P9X z_N#4(8N2?x%e{3t-4N$ zbu+I@)i|%nK=$kWgqh3Gi=*8qpX z?eC>Mm+3#2R%1Go-*H^;^r7Vo7zmP}>f=kY!sbtZFX^iJ1Qg}EN!rXv(F_VmmaqZ( z(!M=a5*b8DS7D+fYDYtgfLbE}q73S?^=!oIuE5Bv70zd*7zX~GHUUQjiJqKGPsxO- z?ig)6N!CS4W)DThI{X|A7q&56B99h@3xyP7yIss}P1R%mM-7d&JBb!8BQciX;jY#4 z`a|Z02PGv1c-BX_w>hhX?9EsWp6l#{ar*)@ti?^O-+^&Q=u3|}`25Wuk416&r^myj zM{M2}MBI6{Jc_rrtxqEb?`B6KC_&sU<22AM32(*daAfS;S&d*ds;UD=vBYlGGwE9{ zIls9CdLOAfNmQVCmoBs4mZp?`s^Shis4StGYSC45)j?e^-8pUu0sN4OWll4tHFEvx zQsC%%q1(3y`=9B_0H+-?Qf@|MdHo<>B9i+Z9~pU$dqb76?`A(jW9mHT%Y-dct*- z=u4#+yr&v;!>D`!iDlc2ThS2#q>v@MjuBa1yS~@QABP;C)JDDJ3KJgT?jm>A7@~oi zQBtf_8a<3-iX#a+8+J-LB|s2aqGaj%*wz$Wm1v7i(Pw2P)jdaJ$X9If7Bt$P8ko?$ceC~&QyRcB=TIKv_n9Uxm>9? z1o`~(G5SoE0E+CAyNFO#(kUW2@P66!1e&9AL7}J+kXbeWDy#Sru34f!C0f{x2m4u^ zYS75@$SGaiH@aIlsfO0e`6be;Q{eQ+@UI(UOt~7k+Bw#sF9#7yUCF=D8XXO4|8#ke zvhDR5Lyxq!qOqw-t^c>WoH&aY*qY{MpvNrSY7S!1*7QHlP6^%PwP}m z3r~n8E1a~3=U1lT%8{@nChD+R6#9oKD`0++bD6SI<%K_^0+G(T?5p|ha8_UJeOW!_ zBNK+IZq~ypWZNy9JnWI_rDI^xO)&7;azTt!scLsf=3lnbl)x7BIlY#@U7QJahS~JO zgmwG@jKQ63DOPcHnS|CZg2fhIZIfQmC-|)IC^;=L{=kA1ZY>oYa|%b2O_kP%jgnZw zBx`L4Gf|t$pegxCI`>@d2(G(o0_Wi~yw6sF;bF-UyP6-8nfh?32d`hyeV;(|vTQOkHK;?MpQ2^a`=lKqGt6uoP#j*i1bWMz42@2l( z)qHg*2*!E|NL$M29ozXbyl)6jS9lbP8F3^9TB;}y<(ob$u8nXq_Gp)mFdZOYo$b}A zES(Xx{{M|~I8$Uu`{ZQ&0PxCT(NL9ge~Bjczr@^`ZtD+`0jU_h>L)Pc#7)k0C@KRD z-BZj%W%@EEcFTQs;5lc%_23x|n&5DPvNsk~)n6SUrnT!Fvk^7oQs-?)KahPyNSZ8T zXCh+s)<%*(1~{uB#MP~1?fLWVJk=z^RVH_Oa*V`%YVm{8A}3k4#oyS1|2`Y6W(*RQ z0;y5p#1rilhpGnc+3$3i^CO!>O`-_A~ALX~8jJAj8S$n#or!()Z9c z%5(41{n4YBs)&+#BN3R9NT=(3PU#U9a)}gVWUz^A3oV>3PXV@ud%y#Rn=`TbvuS~BveI4>q8HDwE8k&zy$c6lBLXSXL*}t|Q5=T5t zJ{+RfZQN6`c=qG89qw0h^iskcV<-Q8`4INi8Px+e<^*XgTc!tCO}UwmTr!7;n=9*F z;~-cSx>@A$dPHkOC?JM5z_$Hhy}2H)PRtO2b)h3b{z@E6o1>qIGem~rm+a7TLd+RA z-nNbQ_v*KyQ*iaBXTATFE+$ zR4skD&%6!0`^pB|pnMvr@5RY?tFB3{gu~XB3SED!ScJYM@K(F&bxywMQYMbM|xP=UVl3UBw;MXK*eKcMTEC|0=Sk>J8O5gAHx z#>UK$SN~6Rrg3)b_HQKt)Wf-tSdq{gu4~qq`J?hfDg;_)Hsz#EcH9k8L`)AP28gH{ z>8C#(xFGuBv~a$A^TXH^`04Owsrm!ZdnH~`j_vK&Ti4s*uffNnHu+Qr$i-IM2;*b^j3 z6z!e+JdH~_<~@lAmHVoHELCUU(ZS~lSg+_W4VRp zGGmaS>4=SK_;g+l*$UiS{XlD&4XWky{!CmMQ#-_XwsRG{$Y_}tAv&(_{vOqW|L#Ek zexl$TyeQzrU5mWLvZEG_k*ce5x(rE~Jr?Mn-;YC{GQYpS4L5B$7-)2iXNPh+IiZU%3F80_n@I}Tj$G)!vvS`UZMQ6tIw<=22uWA)$FHKGy<`I%#+e$(nmW`q5hvT* z+-FLnP2QHAkN2)nw9CGf=sJjoo9luwDp}x#o##yU!%V^aw-{s(tBu8sX=h5|3B>|8 zgMlYj?*yX5Cp*QBZ69gg-?;w2-2@2y{ z))aV%Kei1;i>dJS%j>!k|LdQxpF>JA54-l=I^D5xTaYahLKaeJy&UP#Z>p3w*BJ?6 zvp^aK10}LEXZc3~s>{E-SkZKZ8OsT^&GGg-bPPg7Fv=>a1?rCHkIC$&!rB6CxT^%f zaPy#pU0vtEv!MV^YwpV;$ko8L#0Su@ZL7^2LabFDcW`n5=Z9;8+vXBv7hL8_rm#*u9n^@`_0$H+HJp)*}i9YCfShe6Sv&iey-3E z;!>ETsPq;1W+5F5_LzU|1rmj4^E?Vf85np>nUL$g7>;u*cS2jd_38tO>VGV2iS{fY z^4&wupA^57H(S}4@{@!{MNx$40`j@wL$q51@kd*escWJ97D*ngZWnBK8iay8aJ_Z! zGjwuSS>f{5(vTE0Q<=#LnGqM{Y*zPacndkX2)q8aOmp?W(~3293-x50g&94BGhYUS z9E>%YhA&f_8bR#sDITmtS9kKc-e6Nee4z0fya*fttYF3?=7TIdU#J*6b5M97eMB z8j%BTH5Ag;RP4xR&(hZ9OWVs44?tb{U4xsm{?^_k0n;vxRIYEx2n|ku7mBB{vod6m z33qI7Bu$4JDd(y10odknzH>ei!+Lw^kVBTms=-`R`N<;d9fE0<*M{QTdEbe7iIuFF zJBmZ|a}H$VpCc7wDcab)vYt@Sr8v2i37Q2F^3+NV8@8#JRw!U(m+W44o}%jpGolMA zb=LEn5|1(|_;v0K17I~yoUKEW=f|58By)Le&ZM5m%Ws>rGx-LVM;nYu6;sK3qq>v6 zFaVmAU?CJzy~atx>kyPxX;$6%R-Gyv+rk>a-I!z&Yt{qPmLqqXtv5cwen)kqw|#!k z_a{CKo(saHT15B5s2mP4U^sDZnZ9$5A>QEK?X4oCgGJFd; zrjJ|qUGc+^q_9Msmlnan%7Q7?#16#I_rH5+EU7KB{f(3KEjz!#C0^_y2h;`F? zFI0n}+w3_Bjdmx+fG&)G;?KC+$~m_+Lqh{2@dfQT_wzfGIApBto6HXF*vf;^9vQDslEvI zuV%;nkYgsUu&Q2ydp#sNjB+)@J!yFdLX)Z*WU`;?JYTG0R|^ZtSDa55fK}LqX&0Z3 zk*zO__?P!{2-;JF(9UmQ@OoXQ;Omm4zFm39+iZdpl*Ij|sNyPoP|UAIy|&M$D5$1| z;j})s;L^&_F0E77JSWzm2{kRMM@W&}w%GMZy>w%Kc&ku3p$<|e*cvT9k_QT>1&AEu2Z`@tD>8kH!y%AZT7*Nb)5lDDI<%o1gVskySl zm`d-{KGh+hcQkd(nc`1dIR%*JUr}a@{fFJ?D(=w6Q zwIQ6#Eq>mI-o4wga@6Ak05ukwQ0Z~~H>Gwrj?G8@JNQ0VP5G_ zat@C8&gUCFCQf;`QJlf4)jG}oFm_WaLbwmtCD;`HC#e7gS2zm27<#-7$_2-AbsCa% z_D=Gn%Ts~%=rPmZxj5CO;p5!CnE7-nfmiZw4JFrzcBdn&yM1!cM5KkFfxs7Dc3ami zU&Gb>bKMj4XX6q2*S;MFCZI!Vgwq%y6W(L%5JPEH(*H`!+ z2LB_Uc4Os29c!Tnr6bU2LEF-GGk{9imBs=?s{}U=hcw9i&1q-75w5iVtGYk5=g;fG z^n!#?686~iJc0PS;^`tRVc*m=BE5Hw6zlnaZ{&))^QbpMT?B^aI0m7zTjqDpZi@KG83lwPn!sl8$;VA{u~m=jt2o2w6~w$nH`Ajd-pmQ0R%|tq6fBw zCqZ9{wA+?k6xF4VIP&JHLj(d%j>Ws69%#D+HW=RV#?43T@VjIN58C!=*fRp7vK?o7 zjvBu#1OzIHt6~?!fNOPk_mvmj&kfJ4gf&kiZH;=aIi&ufCu0^A!q&;nL0mo>s;l;? z4KTf@M*@0+{Dd#A?1LlOuEd-fsmX9M@{e#4JP4F0q$+13C`N@j-Jv{kt`07tYlZP5qf;%UG`>UdQ!q86{5RyZ;A;^WDFEDAK z6!KAdd*EjsR?T$86fHbu`)rhI`PmE282_f+2v{oW8Y9wCfNJ2JYJAH1D z-+MO#~tvPCehOeaQDhl2IoUC9HH$0+E-$oz`zHEnrG3lt*K7m0kLgY;B~S<4|w zl&Hytpy7Z255HH7YkKW8p~?QJZzt6^JEIE6lB^K8o0QW=NuqIL?K`_&jAUy%G z_gmyb!SNq7#078Fl6LmY4ys`1ScY>CFmS((qJjEdIQ=(``?8j?Nt;(XFBh$o(=&aC zIq6xRHlp9xR8~N7GEL6s)`S?0%|HJxm`L--hZnO5hCZ*Fr!!;(v2k_*_OJ`!_rk_# zyju0DFHv@9QrX80^fCrKThH)?>?zG2M!vAlyVG-E4+RXDcb_W&z?{Xdfy%?4kT&{8 z3kb40%*Xpoi779=RH?C_#Gh`vUV|KtTbhdn+}^eRi~*YK#-Qz=zS}uojCcyc8pcW0 zy?eqa!PZyV6C)I82z*@MEWl5j@Sx?d*=zm$xW{Jd^1{Y9(&zRcZJsh;nekqTz41c? z-K~zdmn*TgO_iTqiFY0GpGA=wb!lF*!n1P>4m-@SJ$W|XnMSzT1<_P3shdxgo^qCG z4W$&^H>C+@s1D${aE&J>bfdV|5{x^$i*EcV_q+1GU6Ct?a6Dzl(i;SiJG&3Cpz@{T zF?41DMx8Q&Xax#5U!K3vo5#HKIr@yi`mUe>DUwV`u?9}Bp!Tt@ScA3UZv3_CT|#4R*EU_S zE`=LiLZu-AP?&LQ9QUv&Wv3nv{>zwB&#fbPdg1<#kKF%*eqq659d#EN!P(80KK{`& zSoC>DP;Gkb)W`L_N{mg5M%EoxyHX-K z#Q7tdN$3Y`-UmOR(qKDtiNld8tkvA-@QvS~>W&eU!5YHsno zb?s-0lqFvN_snLs!PJ;1UEKlM9t<*wdM_Ab=wH?IH6YMGU$avy!=d_L+cAMYC;;z( z%_ssGTOp8HCOG^LMtJ{h1)hKTEc%t{q0<|qj=+hEvhV)@R(n>Xag1?8Mtm1lEU}r> zZsZ=PPV{m5>kB}hQ|*aX(N@3rz$d3p@@xt>4GW?PmaB2^U6In@cvp8WB8ZoXOS$*g}-n(Lfd5}-l2>f zmpiw~4HL6Hf}+Pcc4Xv;m3^nx&cLotyBVMQ+~tvO`J5IyNdSvgC*GlqX8qndm-a?4ei1GciY|G#7l+~1!1;Q=c*N{ZVWCYa}I!h~dO?0%m z$l~mxP*;cs>_=Dl_xCsELy>gMLYO4`mWjD$@6{O+1@%End+cl1#Hy(MWakj#n7w6{ zDpeSSnR4~;<8lG7qBhdop62CNYu4Gb?iP`_nCAUUy)w~#0so?*xCU{Vj92pMa}{V<*kN)=!Pd&U34Wf_V}nN#fkNK8-TTz`(v$g299Poi4EjT@z}Xper3Fw8 z^nL;t*|I}J-AvpIX-OX~PiI2io@^gJsJh@l!>%{v>izAxQ)nnF%4BJ+D(v}9kfJFjYPd4?9;ilEdP}7%i zB?%ZgpWzUhMy-bbcCyqEra$9nbH(u zwa`Mr7G_KyCSu_DQub}p4E7K+82cunW7{J)+Qbj|5Ec(b;N;c}Rn0^@(+|m%LUW*u z-wFnezCM3iAu0lOSxIAmqYovf_w&E&`4 zYwNwCGH-7#=zExI-_#1}L!!w*$aB9Dm3(&Y7QgpW8!*vC(*W!ti+=^=0epg;I*-%9 zpbns7FAT={|B*70L*O$S*n74Ln7r}kjh_0o3#s==KOB7(CrhQ$;`SXXLYN27wm5MZ;h5hk8*e?=jh|J6DGga_y(wbV-&6@ zR0XXOXvBh=d;=9LEmO`o^6zL68=Ej48MHc*c#YWD#{8k9k*EMMzCIi`P2X5Xxs0ho zLU5u^o`k5`n^6u1S7sw(^hna;TOl?Nu6+-`N`u40g=UN`sQj!K^NZ?iALz7UGF#B{ zk#rZDL4Mmul_IEBl++>-I}r+lh!bRL4YS77kC$ka58QY0{OGk|U{A`94xaFkSV+eo z-GGl3maFY z@Y(-8WWy$!yx=Dl5+#}~*s%v)PyueoFVNc;)lTMhf0aBP!iw^tr_kbj$hv{in3now zPLVy_lp@#LzxiR}%lYQ(u`-O*=Lc88c)FK;@e&-u-?53TVn4xbL5PY0euKElsh*IU z%t0XegISbY(nT{r%; zAdVm2&iIzYb>;lSuai@`dqAFiQfYJ65-rcP=I(~AB5lG)jMDiF-lKF`cX3e6w5E{Fq5^g-S6?NXruKA_7*Y(V2|Zl z^Fo9V?)JA6a=k=%!>BrtO-vL0@fpM042-1|O&iC+3OWy{nG9p&SC z`fTxHctyDuAats4pCRi6^91T&W$ckU!&a)ZC`*m+UiTt`vJmn>NRmNA@{Nouz~t9D zNJR5S0GR0sBc~xE!ko3#aSfW(R0l{Ca2CtYgP2F zH)qQg##$S=CiHKgp@#Zr=kq+k$qKFzCr)52kaJtzXAxF=#Jr4tLR_dp?LcX_3}zU$ zO4=w(wCEm*tI9!f(80vRy9*F0vKmoz-WbjJDF;I3ygd^pXx0~=g7*=*wG?VUPmUZO zt<)XgW&vbd`aLw{B`PN-m3Ty0a?@;Bb7w)QRM$%6y(Gs03&5|k=~`NVoWJ2l^^&a4 z+Bl+`9idc2u4(XvLf!iTDpk3F-jf9LL9QV#>dgCpLb7gAVZrJm>^YaPHz-4hYWd7@ zV#U=uD`1nXk3}k(gA$wCT|Xctvdwv~B<=OAkz#KZ$*Pz?T1IF%teg)VVM%-^!q2cP z3Evg-OKOwD8_0m_7k=Nh+$6VDM5L2+^b>Z1?6^R!C;=Bo z2A|4fs~zm|6Yz16e4>ho4!Fj^%|Kgog2Po;Y-DTe#dPR3hWRjD$dR5g;{cJD+mb!t zVb{wmc7dl3lXpOg!DE(Bc7}g>se`;07wJ14b~kU_f7rNy>@UaN`Y$`V-y3}EG{gJ@ zZk5J>LY4q+N=+5ZIjBRnUbAimD-)45h+JS`{&ckIiLUW{!_^(<85>%l*8=@l_LR=G z-03F0zU8q;x|WTKl%oMAS-n>Tn9Ld-KKu8f>iCGKCNr*7|E5t8R|1^v314+Y{F_N>Kj%>F9pJqa1nrN?VTNYDTm*m^>_8^L_tj8_+zja!ThBW^e+q|VVp4M< zd;cUFz$C`;qGAuw?L|c^$u((MaL0BEXe2w7tnl5y;*}IA)_CY|E0i{3KcIdQbn5k` ze_eE+vL<`_9O<-rLHGgOF|t*!QfOG+Tbv1laMygEzN62NJWUNpem6Zimbv<`hzB-1 zs7*?o`SN~g9Q#V{ACmn%E<#U8#^x=L<+``nS14md zt+75gF+t8-LHf%{0Z(^190I1hgZ_&rDN8~6BM^9%OZp8GgyTyG=?FHdJ6JCV04=*4 z-8Q`p72;LIvaQEJj*PNJ&m-R8qH})~FJ*=`R4So^;Ug5vCnA_HOd-$n?J1Sh;fr_~ ze=Rf=nzU>qGTue%qr7m77b$FS>+`l?`qDgd=gO^}iw@#kFLlUZH(#nvmJv5Alc8V+ z7;aW<0%-~XPh8=Fc`)YUNg5eveeJz^c(Bkb9gVUll4hl3?yjjUY1BPV!6`9QCsMS8C}m)XWfP^Yy=0Y%HbN5P7}F8un1(cOa*#;2qAa| z;$RJp{vHYnNZbiy{Xd`b?fXQ4V>A{+uT#zBR08@!yA_;L7%+7H~G1e{YjsehHZ zD5luZh#3-oN?#?JD--M?c%oc|DnY;lv zmU8Q;u_41&w4&`@*W~8wx63Oc5r^0LGE1HB``DBmby{PoCI*En?hs#csXVDj9<98H zCH`7>i=@w*IWH&4Sx!5U(^+Ry)@fjM`}|3|H;*7c$T`^-#e*I^#vEfNbz5m*(6DKL zU&b#JBW*MpBa4JuF%eEE#>riS#4KP5{Dv;Se*hUFtJpJtTME3PLe|Gi0XTwY^~ncf3r{-Q!)0zWfTd)eoC9 z-DZ3E#B;MgFAnI9*qf~ud-Ncfr&yuUx7QySLbXQ|;{65T_!zn|nMQ2;0;V}Pu`u8f zgPWdzVBgmMG}};Dl@dS4uVuD{Bzw)X*5%NMI;Au24M^c0_xmQB0nLx1+|(%g6PHlsKnN?An;2q;_;>5 z2lIAIGwyVKXxhP`vp);y9djyxIG6`9>u}ghOcg2hpKX(PDQ`H`EfbsTRJl3Edd@!- z6>q_$UkH8$n$6doWp5LO${kXFcvHz{%UGNf-I!jFdOqd%L;#XogZaCX)&&CKjZ~oR zeF!dQCPv>sXj7zIcb08&0%my+2`JkO@$PSd!hw?MY+lromrdOu4H8Tjvm8VjaBh7# zu}%X%jQW9(NVa2KF&JF~PqQ@weP~GL&;9UZ5tK5@Kf&>_hm79SKHnkD17N8adXLQ? zQ9YcCu1V@YrNOI<|79-Bz8KVlhHnuQvf*qxp^jE5225>EZqpfPQXL4AOY<{_bDU%f zfqE`~L3pqzd~iADAb}iHxRqbN3m`$=qRO3BZ=0Pkc_GYZ)a zJ=Q`Z6Fw$o7>Svrp(SD|fWAXmqf=kNIA}vse<1}r5fyJ{jI&^6TK2I4;Uf*q zp`ADeFs{4`nM%K_Qin?`z(N5I`#{KinIF1g^oTBO*h9DIfv(ZhO9Qiir9`T zLG6SC+qH13cfSGhlr9|Etu$N@vYH>SIK|>a_O~BWALPJ!m!BFn$zBwNYf3sj@ZCfX zhB6*}*rsbVlyAWuUnjLjY656EHyfvTM`qBLhvUwS$2m3J*p=Ios~w1IAVRWM|zRBt1((z}ofvzw1>=TR|GCQj30(TBcPD$4YhkduFP< z$GoNP;#l3^KmQE$fB>q=Aj^Lf#j(g$3p+%GTl$_I@x&M3%6B!Iy93S;IKOTz{~J*Y z%G6hh@)(78*s9Ap?poZcxpJ3GkFY+&O@DTqH>5rlaJPS{moRAGU?6&3BADmY@Jv6y z=*JM$(b&e^tsNR)tOg{S6)k3*ST;6Uk0Jj`&NbNe@0birdDcPbH_0C=!u~*UknN}u zF0<*u%a#=XmE#2dVP5yE^m~?CeL=G%0GORk_!#as#JSLK#!14A*J4`sg74MuCO%4buSnf}-6=ede}}7T;7Z z;rp5A4WC`P+ujiNe(8OOw@7XE7BP|Yd$|DfltfgRn`$@ornW$QiVf?L#$#8%v{BqT175)^X(BEjrwo$$ z2t)*_O|I3Q2$r$qwHz^-PjO-)N)AP;b{`-`n(Ra;{Mf~a`&%DUgGV+C=go#3n>PAj zHfV(#o&*V3+G%WQMTn0?fjP~dFL5b&o7lLXmhT^2p~!djcU)cK&RQh+JAgJ$h?4IS z>$rySiJ*Vt#-`#l#9d)sI&U>kg6};iwf?qSEj;!Ibrt(vy2q7oQkNUt5HN00 zcu3##l)z%jv%WmMhEqPoes1uu@=841D;`XB_ziA^n~%;w=N?`nUB_g5WJSCtF^wl1 zBviwyb6!(^$Ux<=`F+lvF1n*TJd$F~)1@kxWul*^de=_SK+#(kapL{1*p=$}drSFR zm`KKnif69(0ly?@axBfkU7d$*crR)88x=+m`18kjI&Na2;*!Mf{gB#=K6Hx4bTsoz3PsL znNZmXDe33Ez^&w>Wd>Y;>V^{}9oKF8s>LEatYDi@UHDgT5Ll`V&qUOGXpHj)>U?wu zJZkfS$`cjtENQm~rSCki2B`UyY5D%@YO`O+p2p3-NY*{G7u#*#Gax^vo&}9C!D*q+ zxB3^&S>{_gfb{4A4FNm+_&?M9wQN-dJAq%7f1K)m=HO;9HnQ0W{IrCUiC$7V(P&?L z)r~}^>&J4Q6A{~SZ&Q2oQQM@~Ty|KPMu%iszZ1i5*RqZOd*S^Wn+ipT(n2;*b)Xxn zIDY+ip1pmwGNW0HLapX?tdCmV{Q4q;EzHH>w=HpL6F9Ug&Av=atWX$X9K(Xk@Hy=w zr*)bQLF}vt4V9A&NB7%yD5&viF=)h(7L=)@wMh&$E|?^5T@c``z$v8%Ph|*I4oR7m zp#62NoF&5~G=4n> zyFCtPS9mk9h<_D)5VL4)vYpYuJ-%}O{~-I&_7NjA3J(TINw* ziiQ|DTZ?;fRgQ0kv0D4Iu%98yFr#k`c0F*A>t{5FE3@kz?(Lwn)L(?&0 z8VS3=nYQd(h^jGq4}!VztRbQFCr@`r_wr@gcfR3&kagFSXV)IePlTZP1UK8^aWRAz z){eU7gA+Z#S;ajyk_ z>nQ-g$jEfdxOh`34(+FdSq-Ay#uqD~pmHHynst*-5|Nq(l1>+%HO&MEy2ItV>&vCu zXH=pCy(ab44YIZXUoh1@uJPH418ukO#Qjg1G4OF|TAMOU-t@?}19$nGkOIs*F%h(c z{3lU{kjF$08o2yf-H3@MV4CdaizNH3gz5xxm$a$J&*2wC)o8$rLq|W~YK3s=z zR}k8|DwwpynofNurT|puUq?Zio3>Do4Sklc4##U~+3iWo4D*(#PGo9b~FjQUq{h|1)Y5NG9*4Yz3!>Y29caPlx64GggSu zsg^dJhfjxuVICEU(m`UnM0o2I8?$A-8~9h>#anec`)YZoq(qO~=2u}h$?AHC4}M-x zCL)G7%n9@^oGjwiIgr`00HP0RAjllLQuyzF%OyvV3M!Z#SDG#myTcFNs#~Y; zu9Dmj>04bGC4iy5RW?Z3eeZkfaN>AgpLB2P(NX4~9)btM-TYe+jk7HXR*GhRIwP{% zX9xJZ1-R1Dl#o@Sh4w5*dCIq#+oa)Orc5kK%Hv`zD#{IP?bbI^YyE!y+Jc!$_b!yN z8~d^?x_h;}`HucHXaaU>owRW(+&zAIhTOuVXRPb+>$p_^GxqK2z*Y&C1^WVC6*5-2 zy1j==2-MKRXizFBEP4nJm@uNRYw(giA#LFOr2y}xshWiUv!|c7z}Uoa$O~;8kvzQ` z3EDs_3;zbTbr=P#^Zle+-#~#o8=5fRsNq`!HVTrWy3o|QzZJvxY84l%uM9jjUI=zK zo2~Q=DAm&@0#vSt4jWq&v2HvuLN19L{-b!c6i4;vU?1zM=S>NgJ90te!*E4A|Nm

M@qLNk*k)3^O|<`icgWsY#3P%fJoMp2r70xSqasM)0w@DVfc=lDTC?tyzo) z+n(r9zR-z3(&K_};XG`&D!;gy$ZZN)Nj3xn4DvuAT3QWgShpx3{#`Q?(Ri!uqhB@c z%EW$*@W1I5*p#H8qCH+Oe=ffH0swZ&<+FAOc>OL1{eWM7&@$D=Gw0|;%x(@tS z88K&Bu%Ur?VFUROA5@F8sZZeA!swVUCO*yntp|k!dq%Jmy(3nLuY&i zS6YZ~a`n(={)TmpUn5rzim50WwCpfd;9x|v4E6oY<(i2wx@H0sz;Vc}F~-{O%y)su zGFJ6nshLz~A)`BpmPH*E*i)~rGvv0O-5?A%#8sTepFh13pw=2q9)m>R5R9bo zg{a0_NenEk6dD_V3zKb-5jF_CR7`^nEfsKbWQ8me!SB_%^<)oOXmoCB9VP(4#u*gj zMd5s}UGe!!s6v0n{r7b$o*d`1H6gcn@n&wEP|-@BlL?+2mY?COORUDqiE+p<9CmQN zH_sX6a2RI2S%ic-zYbD)`i-p1x|+@chJ)@N36&nFO=3evOikqRJ@pCr&2 z=$2ETdBmy3u31oV$1A+~B6UO{t-VO%V+szJ6WPym00DN;5JVcyrwW-@pt5$-hWZlp z$|uv$DktuivL?B=m0?_(J3{rud%g?u*az|8(f~069R$zgLd6VyB5eBv+j-J0cQ9+qyI~8-v}?zu=C1cZVo83ONadj%@m9 zP&ge^K}=S4edweNEQfIL%-{tQX+_a`ak*+A+Sv!aFA9;ID|JdG*=-K3ggIT=KK4j zKc?r+p*=d)c|;Rc4X3`NvLi085Wrp1U%&#qlF^old`exeHDE|$rct4DW|Ro5S3w($ zA@!QlN@G9WYhkpqwD5qpGwKBfEfyYU_lBSNj@DEca6XFUbW=JB4Em|fZbIiobZpg? z-+WY<(|}`U(t78Cz0#!J1%8tsHO3nQU5?unZfiz8{fQVBCHpTCB9>5SGpz|OBoa836R< zmYjF2;gjJIYGIzl(2DN}n|BghxhTO|o+!qJDsflrN!~%tMPL6*VB6E#2B$Y&!qLsJ z$3m~%e%HZ;6tlJsql(&dR%`0IhWM~uHJ>?gFQ>v??%>ZgP%qg1zGK^@B0u!P`(dI(&DQ%C>Y zoF`aokP|~_SZuQ(xo%Dc6=1(3MYj0w9~r7*p_-~54L1edp4D#TnYcurQU=?I4l=OP9N8GWo~BS!KbK(;%cQYec4Ui98H@3@~$6h+IZ9u0k^ zrK;i{bV@}`RyJA#O9%FV5S!{+2! zsnIWja6ognCXiSYI$ahJP?Gj3tKaY5b)+|5{@kx^caAE2vNC z)n`jEqdi1^Xgh`Y3-Z@<9*vNF{ZFuz)i==XzzI6A08h^%g4Y6#+Io0?pbtpjjh@bi zuOdKXvVkk*A?Y0XAv3zP@4*w zqg=9YDY31>{2ev>ndc$fyXzTSZ4o~hFoYZluUA>aO{s;_)sLV^SB zOj?p#BpTaYw+c*nKRdX>K4Fe}j^R0|6;D5PUjmf-_9GF6Bce!?~baLSarKK4gSUUD^LZAW3kj)qh-;j-4yM zAR$=rT&{$w)W+)$I?VJ|>w3;_PTP4t3crpjMti`Yh zR@vL509;z!yAfnJ1XO`$uN+Z#MF0k*ZB+a6JjrD)bq>d4DX-`st6Tw6-4kXLaqGQ@ zIxlUg6iXt?U9KtW6w)cW>6YX+Q9$@ytjrqo%?mYOi?-snRRHW; z7ihck$A)Ll(vXF26i>t-)Xl?BY`9eX0Oa|wQ#B%&=WO#nmg(q3pA!Uy-!gl?YGnIa zkE`VL&2fBqHhzz&H^Ky`2Q^Z1&$~qI(IWs^w1zrct{;I&&wUL+niUC>TCp!{LoRaP z-bnygSKExys4Pl#K8eReK2tlhNJsQKV23UAA!FJ&)-|Gu`2HVAh3-3fOx@We42ei= zJz`GD3JPZadFL>dtV{=8Zj53!!?1L$&)~8L;Spu+3gVQuJ}fppB;A44;e+G zCeXJ%=#(|gU~JN6_Y6WY*EqWvlSpce!eeUQbi2F(xmV^JA)W-ADs#Oijdei}WjFDS zOR0Oa*9U2-M+Zr{xD*OJ(_G2hYG`hRpE!cLVs^G zC$C(`hdw4txdTk;n^@i4u@fxj<0N5uZaKCn>-(Ri$*jssVT5$=9%Stq34=&AsQ68l z3+x{laQ5ppU9=vb*C(jE>XiHGdg;zx9hh#w?*K{!pFK1R8dy*xx&a`><;lCrlD{EDlTHx$j?mAEz zWayo}Dd%P>YG%atyx^l$C4aws7vPVDi;l|%yh1YtI+`MQP_lwls0noU=n=`;n9h;z zlxUY0F>)7r#EqTrutj3E!axOfnVYHity*B4RM;!BzM#OZAMv-1CeIxVUS7z%L4xtYoqeH!n!aG%+ zD3S>dEe<>P^L0cKP?W4b75MR1WKz>wK|ei97cD3xPam~K%7VHArsJvSKMWSKxs6qD z|JVfrs>T(jEv(+XTslm3T%yi@l#?>{tPPOEZPXVS&Qc`LaHPX$IcZcA0v%<8RH=tu zS}W8^Chw9d!|wq4NVGJM-`wBv$>4hv&9LLsb_{LajgmKJ=i!k=0`hJ42GW~Znq5 zt0{NL*Cmln_(j1>KOA^+XNhMWtsj8pS=0Rm=>@I+ikZ{DQ7~3(7-w~Mh6gf@Rw4#r zATYx;(9>rFxTaBG49Hi{t&u0^!QaEyK7s@h`7ey0dQlkpiFunA#WSA~>7664z=DtC z!P_J`EmPCrb`=q*jt-R%M;#tOzv#ka)VaMHmC$ox&!>b-Q}bJEx~6M( zjZgH__?UO^NHU3FtoB}CfJ+|ulV9-QEy4L@YgE{>HXW%} zAt_vG9=aF1C5md1@*wn<0VE^BO(tYu1U(LphTbs+IJdaHhJbz~$mi{lv_n}0ru2bI z)%+0)Ae%IBSPl|t(&~iQUc11vMIpP;e(~ho52rS6#93QFCHPX z<7_Lc>i!80hpAU{gXA|&Ap*(6mwK+$dkd?#bn9Dt33u)hzql#_P?uYRNZDzC3Wihn zQZX%~1?r<-@exLhEMfnJbb&|l)4pbqWTMDMNXfQF_0adlUK<2Nvbf1VL*$8+mvKFP z#gauaHu!I^434 zjBEN;&7VOYd)*CN;bCKeyb%u>7$AsmrA_Gz08VnBp;w*0NDM%GC67=KJnH!L{^ zaq?hEMARu6P30*3j{)I7#YH*vvy%BF85cwC&XTX5Bq6n~DXuU#*OyN(_?j6(BDH8e zH?Q0b`O>?2Za^I>Sim?oSK6{ZyWmxp6BUH^KK>YgQaB3aXr&o$Wt@ zM?%~-*cK*R$a(F{@EkM~M3#M>J8@$Od}y&&kE4XoRlR8Hpye1%L?_VW7)Y931Y)EI zZm-o4Tqx)}B7DybN%73|gwyfsgJ$;4@rN)ghxy@oXFM&tKcxQ6_YPWMN;-pwaj3F4S4F)`dn*9ra%3Mt#H9P+Uv^)d{@ zZ|1C`LIG|w@(4=?C`0rhqhTSu0E-~Wu1gJQs~efD)_E(O6X@NjPX?`4)vA)x>8xFu z=B_FtP+#Xro@rl$hFrOQvJc(oMKm4m=(8DB+4(D->h?*R{7V(Mx1)Lm{FH%VwLME~ zzPVUi<(r4MR49>exz=4~cWKlfimD6QtM=tqTLB#$1Ly1Rbi(PThhmWDpZRuCP>%XHB>?gJz`lymUYd2@1B#I|rZZ z(ogxCmFN}WH(-NJ(*5mJb!~)^Qs~GLkPg8G$e3F0wX7<@eNdLhEZdjf2B2+O$y+3|Q63iaVdT0XbV z$LFbzz`}xSFL$UYx1S7Rvbs7zW(01y#*r8Q0mcRlAioU# zJdk4(Ab~4GGUz8#&<|*loh^d>VVXvbURgebssfgW3fAUL2qy_S3QDmP>=q{=f&9~t zU2vpPmrUT{XaCo6^QtG%Vw71u^pXKTPVac^jFjJP!#h+Tgvh<^Mdm^mFrg~N<%p&2 z#eb5hYLQXq0^Na%yAv*R2zPYEYklbrVBc7QN?XUHTAis?RZl&Xj_{^T0?6BAO(UjM zFWI)lFC=QM4EGY77vdg_=PulQ93v}^Idb8&yLGl6nz3~ZFA&QX(Qvx08lokqwyRTR z6+j}#B7%j5)sxd^Emkh=Sxkl8J6`L2`s9Ddn)!SW`Fa;0jwu>`$0JvW&a3Z%)^Lk((rqN$kd+zfbq`>SC=`gV*n$2 zx%{&xt7S&r>3y5jnV9ToZm1FvkL_cEBx<6sA0x}Bk$K1$#cBKd70H9jLm&;T382rJI500s8m;UrZ;bGmh z4(YpZek1x~##{v)zeYGB_nIKl%3Y_nR1!!Sl57wpU+*_##m^A|b(xtWZwwEUZ%Nkd z5!kAlo;>?o$>%As&>|l}A>3{4a&AdI0e7(k{iALkZ5Ypw_$bh~&TySNMI(rW+;ix! zwa+GancK&8DeyLpJKNfT#WzGSTaaz}ba@O^`-sY%aWoZ?CiBXl4@HodjLq$GvVkWR zenG!5rzrnTwK-5D3`2HZ* z!Z|a@p?r4cXs}+EI9;k$Q@vh$H|h1p&Cr(lABv(UpQaEpY6efFakzUdSG~o?gK^bS zmF^#rt&0cn*NUL2<22o2t7=?QPO?&A&W_+qCj>`(*b7PjhBN=r@r3lC-ISkk`l}VY z+isCIOIi$lJuRCD-^m3S@433d75huRNe4x5$(~Rf*98Z5{$$1T0Cx}fLN?03z9q)* zHk%ym$cE1wJ{oy~bzv4K6a!H^%T~SjyP^#W0da~RWc)EBBAua<_6gx+#KI%ZFX>pn zLrZk^?XZ9$9`Osk-S3u$y!4`YP0rKrt^wn-V_=FRlNH&oN3MlE)xf1j4ISH9i*(EE3(@~6Ui;U(A+qI`R# zYFx{g)9{LBWm&MVdXk}K_TpiY+)uEl#C&+?ouno5z&O;a-$9N{*PiUYeOKp+4|>L{ ze!ka0hE=|j@im=pY^;mGbt%!|JpK0iQU?l)*raWnKD|wVS=^1CXQwAQ#iHR@{=r1$ z5SXt{C2mAZ=5`-kc<%?!1na%OICmOT)9r10Y zU#}ja>`LRLhS+Q8R{z3ivfk&5Dug*qv!AQ#p;!XuT|dX)6Zo2q9SRfctl@iHOUEOl zyux(mA|C$<`Ml~yK##cx=8(>cC!C=9M_-gR=L$M@Zmmj`9|R zAsfRN6?~X(T#}M4u`dC;O#p7jps28R0^WYi^`2Z-s7i9L1%~kEhi7`DcTuNic==o{ z`9H8_cu;xsEY=>^t(?B7tt$_no~ixKHRs2zRZ(<_1@1$<**e%ur%K zFHnB_{RQc`pCJf-tZ{|rs(oHjo-}Nb7EI zt_@7jEj{-|a0+GZzfL=T$L{{x*ymy-AZBAgPLI^W<@3=?q845po~HKMQfDHAHg4xl zZ&IOcmd^!b?>mP5^c(TjrXotevxE_gAbi`9_+mI25G+u^tGrR?6x<8=Bc*%tFr{qC!)v@>xv$V&CQi-g zzwL`ODJU4vvjJgoB1s73BYnJK7`dVcKC)$n9Q<<|>9VHu3>0mhK{ns zTIk+tajGG{)`-=b)vR4I6F!A^%w{#HPLzSb|k)Usd zPt6S!ic<F+CI6XshW%(osnT74EN#Y>73Yxao z|6JNUE`b@?WX&cX=B|Sz1TQAnD=ic;G4wrpMA5ppRhPI#3Hrzbh9yVFsJ?{4+#?@p zxiv}|RA*Sn)Z+_p$npE3wQDp4XjXqRVZ*DPE-{N@dzGV~u;}k(u~^=vUUlq5P%scU z8eR#ujxJQNDQ_V~?i#~T_(U7vIuL=sUM(e#ohvNKzTcb}O~(l~!qIddV5PA|cIWp> zp(xj_5_53_p>t!AfsUm(jqL&8W-7C4OU4ALv5CYwUMKVbl)oh5F{_I_ z&4~9x$O8y4M;TGe)qF1V)49_Y10$CVft%q7OHAe*1=+(8{h1DuVwU$~2wAZ!RciQ3 zPYsW|M1Nv>>ROp#Ay!u{Z|++}B7tQFFGX;Z&hAv&hl~}n@USADXr|$IpCN0`rA_fq z*koA+R#~M3Cc$tk6;1ZK7Y^^I><+&7#}V2W_}YUWAq*J|LC>}=b>P3>&zb;oVR5@V zxE3_r(jpl=T4nI7)7N`;9LrVW zAY`l4m2IJvMfOrE8t1)p`*8#D>us5{<#nCnbg8CA?Vom z^58x7Kpjq|=^kkU5EA=Cm`wR25U6)HyJ*sEsycCBzLC-D_9`5=Pei|@gYr285T{cR1~C=L{aQ&jCZ7{H4dTDz<#HkQtT-l9V$K@6;g7b&{2g_(70V1$Q4>#{AQ^vRXJ zX5EkLp2e+n*&84{0RV2(H|3z2!Eypio9qC}0Vho@@U7&yqX}gno_Me!7SybF(!{nM zcL8=Q^fJ$!%o(#!lk~6&VA-Zxo2a-?5k8hFqJg1nw&u9$!9q2{nN7yD4^|KDz2-=y zZSoTwvA0w6@s3z@K+|axx=^k)CL*i&I@OBzH-+e_ByijE1YJbh{?Pt1>1}>5Y3Sq` z)7JOY`2vx@n6;>^JZGe52;68QZ%M;tk~_5(i^C>iIBDt45KgBsfhJ-Kx?{`i-N zlEiL75FJvQrVRG^hPJr?c{j|hNk|x_siN6x=Z2$5jC_R8fgEHfFw84)gRG6jn%ChT z`kmVX<$BtI#aYz5e!nsm6Silv!IQd3nqPoB`Xzk4QXcBfn(demISFlA=>f%FJkbFu zE=_msy91wx@wie-B_5DZko1qi4#qdX9sB=PV6l4fVB&1rtHGXp%g=|v;^4>mSA(wF zK0$_#g~&d2CmeZG?WO=7{YBRjLs%ZPHo;m2=uC|MoU=!$rAnB-4#YRPn*0ESNum5L z>J1Wm$$G}0G%-CNK1|Kc&ZX^bR0)bIfv9|7v%L^!gPGn#=$52pr@wVPRSPFd9}Pm- z%SUKO#iA~N<>+&JG6+|p{!760jqDlxtc&%A=M`5BOONu&$oY9YX5WZT2^h7-&K~#36NQvG=TYd!kPH$v0O}z1$lTuB}eIJF(6F4&+Ifdr8Y+U17d7 z$46(-?j2eAW%qgm05CW2SZ|TfPcIG+zPIimvb9uomrhRlFGn+Fom?SQSsk%C@uqz{ z7@`5HeWct7CE=S{x0)%XsD+-MC?aE?t!f)bjDIed06J>ue~b;!{!3 z@d&Q(BSbxBchmo+ryUkT{Kiv%uwC4LF1Y1ETBvk#f`-M-Px313=f8#1u7e|C%5thqx?A9D?am? zYMJ5*6)mj!Wm2BM1+9c6ZaKQNU{7&s7hc|K15#}AfCsqeGimHN@=gy5H_K%q*Qizg zEt|17s3DhKV4R5O246E+6Khl1mWmY)d`p4BEU^Gyw6Wt(HG2&3@`1GSG2QSq&6xK7 zka4j>fVk02j9QE{&dcfU8^vr_xGVH{vsa7xWnlm1^< zFwlsPPlHs-DiNjT&CaQHt)Fpq*9EmmA_6l^k8>pd22(lI)1#K`f9!&2l;7J)g*IA= z##>)Z94OTTE_aWSF0_CBNxJIEyDF6Cb4u1?*L3*G2v+fl!7@hVY$|mDNR7+X0N<{d zvEHTyo70@6!QcP+aDSyr)Sn?crZbKlF&wG-vP<71UxE>6x(T=A3ipI_zk~nQ0#r(v z6r*Acm0U{zE%jwTI|n=sy^Yec;zT_JsYPSi?7=|NNcDjF2aP!uJsr?M#^SsPxW}it zAiz^)ip2QfKd#_%98&XzOV#d*Z|kAC7!h_>7}o=%y%^SlV}Ks5CFI?${Scodj!m9e zTxGa>p;ffQO@5 zt*N7k(y&QQnSY@mo1oV{T$g?zZud3sf#sllc7LNVGk*dd(e-*(KEp;RQU%rQYWVHYdPcs$W4)eXWJmj6_W@OF>6&?)nrR2+a8Eta zXMGc^tkwQZKfWteL!Q}8b^Y;4PM}DAYGT&aGZhQ@gdyxvjD6MGo>zgiK$ zE=DozhoG}Uv4CYWgdt`R=H@2v07)Y-3Zs6GGH%K7*70I>r;i1+6CBI} zf$iib*_Op(a#b-IxA{^ZTpF1YIcD2gaX_KnrxE-P)A|ouXI*a4@8&>nnjdaX^9f%- zg%vv%F(+;Wx>RyW|FUxkpBz+QHpUnKprYQZ6!Jy>F>^qG&#s{6$)hy$#+*|AirF0i zmPDf#LI{y+c>7f=@9O62GW+MxTlN!ScOP6C=sArlG509Ei&3hx*KJKJq8YB!jJIB} zIh_%RDPR67lspvil0Ain9j$?l8F~>|urs%{r4Bwj_Mq}H3Z9M{4q#5+^>EQgTRA-a z?{S2x=3nzwlxz!ha@PdC)^Jf*Fsw9OTk2%1CUS_$$%89jJJ%@vpX7k#XT9odZI7EP ze%zwx_MqbhAukiI+hFsRqPM_G(g5Scn8q+pOR!)A;MJQBSpQ5y5N;ibS-#5CVsv5= zDrH+%DGyp>V7C*JdNIGyV=X6Sf@JQ5gh18&AH6G66e45}93>4ZG#g%7Eb(QzB{0=^DGKlnk zIU+;XFaC(nLY}K>FCix5lB^**XoQH%EoZmzHu1ZtlA|&7=%*(8)va#h~4z6PvPQq9kv{O)HIWLYS1(HrmaRrvUgXcsjZ=H-ZMt981cEah!Uvqlb_q+9H?fb5l^WQ z>Zq-EsxsFD*vYOjmoA>p02ZIIpyE6)JoBI;mK;p7HH66@uhr&D!uFz>yOfzEI-7p9 z$3c%46>}oJq=dlvY_&Z4))k8DDYda4ny#UXcii7kARDRA6W7Mhk?5GPFL&e`mjF5F zE#piIrcUw3#^=4}?umAqPh6)~2Ezj@W?HY7ld{a{QY??$t$G9OA0h7Nppcachf{Gr zPFr*icTdV<-v`e1L=oWvm*3@$-)ow7+rP7pIHcybd*@CTAV0>sTYYQaj9}zF5M#U{ z#y)_~O)N94JxiFj~&u@8xV$Kly zFA81hp|)U#5`BBOeq0k3-$MXOX3Cr!m?ilC@+{Fn1Z*5W;JVQ>L#9#HX(b)6C3KSlY09h7haimsyzNA^KC_V0ac1FyyEvNgLUa3K!3JMR{`A2hQAp3FO}oYJJH$>F6tN=36ExK>4MfaF*{TMg@*dir$aTp-grs{3W?f z9Oj&i5XZ^fzvJ{|xG9Z?9>BVgFUqD`ja>lcD4%uPM4K*8jj(;@|9~5dGi$TKQ`qSU+Q^o>-;7XQoUus-4paEh{Igqyr>LyQ?SJ;WbMXPYl*X~s zz_WU+g8P3fOw7RQa}O{qiB9Cet;q=10A=`UKHvRkJ1lyA`?2euC#0qE;XFCrWQ9dL zq&y6aL$?lK!nM?os?Fb7cnsju`2|&KTVx0YQzElYIb#_UNkPl0^!@CY_5s&$M4UTj zgx+#MogmWDJI%8Jb&;j#qJpU54}m9#L74`o7u<^7q4YP4G6ynPQh{%b+P?+DA7Yei zc_~AQ4Nqqd{tp(NaA&ZvJ`Rn4GE+}rg~}O&TT8zbURfNL>OA1xf)ipUzclZE>OMn? zNUUnB=(;zduA+H*OoT67&j;4dohhVajzDo=htUV4J3OuO>r_Xi8q%sRpZ7OZ>|Lp_ zQyEl4JawwJ7c`Icg4Ok&>Q}4DbqAWWWF5%xWS*<9a3bVkNNtTy4k!^i6^>=YLNDw6 zGGq6p%3S^1@ftu{2(xN&8ZQxCzDTmT&_d|ViY@SZSq+og0Imo@>U~V;NCQZ=7nsLe z>h;W;-ZSBQdTzBC&l>T0cR6?lq{bu6AnTeGj-r+|=$`+Ekn3oh1k&Y<{jN`~St-wI zc9g=GT_xB2!)9D*E9R%sYepDAQqCXToryyg-LJi|q^>75M=1U38M`1zLuc4?*Tqh< zfL_j1MnT+^GP8#gXHV-Ojf>eF@E6)F43~R;m@~-*`Nw=AqY670Q|@@Y(uzw|(s%RJ zs%5zf0P(mZW6xprjYn515SArx{!KLHv?|nUtzr&gwX3$YwkjxWH4H#C2w}VZq?-Z%Uh(Yo9k>?xfZ-TIN-+TNCOM0!*qE)2#)2^`Fz3(4YA)UkDI& zhH0L??amry`2hD>Q63C9xa!{-3R=juO+S^}UxK=avJ3FDh1G;l1WF&EUsS4x5Mj0F z_iPCpU6sKYAzpZ2nNBn2w3I94#MC%o@4)0d^>Go*HP$$hLM7YZAK9@Ncp2fUK}04V z)OSF+*ibaVlXB6yCh1czv+^!*(9SKxAbpPUUMK9}%z;3z^9#0VByn3Uw8$Mh%N+Cr z94gmYN5``xRN<I8`I%LHdLoRADe?q`PtDUl+2OP1DMKpChQ76Mmy z50=(Yp>yqd4@A!*nwPboNOD6T52ynlwTRJKcx$$RK&rd7lRDT?ExAb2Q1h&Yix(d1 z47VEL*!c|ceh2zPx37n^W=lr6Up11Wl<~)E3}$bjyUDUddA1mm`B+Wd+oAQRqk%H; z8g&3nmaKqX0b%|YkI(rnD^Reb=Gc8qT83ni$y-mikn&)>sqpjA6PdehcfupGrQ-(k z2#vk|lr4SY^y&~7Uj#|!zebdMAEzptTvx@jP%xbM>aY?ji?B}bFwr*V7C_~~JVWwQ zQr1)b=d4Uk3?({DzYM|kg)**X*J zV>2AJG9T;~<`$Z&u)k38Xtczw?r$ zmYy)=SJzzbl11G9yfLD)0=B2)#aj}Ue9hQ!Cj6)%;MFO~tp{SG&R;7Dsg!=a6hAZ; zHhLfm<@Kz7h`ThNlFWkWoHV`7YN24`@65zh2X_8_bh5tT!><7ec7N*{8e%u8{r>Q* zTiv@*roV&VxM_C~jppC3heDeV_QeK~p@DsqeIk3~x9Kn#JWL^{I<{B4dVJpps@ zO>Dq}TdH943;;120hp<`5p+)=9lq?SkmgYx7y+={(9$|&&?WUBmRQx_J4*sSA^L1F zwEqjZb|SrgWI^0f1QC3uewDgXV|j41p%4Y3s%gPf7S=y^>i}*5Cc$oY zBiGoiY2#m6Hrx+l-qaSmXdjJZ57mYm4}Gh3J8-Fq1r{b0+SeV1gul{NxcU=%*W#iGvQzpLUE;|zerab3z zNu*(5G;4mzB0Yt7ajjC>-*c}sVqH92(SY?MS0;y$(lvO4*2}*0G4o>5l#{@Jn#%$zYxedr!cNX}1$U-( zM&r0n4Qo+rog*gM+_^xFtyXuA{_I0OM4$2OgtRvN zSx%4d^w2UZs`JBcc;c$+~V z4bEwnm|>4c2wdhq-!-lKSxdO)6pk`YVVkgx>JXjpt^*NIa)6RUi$hM>v)(ff~mt#y%tKG)zo22gKMi|4b?(9shR3?!euCGq}n} zlUA-kQi&G4L>-!Vb<7je_eWW5J;rhifC-!Ig0CD60fVausja9RbnL0k)I z-3O(g8670x3xi-+7+S|2geXp9`a2c|6T;xF0gp3Pm8oEcC>}-`(>6uq+f}!xqmCmW zu>9hX32s74*!ZZBsM~J^UmDksHdmddm8JisRd7Mp_Ssi3E(xglz^_3fRm3)&IwcTU ztkvszR49S&x-RJcb*0Du$yg9aykq}N$8zpEchm!v7^oE|u*QEp$M1SEfVMzwhTr6% z{?~EW=2q*3xICpb0jgab6a3CET338^DYW(80`4EuXGiT%2uTdu1arxVeuchkbMK#JXb3sGiA*u>$sBm~%^MqLzM(+8>HJnTW2B-!KuH!yDPs*q90d2@;^SS?L z0wy16Rov4TVg0IG@JNW>5ckmpiO&wpFsCUnwc9sonx!?HdjMWEUOe}ZVeB0i)^IZr z8-Jq0O2h`#KLA|+Y>WVpPL8~jJJsWRE$i?=n-V-o`!vDi`B@$`RSX{#ui5@#S``lz zppcpKeC!Ijy93XaXA!^j>|9&@iN?0PQU*-A(OGZx9-27hK;i5<IolzXi<&1nIy7yKX$mrN?oC%jxj}qmF+&&I{JpYl$+Upvv=-`+{4O0mpV<&JpYqYsGc$ie`3F zX5qhV!UE;LVhns2768Fpi?XQocT-#2MeRt zXoOh9`t}Jzxhr|l>Gr`NY6EzS+_WU)mXTD|5z!V%4X>b(ZU=r|?$?b~)Kl-day2f~ z7v*@I$w**mQE`6Yzr1$xd$W%>-tpAGf=7Ur$z7_g{{kvROKw#2^rn7utIl+zZ}(I6O{3y{nkDE%jJ=hKWjY^x-4|KvZbIH>=RaR!ydsvPkh%F z!6%IJ10Fou!a`Wy=E{Y%Y}$Qfkglhp;}Ar5es&)i0V|K%5W6_>-$5YPaH z0v1>V2zh|*2A#q3G>ZlP7Ml@CfwK|0ejk0!7D;OWS2>W0qEU*D2t98h?`%dC{Ki+z zy-DmY)4J|J#2Vw}IsMFf>$jnxBR6`Qpkht#Te^Dy02#91ZHf>uCFA!C;i-j|Kjx?N z1W%_Tpt-^%$8zIK2#$&zwI2jvi^BK_t+O*6k=X@cy z8P{eP5f(~;=j{{gdbPUMwDbVOWPg3QIavtgMr^Q;(}+%MyJyy|g7sg+fh_!J6dY*X zTEJzJR3@%+p+NQr^wwQxJh8pn;%fEeta#6I?>eFLK|Aof?f+C0#M}U4!Ttu1gTd~t zmqx!S5qQcz%6&*jxn)b>$D|o>T2Xiars+XV1JxeiHJj{+c0-JW!G{(So6V>$R=euX zK%k^y;`=@>WqJ6eYRX0@&%f#ZGVx)qi9_0>ZPJ9M((4zhE^fMqi$OVF^x)*oCg)j@ zPlLE**uwf|8K_f02q;l#cQKc;KZkY7Tpr0}Ed_1l-xl?mrxYYIB8!eu96&idMA<>I zsa!p(j|7Fc(I5kBT8 zQyGLMOQQO89oL=+n8q^454wt@Hm*8I_wcKS3^w)*7xHv(<0QRp)ldE4zdWVVa(lvZ z&Ji?>_|^(D|H`r}L*(XGr;bZpWm}om?X`vo25Cxg-a0in`FD?=kKd2Z;0oVS_C$ke za)%>3>opPiEyiv?edT=y692E!Dx`x`xaD*W_zY1Zf3O#)o;V)TE-iC)xB ziMR|4mOKQ1g;{1XOX9gx%!nKv9(=y^1Cs4h6LcrQ-T-Nz*-lp2Covz**UK~j3pI~V zpB|f1NPn~%(@wUc`^q<0o18Z{A`rQs+2H83UJCF?$N`tqb@xPzthbM;$1V5^eOD96 zSc!2y2hKu58QA)m5JL>)esyLabBk8EiEyz$P_B{FmnwNLXF75QD!dc%Mo*=1CE$2G zJ4_`fnF~27@>R7T8?r^b82T9@Kpy(Z>`%AkLD0&p#(?q|mh|H+7RWq^pA#oe2yKN< z69D))IUFd;U!x%we{Y7;ZT+~c(|AC6z(+r;sMxU1!-9)em1v+M| z_29iMEYy9A{Ml1UsKOvGBbPP_jNu7&bIf;qos%&@6y2|5q#1tBNeXv{{Vl8YwLU&v zCdSLNRjbFa9GWaUnd{{$Gubn-9?G}f*C2)J+FKmT&+?J0!S}<8W#-nz#=X`R+dbc+cq3+b({BA7qIjP326G z*~W4lrxLW}dLK~X1rzj2d{cstYAw;>7Q&=35Ds;pVwZM1Wah?k4LZJIKXqAWw5|}v ze?qTowt6Jw+Y!r&;Lp?#CXpd2=)>JAS1Du2^~-w@s1{;!31x-nO%>hWP~n8*4#@9_ffq;!SrX zv93K^8l1b=Wyp_6!V9bdo;>ncIW&2Q?Jid{Hs!d=_5@P?F`%h0$b zw&=7?@o8j!hqaQ!P7emJ_3^afK~w{`3z82E4QLj+DI1H;R6q0$r`<<Irlh7?iV^CBW1v*XBC21-^Y!l}MWy3)q)O8TE*}WP{oa$9taa9zFjRAK#>S)k zc}6ziUm`G-%3Tw3AWxfGFE!G^fP0Q*-$78?BQNPpK<-`HQC$=nO@2nw_&^H?y#H7z z1<1C3W@Do%{&YU3BIf~kqx$#-M1by(aL~D#q&dV6hGl>SGH=lm==S2|2>l`_%bH+m zFrG+Mye(L$mwI}&P((UE;FfG79;8j`2iMe&U|itb4MZ-!-+dGWK@OQL2Es#bOaU%s$@r+cJv$2g$&uafbHrO*x@mvd|*AX zw=F6PJFPEj# zYsn4o@nv*ghn_;Mp}pIhx>tTDQrFY=MI18C$e=zEiFO=1!oSn0aI$I^U@Kvw4o(9< z)d8coq$7<~LrSZi?Xn~lbIkzveSz;5p#Ohtd~J{JkiJpTsJnPVksg_a#s|5 z;#%YlxL`~SMrsBILN<`iMI9jB`Bnr>%Ok+j16_pSy$*b?;Egngwz%l~j`#8L!Hvv~ zR!}-Ql8WT(p_*IOrrNLhZyP)}u<&(n!Fj4t+DUweeKe0H;g~e8zLtVvp>Za*S^>+q zm5mtvm#*via4lVoRfm}Y21)UH61D!Tzd7Car9l$Z8tOJoN8duKvhWI~?GL^(Rqq-Z zjIAE6aVDy`P);pQC8MUU@+|gF7~v(Vo{`NpnG2Vyf~&o<1Cs7zQ?9R>YY+NZ`?Gq4 zc%CW?R8OJI)#a2q*o7OmeT84cS-=6l+klZ z`bqs?62Kbu9IALPPiu@VaghQOQC)okdP1A9wNLG^l(iDY1Io1Nw3~)$$#120^78=} z3LJ?oklX&cdk$OW#1zQ)uQ%RalkfVE=1|Fjb-Tq%dZ*J3!cL84zmgnQGKNANboXa`iIpzRttw_0HAPKR zxynXedotr`oS&l~5xY4q?KAsZX@leF&aCSUR3ajv{aUX+3huKwwu7-geLEQ*N(o*t8%rJ>n`o_IY$Aqc`Z z(eLHSToy++)buQmVtUInxz!t zj!QtDz@o?vf=q1D&rnPa1C#eroH*5{9@S9zi)vzSq=&krUC(T0jiWB;0D06Jf_jfF z;qWvjS30IZh~Svj=h}#$A!)okg%1$u-<_aXI9z z_bQ(FUBC7fXhN;5^DqcaP7^pZliczs5c5kMhHZr=uS>nJC6}3js$-z6BXY;@NSR?3 zmrA8Q(?q2NI+LTIJz+CWW}mM2vb(2Q-=5ry&#Chno4{4g@TI1>1q-(3m}{0`F(@NT_eohzf)0Fk{O*8Apg38f-EJlj*9A zv=6l@g5&|`+|~ME%3mrm0TJG@k!ir;q9N&*z8Qa-0glwJeQDBoM@6VA9k>UuPv>w? z_|Zt%qiBR*58sm}yp1Q_`C5jzjLT~~(t-i}pxJ)R0*2fj+2MM*UeG*A~~NS2$_G=I|8LoHQxC@EI-Xxm7U-plUHKpp&135~Ky0}%DsFxd*s z8u;hq3YZUtu1y&`h1N`%g*Q;%y!~Qj2c{q6>?)D-y^oze`&a2ETk0=q;Gk@0`$b7w zmvuFE$RJN5vc{(vjU&oGpeEAW#)}I=#%xlW9l}(|qfmI(@NaHiv`^U#&%cS{mN4b5 z&(#Q(tDx01q;7CdhfOv1RjbTqnLmV=!xI+V$=J^iL~!7ID?m${K8Wo(Y}7mF!3?b7 zz)%xP=}z3L>n={n9adnVAhKOjs|*u+HW9PJLCKWqHgLNDG@cG(EoAXR{v3Y z+en{wN7{jcKUjVA@mE3QHW$^_1^MwJjR+J1bFIdYHQweO6zH!rlGaiswU>&$1x zCvYE-vAFWf%h`WtRr25`blI@A-~0RAoNZ3oZRBV~v*qN6F$mv3qmzdmDd(g-Fj&T+ z@2i*ljTk5Rx~{8n0Kh3{@`U1nXYFBrW)9d@T85#h7pR2`&lu_&dORBhQLb_Iy<6_H z7No@&uAUyS9swk=X^q@V>C>!Mu-~E#H0j8@FGlK>;2h{D;0uUnr{YTr&yv=HoAvy_O zWR>=KxsXDxKT;+C9PHnwp~~=^fYCXmG^4gG-ql*W1O4e3wUht^{H{hqENy(g4b#;_XTbaDV&|wR@$PE7-gYORQ`RVK{{q~1f-WUsEkFm{ZrR1eTjBJZ z-+qP;R0G)ywHlmnOggR`^TlN;fVt-b3m6K5C|(Q&8z5oLTi&(5n_K+6L+W0Ut<%D1 z7%T+mXqcw3N{fJlUnr&z`P#e{M6uOk_YbVyeoo1nCEBAFHlxXVYf+aKXPkPE%(5!u z@Y?Fkfz5%Eq6rTan|<5Z__8;PC^RiR_HJXxDV#e&hezij8<*%>9FmUSwN73*y4Yj5 zy*cWp2uCh2RP;%gDW817f^eft0ZA6=hdjqjWx!{1r8~^jN~M`u7wt@s6T<`d*jb7* zh^!_t?3FAsPvhXU=28(wzX$*6w7$O6wjGa>shSO$7O!0BRAU0x={uvB(*>Z}H=K!e zpx5@DO|b8@=BvMT^kQZk;?8Q1NsqPrjQBJ2i$Ix~^8_f~#7(XI>j@li`^~WENY__q zKJ-^A1yjKAB@X_rZe+(@Zi`(& z$6VUz456i-FRNI}lh(eaCo^$C$TQc5!A!}K^1oa=>LbC?hCW|NOa8;o|Ng<#n-FPq zf(n5`c>nN$K;;U^f8<80E}czK?S|H=;GAv6qfIl#EWm8KAtod<0JEb70(8AOLwJuZ zc9Fm1ZjZQ#t^Nt3wcBlJ6-kPxZBMHTdG9a z({0sR39}Mmqw(syn!88GR{TTvj-vAL$0maC1p;IcLNiAi7=Zo>jJ*-?x;emcI-kQ* zp8bNkD$?sLXG*n~vp+(i3t6gJrMWe$3}7 zi`Qd&z&l5Be0-K;8EWZ~3Un*86`y8iy+^t@E_lwR(HiL>u6Mlaxl?_L`X)mlq+{C@8HogNfN(|{p_I% z3t>d6+zCZ;L%}X9C=jk7o=uT}aK@yI*ri2C_B1y$a5s>R%n;zM*RxvAp|q5Vo^j7p z-p}Uc8EPInqf*dXrjlyg>5U#0zsETZ$%Q+@fpZQ~S&j@K)|YE=Ui*vF3QXOsjVX$CgpF}XBR2x}O7wDltT)#~9Kmz2k@ z=uNg3Q>UX1cVYU^j7Q?bPUWIi^vXT%`$Piu!IK``e7Lh(8{3*HN3Tk8b2Z$mL`^)Yr(?rl7NXtrK3R#_I@aLURC1=~@m!7lz7{mfyJEWfxMMhM{7p58s20Iw_5Fih) z<{e8!y2C`(eFzFS>S8a^_o_yM7zD0}{jXMo<+m|a9gE8qO@Y@$Mm{2Hd8L}o2V7Ef z0q6gLEF~%hC!CysLOtaeE`}WrPeap}{Y#wIamI*$GcB&)&aT9#?&iV0NE}xhOatuK zl$6JvkJ}0VWr`a#vD<=p#iEs6#y2ZDZ&X6vQ>D-5PQZzp(K+(&(?UeBUXFan@`@%D zgT(Nd){+$MHj7CXFxs%C;cy6B`AGncXI%9*wh`**vjf4&fGu!`CL^}=bDTdmr8$o2 zvV_rivi=dhA}@~(0L)82V6KLAE7d7|vq{ee48%|&kyGrqlAQ%wT(!_oy z_7llAre!r_uBE->mE1swm%t@0F*Q&Dr&bYk!C55!g%VnTG=(M2q*{>{nE`fL8CK1u8%1teLJmer!(0_IhBTX7sti zNgZkicW?`wU1TlYm45=7y1=44S3SE9bw*VqDz1+;Qr?~qs=G?fU|4J{3e-Df|D0l{ zm0j2N5C6y5SM0Q-(JPk6s$Mo8WKJPtrG{2Lg#@B?XZ`lMSRUYKB4> zexFofv1or4ttzll>1~t&v;Z1a*If^%494wi{v%nfJRCRiF6jfc!1D2@cIcj0k0D|M zqem}pV^D>K)amzcGf>Om84IB8oqc0z9~^DWVAv9@Ir`+4RGjzJWfcPgJGlPD0TL_g z6V8#zZALKa2$flcU?h3Hw9&$Tm13t+?Ttu?f5r1C zMRQg)^Vd_@1#al1X55Ya_|Ba_t{4iC*WOE(U1s%o*VETK*q+6 z7|2!{i0y)$c6$wq0HD&r z!{cn(XMBKj(!pqGP{_vRpW##g6Bia;rE*JEv0KZXpYZ{ig8WcdXZH+*veYg`e@bbv424-m*-^}6pqX+_&$hwxCOZ;`HYsn) z@sIfJc1|K8&?s0XvCHB$-(ugaP!L|Vp*xT;8U-AMHd3l{iDOD$J1HVRX{DRlwL=r> z9j#oe?c827kp+3+gLh`24gVLFnPOavJ)>g0_oX>Bhm(qgQ{ya@7mhhxh9>oh4rP7iO#3Af2`^8 zhHR#4DcO&ADv-WJX}zHJB|uB?t`%*#Q_o1K$4u-QX$@{q%dIZ`P!826P6k*CP>Kr$T z(+>Z%Z>FafigtjcsG$tcYpDhmY%XWXdFPkcSFTHvN6Eh?`;BJVnO41b0aud%rlwCs z!kr(b&>FKfG(S&pRf_zR=`6y3K~r{o;r=A7gj`$Fl-{2yNge1bt`x%rVz`J0vi;e< zHgsWFbz$J9L9QSu_#?#2l||{MzGmpjskJFALHz79o#E;sTog1qCXq1qMAamhAu6e7Zw5SmFx4`rxq0 zK`53_wcy87v1~1ZS9S2ea7Sk)yRrPsm>5gHIRYYbdM%}1~}n1tpeI2*d(65!@n!7MWB&340!aLG3qxAU@BAzzLk>WdcU5z z($C;83U{?b4E@_p!^;PZ2y;l&*BdPkJMU18X69RZC+lpE3y+d;9|AQnRBJfsCAR0* z2#ge<+IZ;6>-fVxD!1{7P!|KhiI08p`tDDoE+!@oq>ahx+~yhe zp;C1FJc;~Kmx!_n8t_jl{PU4Dn@7emVHrhGx-#>fwP80AErW@ikN{@yioW=6Hy)?; zG+!y`mPb8vAPI$=lL@LkUJ39uT7)i0UA2akiTN@(q?ZqTDf$HSrt>(;x?~cU#bqqF z7i`JO~*g%Scg}aBDd=)Z1s-(_N3I2d+#7P*E-PV zjHpRd!gau`J%TG!9?C5p>2Eds?@nx;&bcs)jAF}X8H3$^`XBjKbY{I8G7f(WZ_6GY zhB_>gRDIFc9&Z^eu){S76~~t!;}v!KPf!!D>bCJi>Y~HyYE;R;*ZTpKfr^tHkRyM+ zhBI9r_^n_lHOT)iu>#c2 zkgE;g-7^g#yMxNi(|3%2uIB_*Tmu zj~xY|MJkJxsT8GQ$3qR7uWzORri#)V^LtF^iZPw5W}qCGI_!_1qXUK%c*%_}9Aj7Z zV*svcZml(4zgQ$(u}ELg*~c)>hEIJCR4$Z%BB5teHyR}#+3X{s$00Pn&XaTcQ;66P zji~b;^${fvWcOhQS28xD_m!;3pz7#hM4^vNZ%wSDRMVepY7m$W76Xj=kc0JAa>=Ka z=tDgIFbxKUj{lt$@f$x`b0exr>_c}@9s#gneQ0+$q4xL^#BnFXn-%R5|YW^56Y*?Ja z>I*6uL0eXz&@IOmDjfxg(dd)ely+0QE?@0!QY(gMwJ5K8pEnBMEz6r)E|MJgj6x*> z*V>(*^AZ#&&6ltsgt5?D6QG)rpq}NT=nXR#Ho4tOyuoaH!;`p}&hRL0#jTwSuvguEqKQ%^B&XqR(i7;r$ zm2uCiB7|p)UGVv--6{p?KvY{K&b6p+fxe(g#jop#71Mv%%ARfDNR?gxo>!TSBpic? zTDaDd^@9`fAo>15Bw8{=+(nS?UnG~^jCW&K!*;k-Ve>Xi;GzXgVP4$plZ2jKNyL`f z8TSDc#M)*D=u0!WZ-8q&#H+~i0h01W_y)IGfNBxs5#^$&_||StGM);H^SN$*;T*MG z3a7{b3|MYub@f=kuwK$}?3cFlbG zyh~qTzG0DDUs)EY94&SL5G5EFyzEM~VBMzg*L?(MdHwFzdnmF3H6X0z4s9C{_4p=S ziwrJdheT0ZB!&J2C`a%<>H88Q#qyJ1?%CC@Bw!_--AMJOcxOvCOtMZ)cN!DD8XqKb z%<`!{WhNcIY}8hr8QmyH!0*G>B@`B#@4W6+*~kfLRHc>GX`UoEZ#Zh^Hj4KjE?Se+ zAG0$hNDsh2S*%aRTNR`R;nNerVI0OU?XM}(Ker!$0qq2m9mH6 zBopF$w7*VKLZDgRpDET{dS7I2<3D^esKtxhj*xbng_<*yBZOxXW13R_)t{SzQ&QL` zamG5O;y?CZU=L6Xn)mih2;i*F=r+gFy{(S5OR3Xu!F4{PLe8=ATLQ9L6dNkf;5rD{q!cf}r+O!>s12vF`Ez8P!7{UDgIzzdM z%r2L-f!SYfiuqH@&X1$H%aH|v9Ai%-jR?ih`WJ66^2a2&iBJe1GIm{-K6i`1KND{; zJ3CAeHbGocE9b9HGH)ifg)o@Fh#1%cW*-|=<5ZZZ0?S^(&eLAGGHT)ZC@MK|3-{dV^RtJYS#VNqGt zI=Yl(VD-gXKN(I6fxlR5f~uj)$hx>s1t;ZHo@z$ICD18SZndt{k_%Ks7o%9_ZN=q8 zZZ}4(pFH(WI6g?)N42yhyhyCe9pQ|SH{#6p+ajV5H;rLWU0`YBJr$LmL=+S zh@QbH0W+mZ9H~on80?*g22otvkzEW%5boAcSSlON9$Rr6#c$|y+~&)8Am<^Hw?B<# zD|k?;_?`gwl`eT2YW2{&9wmf67SGUI3tpt`Oqpqsm%=?9+bqPp7-g;vh-yDQp%;c4 zy>K>IcUOG9n&FzT=4?l+TV}YLI&GJl1p0cOLyAV0;io&48K8I!U>n=oT2w;R6TRym zE&<}fG*9+iy-+I-ncj=w-cUqFBAW}yRz#`Vr87+jz#yc1)wcht+iVHheFYa?okY%z zf>@_DIM2WrO|NKYb@zyu;Gmj{7X~3-Urk#KY0E^Ea{=-MpS3!|VqJ*2_z+{$qKk?NPuq2Tw4+@sU-!`F z;Ze?)@u%97M5wOM0Jvw_EG9^L)*6B7fYPZ>z?x|F?dK2W~>pO0UQ2T=bl_N6sL-eUq|sti()M zx>K@Lc;gi?XGoO|UdqzQ5M=$N5I{6_m0!joK^axyqcq=qrMj&LLpwg46V~5Q>tx}`Kvx)$Qq)uSW?NLwT zsUyCA|1C1GbzP|W0~u4Cg%#Bnuj1k7xkv_UIduo58jl&5*Gag_4@`mc9}Z7*>s6sZ zLGypRM0duO4XCknTD!oMQYk@YzQaB|7LZsff3Uj>pbyB?sE3I}AMG)f=OdJQd}GRSB=J8=O}G2UZ2c`Fh> z0?0wvan3Fj#14s=Z4n#ROv=SfQ3dfB88HH%c)rG8pbbZz9oM=t{g3`2;0=eZy*)(F z)RwUX>f;BnZ%)bTb6F%kY0wAg{;`A8)sT9$S@#`?739;jOny4i?)wD%}6tjlnGpCNd=9K}` z>qT@`HbnscKb}@^ED7fwM;r!Jf%0yem9*k?vRbf6!w6J(FJGEEgmJ<8;|k|L7CbW~ zFd;@`WfmymeBsN9cfrRt$?Hu`yH3-t%_0*2K@efPElK9VzUU)WIpWKi4bFUpnT)G< zd^VtSmQ4m*DHo&Sfy}NglLSAS$B^~65GQv$vCHAg7ZH=gKx^Q?(bnIZHJ?VSpaLnv zW&~0&zgeIW0VE|Ixglhd_@~w|G3q!7H^=wA8GF9adk{N=2PlNLrQE~a+|^JarqXOG zCpSg3C+kvk%b@jneMU<7WM&VSYw$f_GD_39Thm8icZ;!sV6QRaP`E+`{NNoqD}E8m z+s1^;E{S^4S#a>BnIF~#hxTb8=5C@e53Z;5$ayXJ;eRen1~9cvM92o3Sy ze6|-6VFD^Qz~M?N5=6*ZMe!Z!X@BR0o*ZIW7%T2QS*v9)2i#w|r~WuIp+w>_+P%fm zLM)mcbj1Fpn0sgG=!3aFHNld^E1Tf%msuFTp-UcJV;{7I6P)jG6}JHN$wdNZrhVHa zn_(h23OYS{7HDB2h^kx3wup1#GH((L-onD2lT9=vEcDSDTXIEYSL7reZw|ayG@;GNNyhx6}Y6@ zpV%?e7!^h&`Qu5bg?N5{AaLA_tELNVtu9aX=1D|r@_;E@*8F3dI9vyp%;k#ZGe23w z_3;riG2wrvAE@cLl(z-6-Mr;7rN zSM|eQWA8B;L1V*9wl)7yxIhZrc+;}z1-svt5CuP~A*LaB)t3+zj}UcIu%6_HBA%<~ z%`&_hkF>Pt5o(9FW?32PmGRSrg?OT}AQluE=yZ;RDsRqhv(r3wGotXeK7<&!UUA5F z6Ly*-azs4Op7c5n2zhW{_C1&JV4Tqhr`|*G(N`>Kf0%8d{C{FvRTgut3$raM1GHqE zy2dyZ<9#52#P@i4<=mJD)^wJ6u@y}SkY@y;1cQGU1?8L3+p~HwKOmppygFCF)D4{c zes1Pv|)@vyPvqGRLHUc;wa2tt@=3!5O2^{(LqoEnto zqm{!xGBUp|Gac3S*?6Wwi*f2MmwJrMFe3l{{v#lbV%aSJaLW}<2`3}!ZO+Z>i(np~ zTA2#rk`M%kYNu_+eqZCaG0cHV=hdZLlHR=4HY#O(btKT}@zbd<3s8zq8grgFYLg0H z9OzUH738l+suyCB@YI=a8z+4iKwA~xCXT|dS4jN7Dws5F1bYw}#k)-i8%m-~&?|vpVS<1hIpX`c3}auTE|{uL`rA zAU85INO5DGXZ&dsM12sP>$FLh1}!uf0aBp4m=}vzE;~}a`3xPYG8PI-2h^NY<-a`< zYcZ?QN|b3`585#@C=W`CSen;Jx95BLUzX|iIiwW!9BY!!OC~%hygtx@<^D{D=*pJRbfmfNH%NE& zg@mh@97OA08JNJzI;@^-QHFb^V0r;Ml&mbF)|C9@@Uw3Gf6N6*m#+d}DyNgV;Gv}V zJ~gyOy%cLC@S%uyIJIXKM>K|`Hda7ocKjPCWA57kU_CsRClhbJ)P8k*ZpUG6%+QsH zX8Z+-86&UnpT!;rF~y5Y60K@R;u(L!uKedgH@(ckqaNxGe;Qw%Hhap{HR?OZZl1#< z@{kek)*--RFR3o>EXc+RFeIcqnt_7Q{DZe7=K3w#15$)=aYS8`x7MsG$XQMLuuH4{ z)A7buKG0?T1b*Un!Zq?Q+SaRQLT`(k9n9w1>-4|`!g*s@p7M)_Sd-j~O(!XVND7gX z`AMgI*JH~&aL$wjT2vl30f!T3L$ROY9BVeyAdmD?&(m_Q#Uvxcd7VzuX{JCI>2>Ok#bg1+1K5Cp`sLM$B~l& z{0oQY!yTF5K~)-eW!%n@DsD z@Z*MM?p&?eAD;P)PCvOBKz?f0yrIYy7T@4Gt-pH9VUX7Tlj?a$L0Rp_i3ztZPHL*lbIfjewg&pnUNly-dDtnLXK5XRhWIuA}e%)l?Kzr zNqh(ji;xLS#Ue1yIrWLnEN>(D2CHSO$t5w5qI;b9W7}`h7yMNUG%;XERpCoHeu`P+ z)3Ka>BMrvZ2B;5^p!EcOP9)d@{~>}gffb1c-*0>h|1ySCz5rsK4b#?ql4VfWT8+S| z$~)6K|33@4H=;U4_mSVQ&54JYMLG=Z)W{+Rh>if3&fI4eR~Vx8;X&psCm@Jra?@>4 z0iQ~cG3ET~2HE|wn++m>u0ru}t69{2_Tyev^_)s;ZD4$Cj>rYKgEsyru+b+2l7pt(5+2W&TC`o(r)9{h8|=2&!qE4YL%$wgVrq1f_5Q_=K{FMDmbZ@L-G{Ck(GD#!(JPtIYrfSsTmS_b6$DI^yvc_W@exv zY7{a2(Q$Ctx_{qn#d)=>ZA9Txv+S8zP3WOEH~=Zplkx^R9s5V58lOtryoTyYxLv`S zRZTQU@j1F!dU8%ltR#;OcO3>Eo$RoQWrP4_Oc>d$wUQ=MND4;*X^lG6JSvrLJD_Qy z4L%M#LkREP^lA!oDhe*^AJ#xM(8lUdU&KMpH^?IyOxiA%sM+V+cPB6CZ2E|h>qD#G z?gummoEmkZlyuycJNUTjNY=H=1KnJy&Gid}_2r@4x`y4MV8z^rbR%V4{dboYlmdR)B7PM&O+zj3r2%BkI}v9~9Zmh} zSx+m_xnk!r&qLCAb+gY84H%n7Sn6>46S_&n*d`}LN{o**Z3*B)soCuy^K{?si9-*Y zuGwF2x&ICl9?yQ$vcjK7>bvjG_4=e{8B0tAe@<;|_Mh>9pUg?U;_^gaAz1mvp=9|r zEqU$k3%AASYZ!Z&eLKAw@k(Kj!ayesS zG&e`J{Mv*}EOV%%iWP`&Q&lVYb5 zwq6YE5U>4~#dGQKEuiQsY~ho&o~isb<^wc$02t6!4Ri_4PswcK#bCBYYW-w(wJ*;D z%XIEhlA8+ErKWf%xM#0@AAIBZc<`qAPp=kr&~`LsP;~*{Pl|HF9yGj6km~=BSEQp! z=S>ksfQhXMv%#Gy}nbegg|DEEtNI&fa$ zLC9?~?_=t{$K>R$0JA%3o~r4LyX*C)q+B%Wn_R8d4=!|=UtP)3ozi)~$O-(&1)+XF zDAFn0Mvcbuq^WyR{BFbupe)J3F*E?$`wq}FL8q--x#e(4(MRWB-o%ruam4(rNflM5 z*1W+}MgEs5?;ZXVYZDb8(+GCu460XgvA;lO2@XvAoH$uFT4pdzD;}LSopG1B~b8E5K6bz)BP>g?x zC3XWIj16Q26|bVazwpLjpB3HEk?2b;m--Z%@C6B4rQ)szyXuCq&Rzk2q*mLHJzU&K z>hbhT*(B`F`8Yh^sP;O+3Hqq?>%!iWvpsQI86mL==!B?vWg{($8f8wvt&~#MPJ0iZ zGAZ9uvdm(JckiNBhQ@FN1`B-49&QMwjw{wUIyGvzp55Mg3)HlLdPH)KL1J6w?prfZ zo<*3hcP!l1=E_?}I_zwcI38O7K_?Wxr3W)t5!j0~06;EzGUr^{l*zosmMOS3B)e6l z{!Ch`r*5OaJ7{z#H;T(cx|-k0Frt{ANQ8WtRiT_LfJBj-!pVJpusSpzGxv9ts=roB zHHgh3DEIe-^MclmoV_o0D~4czNA3tFbp;xuH<@M#NzjSrEYz?)Z;Y2S{*gKc`G2BZ z6a-I+A(Mx{+Z%})hEs@v;P;oZACz>OlhfZ~7V4h95RX@$`N>prwieeA4TqH;G;;bm z?rZ$-`V4}!jbNoK2T=(ENJvI)9|hxw-$yM%XnftyFVrd-Y%m{nWHM@If&o#0%p zG^jk@;m4xkv(Mr$d(5#;Agp#$-A4c&{Q@Gx=Db1eSjAd?rHDg0DMdX!Z7ax$q44~# z;zS(yu&EPOTY%5}A%_M2h7$YUunq$!TowSDudZBp0=x=6a%6Wvye(8?FJK*{`yWCf zDN#u|(3N#g&RnjW@B(!Z^to$1&v(<5ms@%OI{R;OIPAq?dpNW{PN3MFB-M#yfyxJe6-{I$)uzl!3!lpkq3vOC!I^Vg8_Lk$J3|Ks9+Sjh7jK zWZTC2w~D{@k+H}Qaps$(lhN-*xVJGOXYH>zOW3$xVfEYM7}l2D z254W_ls3KmQ4g%av1b-!RHF*d3(6(n70Mz!xd}C8joJqU{YB)p`xgyoZ!$wH_}uNw zNsm=Y*yMmP2!U|&hc4e$j}t^M_Wj~3neqdEq@+>DWWXFr9EY6{ z3HcCr@nB#pD{^Hg`o5k2UA^pLsS2?POdrA4@6L2_Z?%N1ACJLNSK**Ky*_ovRa^DS zwsNkZ`w{XfXJG$cFW&W*W|Z2#W`BQe%J5&(1`d#)epc77{O5i!v{uoeD~u$n+YO_c zhDTS`r*!&PR-9B2Z)D}4b6pWLYimpLt1^yZ=E4X5{RnY@wRr+f%GWXFYUkT`(ge}F zzE9=}Ta=3E%WT9KSlizTRNm+qDi1`Xk~1b{NH-Ow0J#HzV^;t558F-D{`i%aLc)xpP91v>`-ay|R(KzJGnA@l#qfd?@ z<$<&A3UG)SaGJT6GPyjO_56&G*U(mLNJD`zq|(~o?K`;2lYrS5A4pC!$KwE~PG|6J3>2WBvgKIJlY)u`rTQNuT9ZqTl3sBHMAK^Z?uIt` zA(}rh&KhTq%B&(6;KwQ(fB;uGV+~t(6zexD=^5Y!JWI!EHNm!@2Iy_Wja4cVf`3ub86VmOFRuC1vhHa(*l%oMPR;& zoq)=XD+fedRPXs{Hp`teL^kT`l%vgvZ#w4HMz#iq96KoErTa3 zBDUhT#v{fCXI<3~)MY_)Bd^VSs78r{0)+n1m-h?UnFJE+%ySXE=mj7F-cL}qQDQ2^ zXaMvo8Y{SnnEcqDOaVA)J2uS>z}cEc(b)j^ipeSWUvsS*^?RbgYdBnffE z6h&1usof)W#;tf(;|53*sQxLx0~HeY@uWS@KWn_lz(DO<)Jp^J42#AtIY|T#Ox?1z zkj?&)OuFIwS53Zi8B^-TaqZV*Ms{AsV3K_BbU^^X9Wa_B|A5inNslU0)c3miOEpUq zlDJ}*b@s(({UcBjdmO%S5=Bww+aqP(`PN*Tp&$6ijKuAs2Z z>iqU}L=%Cwa}qIs(OU1>XT?8G;&q#kRJXYVqgGXF$)GMAw=YrfXmZSOxPDOy-=}g* z$XWm0o4~;Vbg-pFQK492%>5^aYA4<>c%QYakX{!=5jWNz@$)HPK}Y!pe%9sDsH%~} zoZpNzr2?=*x|Fohw#2Jhk`}d%6pkGf{L2|SMo4{j#_<9iJ*RBP*$Qsmw>6*pPQ%0| zmUGFkSuV#KiOf?h>H^+9Qlt=+(4()Vn`B;_jh<4hnRYxu>96t^5t3j#$b=DOCEd?` z@pLze&%oq&lxY`0@_l|A8B6D8e6^1X1^2bm?l#{)b@vc;EFbV()>>=jwXZ%-sqEet zPdBe=*MssNHipg@8c4|`SG)tg;qoy7OqTrW9JtVOJB1#ltW^6O-A=SD$=l}Q8d7Mxc$jk*6#qOyy+RH5T@g7tkFoC@ z8Zh~_1!P31YGrF05gC4_wLe|H1jSYK&-Ag#C$Ybf9(xqdvzs+W%=$b_U2nP%o^vn%jaETtXvqG&B9`lgvHWhat3t2i$AcCl`4xH;|v0I$? ziTu=L+H?RcUvJ<@UiklZXzSkJhQ_7E6iULr@y8iPa~-4|&k8TRDeu$g06S_72jRdt{hTJ!SwgK+eBs zT-E3sEn)D3#69vhs$2^=@Hg(8Uh?@5xus75*PY9i?p;t^HpGb?(tr7hn;0M-$NFP) z7dXr-WH@Z*vw-&2yxZXHSCrlM9v`dhIFCzK2&iOW4FHeJ zy&iuWqa-urWE!$FV#o0Vz@T(hB(x!j zqW%qsE4gnQ3NmAu*F6KHA3_575Y#m6c2;ZvEFM5lxHAnP&zGOQ7BeRr!4XJO$%YDg zyJVd80HoTQgW1fM=>f=8+|{%(^YI=Q*N_jQp7o%W^^i9njP;#*$M?qZ=NV&bH<-q8 zpAD^$G4Oh71`$(1W&a_Y)o9is1@-lV9>TqEm!$7c!;Sth^jWYiv}R;A`fx$eGVF>7 z8jV_|&mpbbgLl&k6&l)rJYHpNuS@`l6V_voQfC{VI_Fz;&4aC#o{%yRyg?QQ7P`l-DVN6l3PX^w8+zPlZAAie|?K0as7&T9a0{%v0iwdR*mpa zJUz!`Jj35CfKWMt=1HjxO@J!A)~F;#8Ur!tC}B*v`libg9EDKyolwx>XtZLtbQon2 z+nnLSFHhMiOv|b@aZN(Tv%%PBeY|IYSKCNv5d>z+YQb0A;&~`P`Zy+A9R2D+f41I2 z^(}JJBj$}darJ9_m;6_queq9(uL~UL#3sF5Vi%v2fGQ!}z$3Kt+=xe~4?OK4Vr zMbGa{ExWV<)<8JKP5}6PqYFN!HbgT$4bCsJ(M55vT&R6_@EZwyfx&}&k>ONube0vj zuJn|_1Ct~tvf~)oMYTxqveUh|4|8V+b4=1j=bpPg6>P#>YeCXR* zzQiRT_fng3~OlZ2URTw^7P$$woX6DG5*HPuZlh06% zns$G9(F3mC3@D}Ge)LPCrp_OQHIsqGGTgiT>JFsi#f6ihf|KUF^92fL7)0M;iMW71 z{53tz@cMT4+rg=R{$(@-y3VYJfF`KnE_Hv8o}}qG(e*i%3!I{-_3yFqF-O0Pl`~4PORu;Hs`-OMZqM` z0&ft%_!0jgGiCQKQ@o29RA|nb_S)QSfLBpp8+qCt-9nG+09%^Ij-{zlkNL8jDe^J7-#3l zTKYHX@;4K*$AWb>WMdJ|^9`dA*ZvxTJN_$^^%%}u-|Ozo0VSED{u3Emy%B|}l~-6~ zyZfz!e_0x@!VtWm(iABZJQ?~e0XS_UgwOM=_AuFY^E8aFek68?!<9@(Oj7gffzV#S z1R7ix|63k53LG0kKHa^eAGerll9iYIIf#oYT{{AZWstuz-pfTekmZgj4mWCXOIs(u zzqKCz4qiL0cHv^PZV80&Dv|;i?a|sl>-n^oRQ4O-@>7e__U8`sasSQf>yecAg|FWI zMQsoWkgstMqAfqd+xvn_404EJpi8uge3=bvHDV;`g18p0*8-qZk{tVi1%e&KE@QHo zt?u?m<$uXje9JLbA_%;I;&XwYu3yv`Y~G-z{7wk!{7l1>pSAmf^J-@OqX)%A%AU6t zJ`T$|r%+%~j`clI4L}5(u5hs&QGC7egGDT#5$6$t=WZ|HAe3ht~-N4#xIV zGXdbjyK0qCSO(6pk}(3iFaK9V;kDBVU_8grMeHOibwX@^Z`k1CR2LI^A{RA~rBb~s z)G{#6b?4J6SW}|jECm>n>=Kd_P}w9a);psOx@h8e4IXs$pO2)Y-8bk=5C|OfD09MY zBM981_5Bi1w!rAg^_Umj6*lJwQnZ(m{UR8Q(2E{ig|cSGn)}Dji_(ApG^)rAIxgnd zaFBS=cywPe(34?Jrc%e?!lpk%Bv()}(mG!){dTUQv~5--VIiCz)VKU=`|3cH3R}jg zX=zW}-g%Kk7QlOCgsiExD>)3#SB-5j`tf2$)@6@hiZM?`(-krD5P||UD4?VP3)zphP+gaXe?u6!LL zvEL?u14w-rpw{VN&&#(T!$aVhd3QfOlho&6)dovB^F9U#EHo`SB-)a-u*m6^cjE|1 z;hFPG90L{~T$^}Q7lruF8is<~-?9kk$)Z~dlLx_L@y|Qwc==GP7inVKb$bYm;8c;P zu;u}414#KG8B}aH#aO37(a#nEbJciLgJ85OxWr+AJu5}ntc?;a*5*aaFXedn&!Zhc zx$taH3Vjv}-@p0mAvxmK25|p@Ys*nUVDDT5wGPLeIrQf1#$6fu#7UYdquC|!u5Uu# zXyO&7(u(S8AGhEK(QLJfbEl|5hmn)N4iZy2RrXY5AK{0CMVsN*38VTxGmwb2R>pzk zAiF;XO21oweOv_AETYMBkrR}|F>vw~5x4^wZ)hvS@9v-%KJ<<{J<~F^n=K4LEbViT z<1-eSzDbwo?DU<%dMk#!-SAcQix-nNM;x#az|qY(tIEk3TlZ^jHs*L-Ug>eQSJ#=* z)*s(}*8n58Z0~@9)PBVk>8-N?rqgL-D8sq#wtRBkw94D%&?LdvoD^2jc$&3=j;L@A zCU!9@tGQ!R3-dAJbe@2L?hTFEv5SVx)b!3M0gxe!23;-ETL$-zNtOHSTo%d7)Qy}O z=x>L&FS$FdMq+}fu|(KubhxgGaI=Z3+uloACMb>MAs`^V?U7>2mE;&w5Slc!$CLfZ zQn8RGF`$4-?3=3~tu0;-gZG+qIHqS=H@b>hzgP$^YEJIzeOgG(NRhM(J#dP=O9x;5 zql&cLf%QqmdGy@1x7R$C7vba)W%?jR)|5B9UV>BI9{zgj1rM*QC0fF?_iLFwza zYH)W(6_xx3v)X%Jvt|sK=tp6Z*?#EF0Dhe&JwDn<#K=ULnZf+|3Y`$*t2H@9{?w2( zf>QGnDl-Ex4#klIuYq(+9wO+4Q;=f#%IPk^f=VlcUBZoDn2#JF$v&9w>ySCWWzK*# zRe+KBJfB)px*@+pxEUxdF{(q+1T%6La+8)~#%MGutw%Jsf@g7l)Bp*`OV)rgLU?{C z@png@50c4CHHiw}A(qJRy>u1Sg@|p9(+AA&GrAZ-MT_L= zX#!qXH_ik^#w^sXdKL^bV>^ZEoz|H7xBP7%uL8Cr)S`zalkrof97aor*Rvy@=yBY5 zoK*y3&;HyEIZVVJo1gM(orjs1*B;K0qukmQpnfapc72H~krp(7-6C%S$Jj_|-f+I8 zoK|4^AcEMEt&*m^^1#bmObc(?x6M3`teZuJ7NPg@fd4I}t@fb3==5X7YLrt~$`zI& z52yVpMmQ2lJ|2+o=tWrY~E2WBHyV zvMAkUTJlg+*{$7HMAW%;l2UXU4-WbkczaoSu89t5*s|Mc(AwdDQjzaMsjwUU^^ujV zM1yPJU0tszg@lF-ur|=-nNV!&;FFSx>J>5y6Rr~}sSrgo@DrY)kPgO)M|&+7G)3o5 zv1+fpQ%5Si8Xy1l#yrm&EgMI3Ts}9YLKI(eb2DeQ+}ZxBE)i(3scnDq?jtlZaR4DT zZ@tXyI3KEUS#hri`A1l(StVi51-^_PPs?%YO0aXssMUW%V!OJSuY$4R>b_7`Vg(HdT{JgPRZtM*qk(} za;A6{zkzNPFQy&cP?Tw2@j9Zksg5xrSLz`9KN!% z3M9W#d30)WZa^h1B5nO0#aNt6*y*|Rzy8J}IoxV438g-7@<>L6GxcB}qhJ5BB}S?= znqi#MiX`0MB;n3e*vxXgrd&u4Mgu+)(7R#DagsnscQsbxi@rH!ufAl>%Q-X5%{SOmezraK9n^0-L27j}Wno(mDY0|;>S^k={Lg&umPta)|` zq{Bd*al~jOyN}*t#Z)0WuFl|=oO<>O{XTQ)gBE*0ZTUNj~*G*zi zZm%L0WNCx`H=P#JanAVRI;nm~tF?uUEpJdyxC{mOb)1d%`16%?6f!g?$`}Qxlj)la z!IBGXmG&mwQXt>s^CEhPqqQFr|70Ta;EN|AiW-EmTNmU82SiveS7CERR9mf?1lp_W zRQvv+h2O7|K>#s_5d4KM10r~wd28&g16lME;-%j9YT>YN93e*(|(%)G^1NMHh7eDclvF8v47 zH_Hzh5OC&K{-$pE*qC3Pqk7%s)nbK0W+LnMx#O@)JNWGb=p1U$cQBbx@>EcXR14G{ z2p6D9=;D7069aX5p%W%3^B2J~4AT;`26C`AM#_sf)QB2w>r<|iV%9c;0$_zfCn8rX z{8KQ|LcL@K6JM4m9F1HN+P&Qa4b%!9S<26`fY}ETDKH4i++*%5BC8frbZgMrvn*MZ zDlE=Wr}R&AC2u)Kss~h}%{OXcz;l9H_yqsMtgd9I2*39Zxj%*Y6DY#bJ<5UZmyNqg z;GFZbilL>9?x-;ZGQA;NGNrssnXF)VYS)vjwn}M_^f*~p3#ZpvCB+=n2N~hbSKcdq zV*^JtdMwvnc3un}w}MBA(G!|(o^4{4ZRApWRz+6ty#Kg#LYUd0r$ef$*hrB;VIXp% zriwY$!Seb?$K2pRt>0Ha1z}%0Z?}c<9wd)6rUzem=9Qmapt4afQ3@wUB`tcr>yP%g zMFh#QDk`8*e$4d7BuKtRPi3}-FQ;mXga^f)oJBqd(rNRGr;zZY;y7=3ECj1b2a@+S zQNix57t+%HyA4_o?)#rX7s$lz{4Th&K|1S6`X zO(1t4*I4vvgrM;S>#u0f?!PZJXsZGs$x`s!xO%nw_8}1q5l(6?awGNIBjIqRkhYC_ zZ$L~q$N^w4Q5gyyw_hyJ{$81dnD%9|7NBH^hw(uzDkv)N*3!A2S2BiJIm?xxal(bO zAU<4nG-M3pY{8y`n-(Ntdb?55%PX(-7HTEd8YLu5f@V;(jgtPE;{<<_D7NCj! z4a!~D8I;cZ$FQEq4EGw6*Wzob4|B z4O{^_MAmx#aVzEsybp&N+!@kP!MGt5n}Udh9J_eVyIe zO(Ke$$Q|#Efbi;L|LzAzQa}P+84UOVce#tEovelb5pfTr^8m; z5!BU>uLBc`oS%fK-(@df%KAcWP}gx_BbO}|6S!-xLc@kz*+9g9`~lt~Z>8gFDrtkq z&lY6y4~DGCr}(MrsNl~$?Sjsx(;yQTWtnt2a`}T8H`3H9p2)l5hGmmsk|f6&bA)O? zkYE^c4gI&3Uo0KX0nQBFTh=7-^p0^z-Dn54pIj8%A*GqOpXtMNZ&|=7twilG*t2=F2P@+sDlBmE;MsfKmPq5} z*JGgQavBkPWtFV^)w9k5!$!nH|7gHpfLX!r-Qi(Zx*ojXQm3KzEr3M$A(B)6M@$28u6H? zy{RT*sfnL;8+j^&HwXxij^AA~kr^ZNmq0oG7)e20P1u(LrPJKtGtVtrg>mdkV6$}6 zh}0x42D$0Bky=c#(B`#WrLJ39LEc<}bOxyMGVxCXEny|SC%75^d2oHDE09t5kBM`srf81I%NlL%KWm|*Hta__^Nm$ zYUe0;HnT2X$X!Sb03?u+!S+Gj6s-b#q_U&t%A_>0(9VZ^mdMIfOnZUI{(xyvNne!J zHnYBIc@4=}1tYi#HL-NrdcdYB8f=H5z9gh7^=;yduM{l@y6x1b$PMAQ@yyBSlzWPo z2z@4?SGXAR`5{=Irf&KHM=Fm1Wq~N*!7~ycwLq&=E-QT6{4VNB(%f~(b|dVfUazt` zc~^pr@g6rh=npA1_95=Zf7>gW;oZ5~2GkWcroem5VLRy{kSo}<5t(dtEZk5!=Mj0L z&9quxpJC_&Znedw=lIL^(dVMd6Q6h*$7?(b6Kh)83w$BQ_3}6wqaw$yKT2MgqvYLy zjJCct&l?EA&M#8rk}lmiaXBI9-f*_V>6pQSAHNoxp%_ZV&I(y~R>wfoG!-?Mp+-vP zP*z|xw8xl$IKZoYfF1AuBP-R!0@ug$3tqT+0J{YTng*(_x)k!l7igF?{bFztj&AV- z05{pXP&pzJ@M4k%fm9ors=eP_O&I~t@xr6S42}FX!N$p#$_mz4i+YFpvea?whk$7^ zCU{0KFo3k>A4^&ZqFvX##)$Y*?n6KkrDh(KtZ2&(im6bOwoXb|Hh1_+9Pl&e*hGDX zcl8wu+Wmy-lNu=dvyPGE2_iu-VsZb2V_yOw<~;@>{a@Hzdx9$U8bA)V2Ew(1tqBQ{fj=6GYm|(ji7!YTB9d9VXPm#3?jP+S(Qa z5YK4v_M%mgQuK3xryy>7Z*0~d@G*L5-5M5k96$?+d(Zj~fU1bV`YqrJG(_qJ7iC*9 z_u6)=N*%}#L7NlP1g|2on64g=n)u)s3t>y90svMFzKMiMCgfN>T&_bG)EW`P4GrEk z)u=K)>A$)=XN}xybJsEO?AoCZw5(1$Yc z(hlDnN-PVr-y7!(=tI}N2k2Z42X}Cj5em+to2z@R0xS8S@!_oIok`>P_ow>@4MU=#{BxCqBNW>npE z96_(sI;=K$MiqNGJ!YK#;qWG#1^dYzFtuf+wrlTtSz1nX7;0y3hL*w_*fzmn+&D@m zv_=Z+Xz^K74t8PuZn#0kVBjY+X=GL=JBQuY?}jI*6UuQ#clPxJLZvc?=m{ccT<}wKj zQS&&sF{5F}{Mdx)e6NHJ*ecT*7m!UK-!@G>mhUy0dZa<(z%NJ4bFu?pl95pIQg6)o zf%9FMdVOeZO_${WQTa3{rIYtU~SR^ zxw&KyAzJ1!Aj>~5L>6Q!vepu2FBnTul6A>9u}rte{fsK-`f5fwFz+iI0CS5W3t-nT z<$uwSD=3?&&548A<<^7-yvt;Cp}WWY_J)-(WMk@0?dA!oP<3 zhm&B`;#sqhDQ(xZ=_s@)v%{HG>l}sK5*WJp->LxzFuNdeVh)KuZOjMbhmZAdC*U!x z*F=Rq#^DV#>acRrIZQvi3w?}B^YU5>k+ds9BTkBYFe=Bv zW2zgjJTlZEBhv3dO+osU%z5DD*jY3%NFzRoO}TXfE-rg4cg*5A<@9GnBjE{c-yc*F z?@k3USEyKt@1Ea$f0ithIBz>wDt>(F3V7tPc*Gw_jChyLx+qQ?!=X3A8-ZOhMa&B& zqk@mXgGOJh5aOh7xAYG^$QSVnZVjM|#04}JEnYG1KIX8ma5i`-cRb_A#0MY6gO2g=cgW11S#%U*Bj*h>mwuJU_JLPc9!bX=WyIZ?YW;tIM+dJ!%9E z;e-6l4-h5n2@Z?bda;t<`Jpt8)&iUJLD10et~&NKHahDKULv4cUB6^>BO{`P?iBVg z`2h~Q5J<4g`!fx;9C&nwG7k!Rd=+^0{H~-qT2+h;XQZVPa!m_f*IK6#&Ox&cgVQcy z`bP}iI!{!|YE?o0Hv){|3>ikdm@p|VFMVywhDy!iOMuW`Wc?%9P7uvPWxD+d07JO3 zqLVI^8X!yoGb+GD36%&)74Jn3f*Jk*!|pg!g5&@OJVd1C9=)aF#}yTP`=djKnN*6@!yPX34xO4B3!Dqn+9e zTxe7g3ei#7!pNsS+2e3cYSQ{^Q+N{7*9^84L_)v`pcRZE%2J}S_Ch1ig(pY$37Ze0 zN7+u_nZ+}|RxpLiJTxOD91T^&N%^cFFel9R$gmGGRs-zLN8E%YqQvI=GszTC>`QW9 zJ+G|b^lkwZA$Z7Pwh2^&PV&fwRYi9TIX0_5L9IZDJJR~HZq)!Al?1U^ z-7a9K4MTxAbwsvz9Z zEVeM3RR>rP=qz~kNn;Dke<;0@X^|xxG$y&}95HiHwKG+A(S18l_S+}}@$!NvDa7J{{9AY2 zN{CvC`Fpe>qQq9GhRw8n!^;1>o%Hl>65%G^OM$o7=G`?u?>gF3&^F-7ZA;>Zi3)nm zFF9&!Y88fS4HFtQb1It$8<$B02yV+DxcX&ktm)Ae4j? z8y_7uhzo}JA}U#o!Q7WyMevlC42=7p9-Lu?H8}tlZ2L(^bJC$8#dn!s!@47hHxh*;^?K03BT4&t|TJz%h4!x`U1e!0!`4~7K}NdQz zc#s+Vc3?X$w{Yr93COipZL}hE;Sw~rCq}nafCB%r0y(p}xXy}u=~z?bU1Q>< zm$zdOJ_@W7fWp^cYp@R62G!D^yElL*vyT^N=B_pS4+&<}!m>W;{b;&oA{+AS8%#%f zAr75WE@>5fm>yfGeK>RIiVD7TJ2@xXe6;C5W>Zb|luKcgre*SS8ei$>QDxQJ0LzLHW+2>OkQ;Tb@6s@=J zU=6W=x_MTDjk&M0bF82&(j!>|-LXDYaUM7UD2!Z|FDO`sGl>pZWm)1N@{M-Ry7ooB zEAl{}3OUni+;=|L2PA)Cv6xG{?CifeL{rL>M1vxS4s%cHX_Iov14zH-IIq(b`O8E;)JxUX3P$wzQgw0Y&qC(f6pD_|H}pc zA?iINb9!+J)RGuz6M-*ia{9=hlnjoDiS=wU6C1k}%kzC*rz4ywSjHNb!_FX%D)yn$ zQE+9}zDI1qk%o@)Nn4bXm^#QY=v-Sryu4;cTOQ^*Fqax=4gV zRyo`9#gwRIWS+cX@+m0V?lu-#y_UqV`{!A_EkIfA73@%{WF?(%V!^&Ks^$-8-n2zq zQ;oohY5MUJ$xZJpphD4IW5tqLS$09W?^P3_33wmy7t@@_DUbX=(Z)!*Gg35f5YaJ- zOn1d_{)NJqEQcd-Zj2qH=Ffc5cNZ2`9>;8a zJI>acc&WMJ2tIkWr}P^w`06KTGIARKfA~L<+o$9V&5br^Q!x0F%M0Vt7Hy)erdwZh zdt2M%S72Ono}6)HO^OoHzan1XGy~!DRXOW&$IBjDyPZiL)RJtVK_x=bHy6&AT9b>) zNf<Hek->Ua-?+A#P|6}i(@Pl?&6w-%Z<^hpnYfQ zdBOW|dg9^uVvPYJHO5b3R_gUW7wMjIOwMwE9t!*!Z{DL)a<2&@V54VVlA!X8uje&7X? z3PCC@h%NVl7F=GFc|t4%z=rDF7)mK)OB5pEZbh5@=7M-{K;>1Vz`&m4-{D)0j_BbT zJ0ScpK0l5J3OJ(2_1rZJr z8rKcJ_@Ca@8c4013IFZdg6CvVEZlmk>{`=^I>L z$vCCt^+jF`qZt-bEImybnk5P~vLGq|&&kEX7{& zFw0Gd2gN{68YgmcKo{YvD$lfQ9KoUaZdlb0^B;WleHl8)qfmD^2{0c{>V(v9!1=rr z@T3K-`ox}CWghlLORe4|GF*}@6;uWl-0BA(vGNeR9$@&Zr^`l>~ z_lFfuzd^RFJo|kY@$lhpxX<`b5Y$w0nR26AqyeNlj@N{BDxcJZnOTI&Yz@gG8vJjt zN8)i!B)J#?BxTT@mG*7_HyS3i<@p6pHsv$YBxm{`GRmQh<%FlDeOQNcxC)aFN5}|K ztIWf!K)qt-i4OQTu%t)c`#k4)V7kosj)P&^?YTXsv{2w<;yHuu+El*7enN8CH}*ls z{Tcm&^dWtGgE4diVlhV*fED7>K-oGl&TFTGePCm7+2mrSldW$3Erh z2a|YRv_ zkeIQ%)1nTg3O(=p2$l0TJZL5%1OJc}#;#&@Ebei(PKl8--u9auyEy{ij(JAmAg4UF zMO&E}j~^^hROen>WTUD1i&;o?hD6gSA;3f_kp)pFGw-^_!~aM`?Cot+E}PN>6Bw72 zio!l9l5+23(Tj<|O~ub|NSdF4kKdZo_ktZYE24um9P`!&ED#AO@k@$!F{c1-@SWRg z_uBQ@S1WVFx7gub;?AkYcHvi|-V#h?V8)HfKd~`K z{voZ_Dj>0zxEOv901V?{14`xYDZhOi^N9fLd5xk09Dl5Y;Q$JgRJYr2kQ9OT zUt9lQD7OWT(C1a-!8;Ryj} zpj}MtD!WMw=PYcpHE%S0=Elmgf%L%9aBVJG4b>*MU#W1vseK01D#~YJsVrBAoWdTGgd`D}>26g;CJeYpLp}vJ`xQk^w4`wxnJJl{(8Nd4=U|>~&|8 zo~lg7Ttxup!s4!R{wmJ`c<_hF`hoZ^Dyi(cZB3U7fD>o#@e<-L7%G(0y544124no7 z-@5`HScPl*wYZ$>OTTd@Q6?w8`u@HVf<|;XwU9p|7JNb6TXD-_YC5rPvF`DKq+^C3 zpO!l2H{VlF5Qi$G+Qo#oWG|r-Lf@kRg0p(g2m7@1kbcXAV(R^_B?1QY9Yk5!ROErQ zMN>-i$^5)M!bh}VH7LrD@c%fZ+_SDF5czPoCGmO2Q5@%eg6SE+g9AtM<99u!T-9o6 zX$ZgYFpK2?11&-jc4-?dx{lI~trAr&ieV@z>J{o-^GoQP7N z4hI$WdJ|z}rY+DN!rngG0osi4n&^GP za)mWm#5u)#3wgxVEnHVAuU&h?;5uyo*wn91Oq%L~Z^}sR~uQddN8KAT$tP@tLG` z!LIdHyiPRI5}&hc9$xzB@~#sc$5&akVHDO|B3ryAT>|^@Yr#5%sawaS4w+iB=>UH% z0)0w#rLw}k4JZuR|J-@;icZC$GP^}zz6ml&BbKE@W3YPlFfgRo8Y-D)%D!?miWGXk z2`6aL)7S^nS@|A~w)3m%k`)CsrmpvJ^4J9(2(PFL0!K?Sbvgw})NnaD0JE;7Ecl~{ zTH#2f;Dc^Gdwp+3eRwv8u0j$0cshro^Yt$xq0m4L_L$rgy6^XwCqM$?N<$`WM_$ z24f`=a~FGA{<+!bEDa{-hKAL$G9ok*$cDerx=NukoS({5@ za=XzyvL`pZ1wQP{OojHsYmNWYi2$&nH5$=BWKFFpoosPbZdcuI@Ny6>+WU^=uhYEA z*!_$0WjZj{baC(Bdo9AKyp!igoqB-&ql71NrZG2s9pmwUJ6>=AB3ZlJ;5Vn;Mf zLF&_>=N`5jXldUJa8bNa=>GQ7ayIb4!(<(>M7T1_0XEJ`=sxN9z+X$`pWFbsYJ2ag z*31VGjGAJcYS-I9d3B;IZChlD&$>czbj2%#K_&SUt+-w>>dI>1@^vb(Ub5Yis=^nj zI=3hdC&_eo)O;AIs5%&Jabg*wqu&3+94Cg+^aJ2n{vIQTUYKN!dt;MQ)+D_;OHQb) z#L~H8%^N^~1AH2Y&KJLWkayE#d;rp744RA#jinWPmx`24 zhRxC~jhl!j{Pw1yGfK}c;UYWnoyCj2v2}rV2_}bz{vqp(*8MI^C3L!Wt+;(~TGz^N z#2kvzh5Z&=)dz=dNa|QsQX4h-)*HkhX3iuAY>+6&_a`lmbJG((J)#W9a+K7>7VLJ+00_@;@x5e|)+xvWVi?M9>gY+^@?#C(rZXR=pZ4T+@^Ed@udtC6{4+$MGf92;vS zgB21!%t-x2Vc$2LPpb(*pRS5!=y>h*9B&H}Z{(#C1rv;>sU13eJm%8@=8#wDMrP%M zofBZx(^!3_;XhY3%L=|mul~#>-^P!~edGk|uiKSI~Qnnon6ix2#-O1Kri(L#hT9gqC@&sUCx40k=kzFQ{{wu9#v z7)l=1U5u=gU0RvsKWR{lAu2z1KX$YP=?GjGPGTyhEknkyEf&g^!A60Y-Y4;|&Xt!l z&?yrSwQNMvwv!cu0Qz;hck;NQq`MBlxs2j2U;2wN5DDnw&E|TW`vKnTPgxqP2Ko$1 z3kEP0Tzs$fKz$MVCY*T6$@6lBAK2h_V_qGnw<<0a1lnGEq(Mu6(zbff6f7iL=D>o@ z3~bXr(r`HV-_`lw0A;O0*{oLAJ(iOQyr9Ez?-6MgeOYV|A+_(_0NTL5e-e$}a^s73 zD|&7mu)PT4z^=cbC<{e~X_UkmDUYjYK)1PXEAsK`4( z20>?Wm`ERFV~rd-N&{D_7dJhR-Kx+pDohmhQS^+eGolltPiMtf1u8iCGe3jx>{J7WN2u|IUsP#n_k zyeLbKhdTL#Ug6*uP#Y!55_;|fr?-@0867^IokochZN*Al*Idpz+akXb4;pmz3fI1h zo%3ma=()L9P(u3{Pp-8=fYux-^PsUi+ujytcrZTQZIgxY+iENpX@(5==C^L7-r_Gl zd=zXs&4b7c)&$4OQ_57qvlv&E^$)U);W^wh&PdfIOfP{R5jeS@OY(Pj zJH`l|3DBmTI2j@&2fjgGcFjfcXGT02x!4aFSU9uw)+bjvF}#XHAz06L?SZ0uu67qg z^=zCoRFH&4$iVL{LdD4g_r5;hPAYHoh;q3!Kj}evYMm@!p;~8M(8JF^eA6l_K}-V> zmhzO1$&OdMuNJ_daJ`33hP!k^xLwdy%!yy9>J_XH_PYKZZGP0f3Y~#n&pUTlB3Ha4 zm1bR>+&vU}kcqD^dI#Z&{5m!%x=0^m6&*)(s`e440-CWaN^3>9qMmJi@ofkQs`dAXFJ=DKgLqzC5v~F&u~Ra!s}jM(!iz>X zXf=Dt5}|wYkyr-d^ytxv*_eB#kZC~RHi~g=2kVWAogh41`Q1}yPQ>Z$U_(J^8?e_8%@f$>A zz%cYn>XmH)N@WQLSLd@k z!E0noB?ann5F!{{Gwr&lFsVaDPu1Yw0s7aBZTp`&^|0j8d+qv+Wy^RJh}>wmX>Vy8 ztea(|A`#lkoCaFVGC&%ZA!a$d?YOZMhY7#oXIyOZgxz}Q^KMB&rhlb6a5Uv!I^LG@ zp2L|33|!XOjE)%Ln(=7T0a;Aa6Orz@&p>dQjOOuaKv6J+wMUtUH_4g5=P5Uits)+y zZH`?0XKpl!3>7@7(JFYe@t;k@mWR*svnnBsy%m&CYt?tmKbXK#^Sv4NXFR2zUWOGKBl(XylnYeFrXGM)5*Cj(B@T%L$l(>CimzvrjcIU6(4ry*mRmMykL2%kCD1HI6*-**FwGN z02ho>w)%?;9foPLbr{n1p@H|eO{#GtZv-V+dxE4#eLHd5h`?iL59Em#SV&c$T|Z#C zSKSm1uHx0!?up7Vtlq)B8vn(EB9x?SlDz;R3{M5_UBcO(a}C9Vb~{%ejR02n8}tRQ z<&?$N(%%_jQ>7wjZbFusG@JHagWy$jQg38=$QSXJy7IK)K~Ry_K6GkkDVgJc=Cy3O z<{8?`!e+DuBgm0aGb+pN-${VrT1%TinY8#YdxHqJgKBj-jpCj&bxVmozQZV-z;oa2 z07F2$zi2;RI?8keRmS{uhQ<;@f>Jl`)ZKRiC#o?-$HE6aU^I(je zy0s_FU;2kK$@&FNnA}Oh5E$8$;bZcBlR2}K=D`wz>>b0g7wBTMJ%@8ti;e>6WW#9U zz^Mo+cT=11bJ3{Yad7=klT1DvQy2pKb;44V++~5-t5eETDSK>E4Xge5=Sy1f0!KRMOjYZ*Q={TFf46=v@i+ zuIJomyqp)8v&WZ|@0rInO3NSXaOT1qS9g-vHo}!xVni&@7xp6`^Db7K489h)U&JUv z-&7qL4;;iNG&*|%j#%*v!P3o77ZS$4EGsT)=F0cfyNdx$4CevAr(|AAwvU=$-Sn^B zL)ZN&+MSTtw;R>_y0trTs7BKNevDfxhVM8*DJ+A4460c4I>C7{lW#~?)mQ>1jQGw8S*9sppV%rAZ!O5xMV8) zc%FU*NDYW?W2@$OO!s#g6Rb)P4z6Y*kGiVr_CZzeJ=R-!{LB94CL z;>oFlDb6@ESv!4$(tKcBreq7-f*I;hR;{Clw$*qD)+ftA^r?g2`Q-QdE&6~vTNK`6 zAgtf>Nu=u@*f6QKcK0>?ZpXz_8HI-OZNKP6EjknKrBYf_Yi(jlXBdD`=x^DNl|ma269B3E`6fO zRzxCO@5l=~%W%d1&?h{T8)L5;m0!zz!=eg(&2GCMY&AjVE${=llcs9!-C%VtU6y_{YW4>iV}!o}*O_>bqs(XA&H*g{IQBju3*{*C6oBNhgV zc~j~tj|BZ(kWT^p)VARN5$k`bi240sRnv3D=}>$>K)`!Iw{8CzR%+bF`w}fhWWFjC zIf0^tRHlPuw`})h60coy_3n5zG^g7Ll?tUy>|L;M<2YP~gqV(*OnY1Cr>Pc&6BCju zxP->#Y zNa2FzT>)n>pdfD^M8tprg6z78)n!}PA@P5;Dc|Beke#c8Lln6(W4?XMtf)>9YLdzt zNPh21bLiaS`iF%8yYHttg$}=TQU?)KKWkZ#R@CdIW89anNj3}XUsciP-GOuF{5aD0 zJHn{ksWv*FbM?w>|D(?)gstfTl8*V3Nav|68e6Vv$1erY}vArq#0utF1TLo`4a?Ot9UMsMP5 z81RK$>n_A(_zLcQaVAA3X^PD*h%tV3KAsXarURx)LkYB4Q&UYGnvRR#t$RNp-vwM+ z7|u@TkWfm9D}Mau%T;~U6trT*?%ZFOziCr4MwVe+YVQXZU@sT4k*QNuGjP@=DHlY9 z7=q*!gNm~N)M3T#q_06XJWba4Qk>=UNTUx2igK3c8;oO6hZWTXou{S2V(ne9f~Xy`_04Yx8eX* zhALcWCWI=E1UUK~v4K-jhpM2FcIJws=vly2z60Y4Ucb+0^TH!K7TOYMedN3=nPNRX z?)2KS=zGu{Xdm41Q{Mo+-E17Gnj;xc!#~qE<_r;1-j~PyPlRzOcU=``VMCnWMiUtrwy$92m}GtO!HKv zK@29vu$TtuDmWJ-2}bwy2F3+lEMJK%tN#?V&NfEN#Ehs(d)kvs;<=8_z^2kB! zHY#4{QycR0Z|jML6k$E8Si9p``7LP*m3Xpvf2feO|5dNv2&&gjw>}&rnValy-vr}- zVkk$+pb0FN>atdHu+~vRs9n~`>3F&!Qt=ddy9w5hD@!xci7%E5TKseubuu5`?o*e$ z4B#MmH?TB)6fk3=tqBewKAQbh!n;-*4#vPbcVaB z30;ZzC|F0~^)+xzjb^ib9*NCcZme7dJ5#^qq?!9!GVu%^*5xI+jy_xvvt?v(tuSKH8sP~7<(IAtp>3C})Fe^#r@ z={m$iO-7KvTR+h0WY4C?vM9Yv@l&g5QtnA*_a5g{Ck%~ECbI*aMopJSf0{RGJZKQK zy4{MLxXB16735zB+ZpxuO-*JhWo~j|L5V=35}}geu79~$Ud`{@jrT@xoX#PqhpRM( zS~FWF7MZd~dXdX&KYrD3T4hXA?{MSv$fzqdG1XqdUSIi-)NTR0)=(sO46Ql?_X7W+ zado`VeX+Z!aZW?G^ggJ~piFbhXijG-Qpu`jK$Fec=!rr&UetdDQZHH4OhzFZbb{Pk z+D+#Dx3epW+@;Tq+G{u)s9~!dd9uNspt>_U9DG`n;Gysx&q3&<*0Z1;V|^bjmnE1| z=OSYOqt!tMrs`e>{-F{}r^l<#G@}H)d18P3z{;Rfz4y}f!Rx8da3$^%3^)5Ev}Jdb z7n5)PwHHZUQ6qa{!6Pm8VRU&=y)IGxjE!O;G4t3=8Uo=b=B^^3&zH`cXL85bTu9gK z$LQ3OF!A?R_SmOpj7R^Ur#(i7#kGzamjaZvEv!SW&^M9kw27kev&kE_Rcj9oMpo-7!e)gG!aIJZTsZBjfv7+zgJ{X1xOMZ z?~2cX;7B9HtN^^uhDUr=m)LM(-!?g(?NJ$IT-TH_fKdMkB6Jbpw%bR z5lj?*{1tb$#-5EyjNMZ?Y+tvlzsr&mi&Deg{SQ{OV|8W>#OU#ahL=0xXY$$E`9%2} zfLlLyiL-oI=c2YS+~eBRge}lkV3RnKnLS#}u0Q~aqH*v30NV><7!ch3N|bymxj*+d zjYE8ug2++SOE`qFcK~x#7m<5~8O$V`(p6ct$b21Pr}A{K(sL%1hBl{FhcAk-5W-y8 z^JZbR3zk3C<&A)RTy?%2NxiPX!6XtFK)Z4nqVmpf7RJx<-^u=&Wd%xkoMdPZtM z1Axs-91mz!vCH2%C|?07)$HMOf-C@?6=EeGgPiE;p-(+SE;0apqKWoXTx8`M{+5Ca zQq?1F)$q>KYM05UdU;Q>-)#~G0W@U6_I=T`Sb{@kCJ?~6)<*a7O!m{G~WPcIWACPn71*8$ARPP0O{r}F>o3X86 z;0T0it$0T^^0W%ww72kL!w@!&hlL9lKGxH{cQR%o*~)S}_Moc^8FFlLsR0T(;;iG$ zG)0OovtPp&ylsh!Q-}e5aY`@Sf@Lt%FV@Y@~STWVrP+GtGV3aR&>-)%Y z<1Z)5-NJ<2v;MvCX)swn+$`Qkl}~cJ6skBhHwC-8>>#)*9VNzdDN-tvUz+ZPw6lw- zVq)sr8XA4Ij5ufaXDr5hZfy8jyHC(oC$|GuuvSigtgtOxzg}Qz>whn%CH7^JoHjMn z(h&lrSDW@CyTVG`Q#C3cWze|iY)q4jRa<2%p6o)T_^)TSraSrpTXHD$gqGjrDXt%C!s3Jy}Pi&?*afkMAmZi+*H^grjn`Aj-hg^aNoF00I ze_i}eg=lc5u4dG=zuDJSx;vgQQ8h;;QKIAFJd7j>?UJ4D*4O>gv?T2+#sTKCF&BnWNM4Qc zGR~{I^T)b!t0Oj|_s8=LP@6w$P^&ZSC`T8D%Y@L)BwU69f^Y?;CAlF3+3yHrAdJaCjh4mzT6_rK*{rQ&_a8 zu38y!;%nEU1}Hp`$f*x5Pi9Jk6Ss=wf#Xq)SX?!M5xt|?@FX-hAV8OVA^R_8W%)1P` z4k|Ij`W<0`1%+gqbkL^EXrN*r!G6o&5e6dXhZO*CSBLpI9 zh~oF1uwT34R9&zKHC)@0ND-tPPvDZ^t#J?lwrQmsNw0PrXI)*VU7S7f0?lb8tixD! zPwJ$j(75t{x?3Cd|2b5PXH@Q%N9Mv|8x3zL^;FA%5|j2|a;MSk;*Dcd`(a>)e*36 zmo0G8qTyfXU*KcJl&pl|u|J$};mcB1J)CJHK1)0f=@$#tgb851OV7pumhD+`^em>` zX%*gCkWk`LMlRq~w!bSucJ0w5S(;6x6zL2%C;G3%@l-)7B_&eaLuZg{5e zWbe*Fja{HLYL^J7%BL1Frz;$_tAAm%kr+_Tksli!uh#f!=>C`C>`z55FR%;$x{myd zG}8K;WR+Quh>wp;_24r)I(Y|pP#NhH0=uno3rgcR?G#hg5!B?{{Kf3YmgTJF&9*?* z@S>c@gO&7@mN0^&o^}t*g zDx;(6uYSbfz1C*75nr^D79sUzoybT-0VsV<5j#p=g2bOZ4|<4n0R}&)pc6uSffpyN zMcBDKuI1#cI+F%HeIxW=4;Pi#|G_cp#lydpQob{+qLNXfabcc5azg)CK7&q4Ic9;v zcdHPoA3eOHY16b!&s;G9Oh4OeNmr^iy%R4E)pt*2u)Qs&I+NO{i{a!--J^G8X|PPd zgroKvA(@TFFsVz?GQ8Uud%8t-Z)rz7H8}j43%rZBjJu)2TGsl=kf&psa`lnpOSan< zWUpYh(FZ!cOY4SxV1PqrFzfc%RpCiRRo!*_-=dwscEfZb-XyxPC^qyOzwUCt2af-0|TR{@?WBlnre9kYO72!04Uf2R|uXyFw&4| z5GbdG14j7PsnJDdcg;zo9_MYA3_#5-(E(TdQTg$9Gy`XWmI6Z!ugVAsE;+z*>WboH z1mjSp-y(c!60*Cs8PDi1P{C&`s=d9SWHqbJ`J6RzmrckBWUW`QX)h>?3)A)RN#5(v85Vx8ob3P41UgjtxB*FJU&>V zH`rYq*^zrE%!8F_Lj~?1NjRsk+JJ>@p-g;(YaorYzI^R5S~hlqfBBpRlj|_AZg6FwSC)&J8HQMO+NbH^8j{Ey-$T3A>I>pz(DO?B|HiG z5Wk7hASUbJr{UnkfZIN3SFddeg|iI3qIdvMyZOTWzzrxd&f&YmQ^XV}$~TAL6lQt8 zDvE06K(F)~y}Sc_4O#}Qx8hed%=^%+JR)dQpM_9DSDxJVbQA?E+Oe6nv zP7R1Rnm-czwcGOp-AFDbYN*$Vpki{X{TT)JUGrpSX)(WII_>7z5>A`U7vAlA=!4Y& zmt-`NXz)#HG}^G6AS=J}F9}C66trgRfXuqzX;FD07=#ks^VH5gU)@&_~f= z;==RgU>V?eV&Z}=cN-AAYfnv#G?K%BFF}%flw5bjxD+gjT3xU)_?uQqiS^2rV%KF5po=z(r)R7{ zIVnM2=RtG-1C74dhC2Fgc|7}TaYToZ*`JCY+3MIT^!oWmtb1LZydfSK;6Tc1c#%_z zdIT|mc&!4lr+E>94SF4u2^Iw&BWzLCl|IZ;#FTb`3^)ei_E>|d1R!Vy2Z;fzCH@fF z`Z;NjDd`zvyJH=xMf>tTam7peE;A3z-&`NXx1_z!Gukoxn|YPl7&owKAYTGvA^gka zkCxDmO$M}T-K3bpiOM4BtaE9S(r2Eto(+?2%TfmDpjjXJ9=+o*@BA9Ip~j^Tl3Kui zmBipXyN{qhAA_lEq?%*Y)P4iLOqKh)sK2g5NT75l1t#avWA;}Y>CnQ(C8i=V8s(@= zkxLmd<}aqy&n2ado-kb8gH}+WI@lfKQ~+2`@d2~7F_HgDGteQ28zh%tZu=&nNp}wa zD|Mt|`if8%XlK6BVk<$@!}mdakASkdE8{1EHQ)z@kK7F1NBFBmKGvWW8)zsPH>eYH z0ROIj`Wpb;&+Yge*uI82+XF4EB8$W!-O})Tf@bSY=x&C>kp>EE&oemqHH&Yt)T=}+ zcG0?UgkZIeaw^D4_PoQUSF+|4yM?V)rOFrq7K$(tc;kw7CyYRoQqxvt0A zeNXSGWb8(;__i4<0l;*c&SlOnL_Y+ixDarm4fh|;ka{rL&1OUCH9OtJ=7ZP4OA3@A zD=RXacUy+`hHe@{sY&TL^0aFXVDi+r8i(tllYcOumiJu|eU3L0l)kN?$z`Wc<%?w7 zR}6J%>%V}nQ3#TpTg-T3RfBZtmZ_%7IfKkaTu~1Q^LigIJVvcbvJ`K3MC|9eVj?R_ zT9STb%VNUm`lX9?9Ixoda_;quTPa$q6=WS3Zo#c6!5IDua`Vf#Cg_|;IK)*2;3-W- z-Jev)@I9AohpYJV0~?OZND4=KHm+@&*lUL5^%jXjcqG;*RBn0cHd65YVx@jh`Jbz0 za2@i;BWBLc>R?ASjkI}B7f-OM*5hu0fZXYi}%EhyE6LB39OK>u7+!ptmAt0#<*2j`NZd0 z*!ueE+zq)U=phi%S8VQI#C?>^b_lRgKW_*oCa9@t%0t#BxD|I4Vm62B|gX$cX zl$cbgSevP=DIFfBaorgOg6WVK0>hTFt$$+5YcA(;`$U+QiE2kOSY9?-Rn)r0NRoig zTH33ql@qXXe)RUU2~o5Mjh^= zIE7)-K~UOz@;W_f*Cx(5lLag=VfX|DpL-ob%DKxjg-35H z+SdV(IhMo{QbHAGffN)HswV7|2gq>OpqNu@HhFtwL?WY%oj(rI8cyzr{98*|LjPDk zaR(^5wuJdxH-IC?!bIBX`?p6~Q>sk9U+5~|);>=U7YQifpCQEz??WbX-%`?ZGt%js zk43@|88YAQSp`I;(a$c~Ds4wI51F2Q4RoK2cs2&ZQ2toR$Fpc~IQ4IiSh?fGTB4)D zN_u$rw3s)s3VD0z2FQbxDiWaQFU4lDJ>*BJ1v?kL$edCi7+NLj{P}`GMdXtr*^GoW z%RD!6wG+O9cTG>rOOujWn<6QewSsW6UiaHB)o==f!e?1Dh)eg?7~V8VJNU(x?hD%e z%6*!%ibLla06~`|z7>Zr6E6<5(iMiKhL{ixmyA+>aW<7FCp}n#E-+%@z7`iy0bqCx zK3X9=T6GtGc`PqAZ&97(G#kD3u>a?Uxc6&axit?ObNH{p8E4&GLjS(VmQ78{E6(Uc zD`8J@wT*CvP2&(CJQ!HL__IrJn%8{aC-0~>RKx3x(HiZ{Q23>a{bc(F*s^$C>&|vr zXnc|peY?rOX+*|+p*p<=*{=Ei6!cTLYmfDdw%pHln_3&GhTej7=o4kPO~tms$!hkgEl4h6|wmE4B2ruO)pkK>X zjJRHxH6NvVxD&rXU7*e7hl!a=dx;%H0taB-kH*={{IpioC6&BS@(1G6bREsV0lZM= z;SC-RIGMnJ!(a=Ap|NggHp6c$bR z^GUQ^e|!b-M_n>|CPLvg2P;O6Q%#6O;@G{8*%SS+=A@{Cq%(m30dI}i6=2C#uHwh{ zo$T-%1;fHNCyNH9Ewczmu&%*}(#oe}q{@)A_=m{E&$e+O8yJ+KFqUi+3_VrsNFED$ zor6fepG4q6z~A`Tpq1Br#GXpJTx`6s=ZX*Yb@$dV009aHdRY;d)2|o?){K&s^gG3t z1(if+@&XXI!m5HBB*!#Cm)L$s&PExcVJBiQ%-!av7v9-HXH^49W)kgrtA}=xtZQO@ zr;(aFE`~Y(ssOfq9=qbzSACiZTv`=gK5%Akgf?ojx_Q$YxFMPy`Gh@#gv-O zrYo0@f(a=(2Sk-Bu&bB?8TZ}p58WvG;M`~}$rTyi$T<~$VHvNTfCo4gk3~^oHYR?C zk*vZJs{m~N@`OA*h=74QnDa6SY^jC@pDXi$0u1);X&&16ka z>|T3Y!F>_WtyX=ajgvkK{qT8K-SZASv@%{LJG>?xftE1}M zoRT7;g&i~StQDFOs`jR2`HUf5mqq@*K1`QHxjW6|ZBjuWL0Dyk?ojyRhX=jP2nBRVHe?)rT>3YnUS}(#)cyTQbY_Ip& zdbc-6Z@9O=@hDf)2<4C-bY?xi^yy&BP7-&IZh8TI1MzpUCt4g6%j$06dzfp zAc+a?%ASGzd%l4CLa@xbFL_Mb9<(f3xGQS%#~J)CVTB)#R*2bZn+?*~o zxP;ZHS*=e)NDN}sV0TEthD}DM!(8iKFP93&eWCsgKhE@Dn6_ajP>{Bti1}Y?Jx^=r ziFRt8@QZ;Fk4NDt|03)%b6sa_G``ve#}@e;xCyHVyl1OUkWjrGg83hrBlIq7_BMO0 z!jxswp+yrP*hVaX@>kWKiUjT=3FK3GfV@nrEmMv}Md_vD|BP%m#Vc#pKfB73iPuiS z3(JULM6^MB_w@P=&^0{UXS)%w5lD~KgMGRf7s<0T@W)b*{<-?{Y^(SGH{!$`*beGq zj~W^fZhXsTZ=YAPofj~D?XOL%U^Ni{kIu(ie5nv26S+&T=Vhd>AFD`?4)QHaiVh8R zma5sR!a}Rkcg#B;CQ8iqu;=L~34T1j*OjL0*V95=t)J{SA(ELZQ^n?aYb>tPNnB%T z%afQa&AL|o-=TDe?`&yjX3Ix_7PMfAOq^$0%@B1fpvkD8Sm(65gwh+6wgp@z{-T%d zwh5Zj^S{G1X~;LhIDVG(@5Qx;(Z!|9$G!^AN%w@BWYo~0rYBEdv$9fbpe5RYSr5Hk zFw_prULKxB2*eAtdSTB9$z4Zu_M^4SX1n3D{-w&lf4)Rn*;schCpslLogk~RkbZ_Q;E+@YQTX%GqF5)ZJ~F`f~Al;;(`iu1{t_Q?Lq3GYF& zx-PVP1s(tfhg0_AS%%YSW!R}UfZc4n#j-P(`#B#2ng%Fbn#h^sJMT9SmweK3goU<&WERC+= zJs|^gvG=T3LAcl58A`jvUSza+xd^oms&5=-dsaAP`_hUfXJ_;FKa)L>F-Uw*kA4@s zyqPKiXU9{aX=t_Uofs$lgb}?)7F10L#SF||3!7%}2C?8xFpBDewq^-Tx!@`5M6^8| zr~l#FnV9sdg8~v%NVV(w7KE|_2YJrD*1%tnUPrarTU%v8b1Nc%Mo98UKe6tyoomp_ozYzPgNmnmWR4 z__Il_bcB7~FG!re)JLIfFJ0Mcz?*v(tvNw{29m*#Bnzgyf<+ zG1_oi>jQtzN@}!-8=2JooJU&|YjLroigxEX`ZnwN>5GMJ$j79r*z(~Fjnc+8?zo2@ z;kY)yJa5C{l;%nDn-l&c?|nO`z%Qoyy@=&iw?A^Q}Rltv2b#P3oHfs7Yq+G~Ko597bEEzU3$rf1?nQE5y< z2~KbvuAOrnWBE%WJi@O;(M>#G`HE|+hk}%V^e*x}rJai|lU(+WH#~(Mz?OTzw~FX` z`7VH6t++Q4JzD#03@%9vBT$1@V99FGQmI0gswG7P!6GT}2@k#@HiGCNJaP;!Pw#d? ztQXLQO#ttSeE-CU-}S?M%f5*>*go_~&Fz#=^!Q{vjVB>y93+^!bD|}u?V39=qwwU% zLi|4WC*ob=lrkUWb*~TWQ90XdR2KkkNrkm>_ME+c`>yYyw`|Ne31$lS>mBi}ykGX* z@WyX;Qh#a4*Aw8MyC=WjFB6UtU**SXo;8`R4Yg{;r;iE`xi5_h>Z{NY*Ljb-BCH)Z zU2OL|Yn{@z^e%ugKg{WeCgZ4uuc1F^i8o=J#guGOZN=A2-KcVI;!tm-yOCLzZ zV{t#6;YCD5c$Ef{D1%%fDED$v@WEWHbYx&(oD=cw_YIRVz3Y=EXYr1FQ+vKTsmXhl zD3i7oM%cD03vrL$Wl<1v5p+Hmbzp!d#F?S|snKK0o3YAV{a9Glvn&3b8C6!D39#yg zXPEqiC!&uKB3N#-F{yEL+%jLMp7;yoZ}bDs85V9dGoGX|ta5^1V!ye-qi4loec!9$ zVuN$#?&Ot%OPRIMi6~+}dASp@;ly5UlL2z4+A4%RgX{XCj2m18!yvx-^-XEq&3$ z2jmmzF7XHMs-`=fn)eyh&~01QozWm;Mwo^EbZ+A~Yafc*MPfy0fGu~qB$Z?r3pQ7M z8MMAEP>3!KbBZ?&X{MAX!dR=9*hMx<5Ez=kDr2RxSOLF=cpT(jw4yb(2AMyRw6&#YY3yCbR0&*8__Ij80+A*O zDn$?{yEdn!Eg0wcKF4rqG5A*Lo)ZVCmE~bvMQWiiJ1Ro|>G3qp4uWv;)JOJ9JzVW4 ze%GnnUY3i-W|w0 zN)$~kmL8xb)GAZmjz(@9QY~p}>=#A>lc=2q59TcfW+I_{ZW; z&@JqkNf+2}7WHA51d@oKY^xJaWvxhwnPo&e{OG9OT(2(sbSDTWBV!Hfof|P9+kyce zL3d}SdBp&L5BM#Uvs~n%Z_SixnSN|0eDoyH_qK!01P)Sl4dS@1i?bd%az)cu+G=S zrhQm{ejX*{xp1>BZhyY^J(m=IOEYbGC}&J~>GeC%WO|1xou0v`4HPJ}TxR?CflvM` zCTTnL3!zmav}i6WaI~Yf>nos*2TpAV77|;9;v911J6aov$`g5)DR9jo<(~(i#LND7 zy|yMFEIoLUXzoVw&Wu}bN=Pxhk_3tyqzI4J1`~lX+~^TKP<{M4L?Fk^-&5N<$M|@H zuF#hij^!gP0&IQ4^+bMbnuA9`uM?OZ*&F!?XsdgP#J9w*?5M|2oxY|6=LJR*?lK`BS9HD!V~e z?%6i^l18LsFM$aau98_p|1FZcF%QTnNVXcnx0a&&r`z>QBu)zZ&&3tJY`eRo5TKm) zXvX8iz9Q)?kNnN@-rN0}z)B^qo;1gH$a}Fk67)=XtTuKe_q!}$4`?3R3)Y0jO5*B} zIp*XS2PlXJ+ODoJkmITv>ArEAc6+$wd@)$VH1W^R2X|g9JNE?skf2`$|PWP+d9h>T>6Lv8mB(lqC>u0n~v}Gr`7L*g{WO@MfNdTfNJatYRSC*;eXcH zsLUgDmXXjhAmalm-BD`fYHS2cf*07dtG$}TriP~kf`nhF!aqOpylS7me(Gqc%9 zvQI6AC7o_a)FxdO_lhFg7I_!yVApV@NAn&Pi(HC%CQPJ)z9Km(8XANfk^I{6HelIB zkB{aP9w0^<(9pReVOYm^Qvl6w$(m(9F~GU)@!(a$?2m($RR@AH`++a%UA@)a@$-w8 z+>3^W!V3wX+`iD>#n~qeBdpZhL>7pJu+{TimfK9piO}weTM)m;!6a@4fOL-rcCbUB z=^b0op#`a%YV+UaVjuO<_Y&92(lE0uproR8<2;Sd#OL!DjcV*H_EX4Pb|uk2O2gqH zTAw-lnB>>(uD=)EE-y4yf=2_wTlz(-m=(0axjwRA6y}kkD*;S~aKZ83adlq#Pd5yQLMydF ziEGeX?i+UoklTPwsf3h$yK4c6!m5Bs%hT`q)~2Lam%8Qw4W#D|G-p9F9aoI*Ig8~Q(qx6f|!jmjF?1NbyIVi}ANA=;>{Y0K-?lzNEyOG6P35-)&9cP*2g#qH*h@CYKC#-|KM!qI2LU^-9za|4B zA(sCQQL|^apOQqei?vl6w`OT(cMxFUjC}Far1(6qjsq!qfFh?+l}wWw+IeIkG*X?8 zJe>bedjEMuZ}b_H^v4`8EQSdL;CZ5$pWkuMG0i%M68gv~Z_ z++Gl-_Di>#c$U*jThg@WA@<2MP?u#s5v@l4|BsaRv}l-qv0MCOf_0bxtVG$Dz+2nM z8zInSxK-wT^6)cfXux2WIm~jBtT3EvM_lccj$0h}G#8cYY+b+o69d~6%*qg$v$|7j z$WuJBVG^XtW<4A(Exa_r3C8fKNV^PUIu0U_`y)T1&PhuX`V8qSuj)!s`ry9B=+@AZ zL!7~u3jDKpR9CA(6T8Koqq>icJt`Y>x)N?@h1arP69b)+#j5g`EF&i+VSGj6MFVe& zS)(3q2%&v`gkVFL#WXbBX$xAaMp(t9pBmqoh>t3PB9)u-l2V^;vvOSBLswW(tk6`M zK4Hv((}5U&@M)afYq~F>r|M2ahUX|@iD@E(rtZmY@8ParYzm>*VL`augi$XZEUt5~ zZtZ_e=SD=2TsgCZ{guKc^>=P*3>RW#$lHn$eY;QP&RCKeS8N1f+h*ET>cbR4sH+?+ z$9!3Z(quDz{VNSdcb&E@j6cLqyZJO_#XlFS*aR%@`c$_Ms9#hv;n?0n_o_45*@*~x z_EBU?pClbiQkQ4A28Sd3#=Y(0r@#U8my6JRM@0b+JI#kfkf;N?#zc^7@o?ghZw4IH zp+jEzJ~#L_qtL2z8W|!hF2S)QDzyK;;86Z5cX4 zk8|5*JdFW|%>hN4D`$6Xqa%PuxiL<-Sv>#l?w?lHS0{k^A1x&|O}2dU=0%9Hd77&w z&~r7I$vYk}+VyHufE5>vD2!X1nF3krx(XY%%6o)8AC#HwoiJgLhAwC`30yDM|IQp7X&(lS=+vQRUxP(CQSUX zQL#LtBS2m6r zx?h@4?SkG1jdSeFu6iBTcIm$gF|Kx8fDp7``Y0Je6p^+ddFn1x`jSIwh46e*S2Z?k zI^=jCf8yA#*@Fz$sxyb~=jd($*mpA^j;-X!k#2ZyMuMm&Qeev35~UXKrkRHDKNF>& zCH=MMUFSiAzc3hIYb%b5<&rd|c;C__Q@6sq_9|O|Ngp0(o(ZkGkqp*_Um2WJ=unu} z^qb*D@%di`g;8ubNqzi`G~)*cSno9u7s zE!>_HRuG@4bG!e)_g!Rc|NRb;152Z)8r*N(&Z$jHZl*g@l)Jv8gS-bbMM^psz$nL5YD zE*HthFy!a2q1b6+jXrZkzF<$V~&W8Rdm0zK4=2WuC&!0oV>e-veE-{{13-r+8s zoTo^R>C{B#C=c}*H~lnjmgI?@?2g=y|B*-^{j60d+c7d#sUi-)o)yb}_LY zwJ{ovum=)~Rx>jV`#LSy?%x)E#6b4Qt+RN+6F#fgQ$~@v19xw$vRL#H+uLpdZW5LZ z*mHGP02dweNtw6w_~w3ReJY63Lnh|v?`QhHoxFRv;k_^Xen;3u*Zka6XMDMOjEXxK zAKedvEY`nyiemKDaf9iMqj;xy0>cKOgf435i}h-bo>oWGjvbG_^zRDrzJQu|R&3h@ zY{wORJNdAr3%uq#S(buO^_RE*atWjKmcOd(#(#1bvP~7iGvR$ZFVB(HFjJT_8wa9c zYJu%BbmRxzcHKz`UezAIEsA#`NQxaPt~eDhxEnYwRm<4CuLez8l&r8sq83?qK2&ma zV;>KbdxZ!?@R&Dqj~$;??yrmrHdg zaBu!KokLcD>#MX4dat_$Vuz%6kJ~KVut-?TK(iE-%PHzTzbtblNsTg;lR^>LtPWao z@7NN}-RKa_k(=o$R;W4IH8~;d%Z^wfKNYeSaPBRl;ukBF_*2L`aXT-~R)vk1F7vLT z;~I~xvDKAJo8ADkaXN5XbU4JV&$|aj4LwY;?+%(~1&0!nu2Kc7|ceq?C=})0{Lclz+#-B}2qv9E{mC+pV1N)XGnNQ(2=hql|^i zl>;?{s(2rh$bef`e?XrIT?-$fC}|{I07XE$zbwnb#Z9D}xCvsE)eTeHMuVv1kmDy9 zUt$y??DG8rBh19wE&q^37X063aS5|-A)Vqg7PMt^`u7zkG3zZJbV`xxXkJ|B5WzmT zr`{>TUhjarz%3+$sFAOZt+iqg(uM0C)`AaUsTBt5MKe5Q#_{6%yU=WP{k+54V2@Pf z{R(ENbouZh1`C)eTp5B}P;ALMhvxL)!RCjrk_-(osSg2ZRB*Vr6T6}R@X0ZU9GY9T z5t3iX49=B{j!#-y8}XTbLGWZPiG2l1St^v{6b})P*-bMoYHU46PkI`6PONeXHl0Z5 zduDf{o@B8^l(EN0-naaZsATRNpg~n^+=Y|WAjYvGjd5>P_|hGP0@V`?>#^Y}Be^Em zzG%%(@QQ4{J(JoM!s&#T=U9(rwtGN?`IMD-f~D*6N}F{pN6=3BA1dy0sJ7@bCj^s- zO@HG@tiQ6965Tm||D$3&;;m{l^>dtt%dX&1`Sb20IfBQ}jU=;};j2CXs#RhZA=Fj+ z++z2N4R3p9$#06EqK2Z`C#zF)(_WPMI=5Le_vufz35LM3Zj>P&Ku|P$Q4TJsE^OX6 zFfLjAPB<8R>;A7AdV~)%VPBLqn2c^LR(84i+Q`L18rma~ih^ zs{G>CB7AlU7-5@{X7)miAEzjT-_WWro#!jZlqG7hKecE%P4iNULqtL}@n96{Od4|J zjObXz?p(GEQ{CX1Q@A`(W`W;iWMML*sg=gqPq3g=<-)T%cb&kt+lbaN4swdxpz|X{ z+JzX_us0cn@uhH|lB`!0Nf#x1EX6PnxeB}Cgf%F|!&L@qXUf7DYDYuA)=~PUQ>hWu zdu)vlgt^ZVdHERNT*4s`Vy@9DO-D@4W;%mjNUWtb+63rLVJ1mKU8qry}9XQYG!hw-Wnj{ica@) zk+5oNZZQTzb-PRa4g~OwyMn-}Mp6*UWRKH=$5C9LX`PgIt$ZlXqhS7^DoNnCB8*!b zwxk;Q%fuJODta?N7U7RYKrbX?nV>yQUqt4d;%uO+2D_1+q-Uw?o5iZD8`ZB$QNH>5jz}UeJ7Jv+45vo*Ho79E)xv-dwk&i5O#_vVRy-DZ%opcCrJR6~Y6ZaOgmTo^8&!kE zi0}FB2AL6RsE}GE%pS<_zR1p3czm05)!RKIH5Cj!3Ncoi(iu)Vm85iH32lXOeN0-~D*S}~8S&;e70@I<80WlG zQ};X?h1{Q<5cRZ)l&~4H_S9=YhjAft@myf^?{9RL4b$rsdUQeT92@XKQZ>$7A zzVMlq8+vkV1=HJzu_(hk1g;i`M=vW77T5pUmhTcxBwL|$GaHX0N$|~3(|nLkHD1or zp(+L%C(Ue6IPTDqIYlQk-WobHLTUX0=BU+FjamC69ohjYcODx-VQJiu6?@>8X=NEH z33tAD@Ixykm=V_H1PQqOgOgANZZZtuKb`t*WFz{hlzO?jfLdVMpcX9s?C-qg;6q(0 zr!6OC?dYPg<98t2J4SW7BFCz7K$-uV7*+JrZOUxvAZnk%2&q!P7zCjCGH8AR2yDew zv!s(w*S2YSK+Dgse}E{Bn?&RZxiBi0vOYf*7&(|!#6v5zRqR!N8F0Mp0^`C1nUn0vfZtwO3++ynK zpJ0Pd1c)v`V=VS#1{oHs4Y^a4*e*~Bf@Qk-E^#b6hxw7F1+}2GP|hnpbMkGWV`U1Q zMS}yy)=)qT`DsYxt!fGjhUBlbjNPSkHkH}k_-PIw5dF{c+GM5v3)tcP6A7_Z0>}KD zJuBO1vGGq{f-1Y9ZPt?@49#2Edl`u-C3*T0o}fj(A8;qDVlkrZSe-ghmFlr-v^QB- zP6(j#-R#YN)gqHU!5cX_`mn8J90x9qW_Dr5NxWlMMKsy&i2)F5Cm^0U;;(?bv=867 z1s*^I2#lVcgCO$6_}ucM`3RsoJbJ94#Wc8Bum?CnVi6sB{iZIyhN5mNRQx?MtkVhE zw6iZU55-7pR(}*72N30Q775~=HCOu2**`E_8`UA&eYJD-dFPjdM zUPi{5CC96JKbJf1Pyl7)yTGhtWFi01G%r#S+!aPJ?T8Os={2Qy4 z>=IUmLNGXiw zJ$MG5(1ZMaA#Vf+g8eFEJAe(Cyi>LIo`6|HZ9Jua;K9f*RiMB(mAQkpD=-8^`B?u% zfqu)D2ru(1bh~U!8rsTsu|R$kKeP0Oj#kqsMXx-BQZD&U2SHrT%c-b!TDY zQB+xp^^9Zt#HRl$!p{ai@|mGl=mXx1u5lE`)@~-GqbiQ=EY%5l5Rw@oF?(a9EAaBN z2Lx$Q{_&WD*5QKx08g+e7%9RN+Wn5lSHY}puWLXqb$KzMaFCO_Z|0hLb<4Wz6xRq6 z;o(aYP4qH@#uo%kE`S7UNWvUz{}{}VZWA=L5YhaVLra%@^0@!}@dNn>@E~m!V!P{E z=i1rRJmnm|!s6VbS3W)HU1tkw14&i9BQ3sGp2!{lGlsm&bh!4{CWD*B5j|nn22&zb%>Bs?S zh`*U_wF9txL2*zbc2K#l$HJ;Q^hQ!b+lbW~XAC%avg$|{W(a21_(itlhl&!jvFKEk zh;;+Ob;M~U(qEq&z7cX3R)_MENeD<3P9Dh#fVD-KxG-C?>Qs8!u)6Dpo3LVj-h~?$ zxsPuTyro3o?O>=J_$mOW z@jZP2N?mb?6{P2Wh#$>XRgW~#3V06$lfXl$t6bB1n85?^kNpw3sHlKcv##Y~)yqeJ zi?|=RkUH1)rwj!y2}+4jeG=sy3Rdze!e~s+2w$f2+0@8at4CFs10ik$2UuDk9jYzB z;-CdJUoVA{EFk;0NJuY0tlYSr@?QT1Es=+f_guzE2mR>V;M;yf>NU*}(h(Kdx)DpH z%1L_nrqiogr{u{-Yyi+Kr60Y0Caj$X;?JYFB-!h7H;W*z_E%z;{9a8GybJQg$H#g{ zG%X~XdDWuA7hQ0)VDVA5YqPY3Z8AZ`L8cfi1`{SNXZJyTN&|yJJthbA{NA;-RB@l} zsYtT?_6S8a~4)LUPism5{Z*%A!{VlKIX15_Vhz$ zB9Bo(W4CQ)r#TWGT3xW&&W>8P8=&3;SV&yU2nhZn+|Zh_H)s?Fet~{t+?T(c;HU3~ z=?Yku|MD8%9>!T1d%*X&#KcF%AtNZ1WJHiOSNxrJ3hzv`&S1e#kzZtB4$jhsTacO= zOrxGg>h_NNl!l00zMuRSdpvIWTDlNBnXm; z;2lC=2w#ps*;7-FUx%VKt=yOdWP@HbFFJtoqF->}zs}}#?pcT_tfb~5sSfHw04oBx zD_FwutZKP3zb0tNIiRpQr|7wS}14xXqIcGo_5yVzO zn3@G@3N$6YgM+;gXjjj7EWGiw$N#;Amaz#)f!7DlFB8#A>0;|o13js1x|(G%hH}=P zCJFABtH9@<=Fp_Jj08;#6vs%8_unL>_Tyx%8bx$z{F#enUc05OU8>nZ3KwpYm5Z<5 zoV|c^HNduF6>#~!s#?4S>bf)nnthfQ4ypL|d^p&SNj z@V+RxfKL-aKBc{Gh0n#XFwt$?0Q-C!Bi&k=Ai2#yYn8xkV7|eU-l% zjH?k_rWan`WtOk97;>~bAqu4}%{vl0HKjacsK?=`GcYbXCrDtHNz^w#UN35%EhOXl(H!lGoz3RM6@cXtJhdgS0#DKA1HpNCn<1MI{n2C^X84CX ze#NBZgMNV19fSwR)_=w5uxs`x8P=z=Rammx$heCTC*r{2-QOF^x5aR_AbE$NhAD9F zC@Thg!35XHakBB@yc1^_bd&i833PE0`d+Df3?#cGHJHD8?D_YV;$OwtOWm`HlAi?1F#>a zFJ3^RJ8=c7;j^3^ku$8ujTf4akh^-HVDMZ(&|qLLcTkh17}*M9-Ufmpx_vGqYw41y zgzdX_wgNb@!O>p2&Q@&0dOhSymL;`C5XGukXs!MZI*GSigOMkBe^>m3E1Sgj(bUKE z5M3V2w4dx}VsY;vp;}+bu$C_@sVbraqNOWkO}h$_?5f4;S)zWy_gf>gBbjIZUh4KQ zUkxO6`-_Uv0%L4JXm;x{+wi9?Fjrdm+TSDWAM@rYmQ*Y5^ZnzFVboH zSm|BdClrd!B(YKY{$iET!xCNVm8GNK_#4C-Ew3Hy`bR4W55TQlH&X?8N!pk%rq%KT zF(I`%>m?0)kXFM57LAnRTxtcELe2v&)6o(aYFgG&`^3eVcF{B9r z(r$*^O^~v$YNn9t-+saoy;=4%ATIpNLo$gT%beC_VpcRw#z>Vq7E|~kSx>P3Jr2IV>aEVHcbq=Q z9^qQCwu*dAm9b{(zD+EJq#sGQja4iXZC&VC%T5Mj>mQMq=(0_e*L^EqpVX3;Y0q~W z`U-4mb@#jI5Gzf5s~StpY(*)#+%0|mZ1gJ4_ejfSk>X58czCXp7^e?2);x_V#9K4? zeiup~jGYkWsv2030l5EbWJDJY+o010x~Pd=G9h(AbO(P0mSM4ceCi(RroInNABmOB zm7}D{UF47lh+tQ@))MEQwRE6MQ%x{U`hsFNhN~%dN#So4m{Fn;3$QDi8I8mkDRvL! z%E%*sezhF^pKn z*HbC)NZ6lIzXVeD8mH4uSMqj}kkNFESynSEx~6jJxOmY0iqlkQ_gZ|vOoW4F@=#;F zYEr@N?h;WNM4#R}N|Nt-#1*><+o4K^Fv|6q z`PTVj#%?jvI-+^slY0I=i-7;%QUqqz_nPuE{=(aT;nd?%CC+dcK`1I%4STK;x$wdQ9DCq3;@Q^l2egs@SRL79(YES{>Y#xd$#aW_awD0 z_A_LejWs7uiHlEpLNsm(FNJXlyZd?l@bu9raNk{-ywn6+mqBZL>R~q)MHu+AIu4y! zu9IbZGTmfY!EMt-RZ^79*l+31aZ>!w2v|D81?5*9OI?j9hlwSw_deCjx-C`AO{f?S z;!eJnBaPauoH>#|zL{&M2@#rQ*ZdhQT4vv!M;%t}VlwE=?`Lzmd=gbd4h5h>v1^r5 z77CM-0kNAdJD5b`<_>$T%+tN&Qgde7X)dgj@?c59sxRtiQ!I+aS-$ zaOxVBoM{{@($!x{9v1*fe5_%6CA1IaTzDTX!o*qXlj9iZ<%C~h&cCY;6t3<+6)5pW zv4elohQ_;15P5RIsLK~_opDG$6;0R!Mezuc4jzn{qT+exnN52k4QCzY-||tY-`~xh z?&}!^z)be%iQw@uyYO$(^F2PSP}!18Q=OKt8cFGkeUpKT4KfT#e@MPT9A?ij)yL>d zFq+@db^Jx?lC|E_anOE99|m^uRIzf)x~ARfdYgOuUE4pV84i+6)E55$6TV!F; zepw2)wxV~QA}_+?u$gMc83aq4^)IX;5Ke-TenIaUg_p5jwEqJD!ly-UUn z4u#xKZk+y>6fVfo0)JS|z*a|zglu=hCWKJ6=!!V+N)ZD&SZj;gnuNasbZNOE zBP$d{4DkQU$hATb)q2^hvPJNm7;UE;1X(r&Fwt~wPX;VQOQKbI z_Dms;M-BSyZB{guu@#yG=Z#(ZLAG=?SK;t(6o+mW zhqZ}ttVHw_Fa;{I{n4L*u+o5bV@vqvtG~JJ2|rGElLnp)lkp=AZWXESVr-Ulc2r-T z#eL-zbmqn)FDZcdRd$c0b$graiKEp0S8hV?mA&t~gX`NH188mnB8|saCW~`13ryHN z09$j|++4VN8_s}pu!*_{!%L%MLSj%&kD}Vh@VYSA-0N2}wjr9xnko=AqN)+jaXZd_ z@PC`IwbnA_$%Q|!MR7PJ%UVXf69mm20MbmYyVqvLaf^rp<(H>(n6k7A8cEcYk~^=J zP7FZhT8q#;aL?NZXteC|%Ih?~1c=kP-nMrYLo$I&Hrge6Z7e^+s}3^#)+maE6iJFA zeDi~2o`l?bA|y%+mG!~qxQ^>dmfafXV_7Q$u)*Pdictj=1c9*gAsnyTEIda;H2znQ z_MXKul5Q(#77LAV5|sSdaeh0F!*Ii6wNGxUt1fvCfS9Z=Q(_4yC=C|}u?CK7l3Q>q z!0Yfoi(gOh@)S*@z_TO>Gga}L(i*Pa&yHR!M$q$AqZ#_(au&2BqT`@1x%hf89 z;vn=oRkiBy$ZP2D#gaBjX7!hyr@?T)&~$wqH5b`Hhv;>zRihP-m^Se_=vDb%dCo){ zfz@p*qqFC+l%L#mi=>}3@)w#Jzjx=kF1k}I>r)&D0(4kLM(5z}!Zt^A>;MCHgJ`rG zA|*nSU|yvvUDmeQN9mrvVh)8JNu!WvC~&Q+SsRHYzrMUjqd|*rz&X%5UL!W*!y$OA zB>>&*hNu&0{28VK_}Lguakj*RZ8?T=r^?nD-nJBA2Dt}O)JL*17-BK0@!8Y61>Z01 z(m{vgEyWTzBu>w8cPt-5)+Jg?cmGvx4~x<`%!2Qp5)&=qpQ@ib)KEWSc*uaIHH-{; zUqJKAXVa9+K zuu$9O@*nGC6f&yFSf72rsTLX>zvr(sQA)Rgk700b8BV_kgr#I|>jLUw9$_@yj!ThE zsSA8R%_`C#4cw(hxnSe1t7dr2ehxY8SlN*+i!ww;xu&A&&(Rd#^o7`9Or$!D?|;9s zZ#8u3ou+2z)U-tn!KzEg=(`(B4)J;MXGu}E% z*{rw*+Vo_6!3T`o0@GeX!6wlwjxd-}?LgT76>CG{v_@7mlv0?`by)dQZx-ADR0@kO z13u)FiwdchfV8P_7M*t49s);#p>Ye;LN_R%ELLTy&3FOfEKbZ){nloG*rhiwlzfZF z^5g^rSJ7$N-C47CLVpwlY`Qs?i9u>%!`IoB9fE;BS6*@bE|A%;>)K%(;Gb?TtC-2M z^N`IT4(NsxvA;o_hJ&Y7T&)w>tF^m%Le~D;j=AUte^(2oHAENR%QVQymideY718jtOLpvq%I zbHqY26Y(g&lA$@uCcWDDk~Md&OinuM>kSN=30`eOX&=GAE+{$KgYk(RyzeBhkDpMA zi*7epCeKS20@<$@8OMWk66eycFUJsk3K2Wl8&R(W$|;M@P8pp8DxB+og8PKR>Un{R zs*Iqek906a_i!9QIva}39Xc715bC6kd z68TwGB**$^B{D{zx9#b@oBbY;MEBlzhoQJWuH z^waVD&$iYeh`H&cjb<~vtY+&u;z%*|wVb~$g3Bm@($l($75IBqX~e!$#jncy8s!(X z#@ngzP-fXrAgZqyyzv7^bi7{Fo1uAT9_&) zcACMRX^7X?M9TF-Ud~T$IrzutZg4#{G`!||oK5WMckUEK!@cvWx- z!gY=H_aTu3my;INbRW4!SN&=9dG;CWxB>6=fL_^?E+Tzd@8EK zJ$gpwr2A0{Xu_eG`dF%r}ghg;csDhU0|l&3DQrkBUIN z=|4LUR?=Hn_Rr!S(a!|3RYg~KRPMOU+bA<8EemgRgt|y4M*=jYBV&4d3@b6R=_($& zhNbV0_lJ8iwk=Lod=6osii~}1&g0d_-+-_&jk6nxv8m(hFohIkj>FWcEZFE~{>URHy|<#Hmj0F3u8& z{II)BtlrH@PckzC5%4D>oS}@Sh%5eHCq~R@SiWGJ%1cpFM78F@2Hs5*20_!oSL(dg zyaU$AxVZO_7Xt$WFGGrkR=+>g7EIk9jRWF%QlQbU;xZ{=$O*Ihiq{_e?!x4jlp%*6 zXlg9}`=Xvnf>Vqpz>;A49EODU?j-Frs<>K5XY>g$(;}%(>28}bPI$35CS|1_&dTBu zGdb1%m=LpeyvML%^v0zX6S~k2auyzx{Oc&F#XAkBKWWggt=g6ysBf zh;va#Foj7#G&C;mxIK2whgq=K0eqH^yjbt~q(>x6byfbxVvM?WS5DDod#?Ys0+P>p zCS1#LOjh3r*d9?0v|C`Uk-qI}DXU1asJ2#~3uyWR?vuYGsx1xqW787R1S(*D8qcw2fnHs!oVUhmX$3Y5|_S7%U$5RE~HXKKO%w~8lBS8Ja z=$8st9Uaua@ltWICHC6m4MzSZ=7LQeVN*4UN>jpoTB zdm8$L!CFMa1|N_~4jIu$Rg#E79vHQzVW|#p+@Q@9R=9^J5wDB@QL*w)MsrPE`LE1a ziN=jJLcjSzL`c(=Ld+0>VC08Zo8$%bpJaJ?(V91KuIUES@41ed-E%yGCQeC&jAkrd z9V-<}cvyA1g6f3oa&M-Q&rg68oS$hdR=X9EXKJ7GoCzAVX~UyteQ6ljYJ_)?P(mq7 zNqAd;ZIlADTj0=Eq#-YOv;cfHzf&c7!A#_ycaz4rdNCkgm|BhKE_ZnR3K_0~NG z;{ayYw7n9~c-Pn}q9_@#Ne9ys)q&1pqmU(MW*`n7%z}?s8#L3_i0zbCcUI5_dwVGqQL0JXz z(wXZOMaME|VHRw`ZdqG~$C; zjrG0-F+}{<1tThY;H%qEx+Jt2o=YE@wdc_(oOJ$R03Aak?7%5woQ>1Pb+>fAhb_Ud9zY_(U5YZsX z7dYjp5!c14>Gq}2Kb|dd%RqKZ#{ooBb{)>l_#=aRn(T-~(eCSi)Z(_F@%v=B$N%)% znuX^U(eiI1+;?Tn|E?1*GVl#9;H))$|7|CoIAu9CV3&!^=LpORjsQLHrvD?oDDEwv zj^9M9^4M)X(g%J=o|+UJ8aYY_+NNDyJ2>lU`at8MBB_;)LH&53=gc;g%!MuXj06}H z3ek-tdFsLN2f3Vs?D6+ez{W15lwR6#h6$GC`8FW}LXm3wFj6G(^tsu_Krhl42!`DF z*;kaJAAh!>KA<9WoA0Bxs}K#sa|n;0U8Wk}xB8xJ!@Ys`j8+#_ZRSs%$L9w`HJsP* zqwQ)_F@H;K*h2|EL8xJMiTRf)*|bgGBGT)--F_b-k8G{F!S;z8>Pr*5#8Y7}y!t@< zW*6OyrF>-o*2%3VB1|88^3k2b>@n^Q#;q8kO@`c(Xp(JV9QdMjR~P^^_c+HYfKpz;-pzChf~WQcjqr<=15JNv(^!6dztL)?>sg2n6N+l zPgYJPyz5aoj%6?G7?JAd4{Jc6%DMl|LY~z_FV$oRS6kW$3uZ`LP0QYv0c;uj%4(C< zKtooZbRhYDQ2~%7i~f#xsQU`@uadxaJ8jmqaB$|rGpD6e7-|2X_T&$Y#z>^3PwH)5 z=|Tjl8CS_Z99Ojs08>#sQ+uv@{XlZpKm2CD31G^1Bv@(WK1LEtq!wK1_XncxKGt9~ zolBH|`aFQB1a?@&@YN;`X2%#KjsZFKBXo7@?*m*(dww*Owi4Kmp6-Hdv|TcCS9ZI; zIjJ>PP}>ghyDaJMBXqO8>v;sm;)}$ohi15mmxk)Y7_rYJA}27Q$SW>aBHSi&Ze;J^ zn1PQ;?*JVA)O=#^Iay7#_#?W=V56vgW3^2LQ|U9G*c9R^jmyf*PT1KzuGp%AB$WD2?FC-A*w|p=xcWw!RUfEFwSp%X|zw zfTZTV^#G@@1r}-qLOVEN$696QINrcI$VC<`>$FXx=@RI34Zk8!Auv1bmPTHJpFDbszRkkd9+t3fQs?V-D|<=W2#G? zOddV6N&K|6{nPbPCgcNlRny4-njA9K!1ukpw9--g6jGnHYrXBU;(bfGK=<>O!H*sK zs9m4t)s+3$aTJRf${e?jj8iVUkA%>Lv5*swCeH4G$%qs5jZ~;bxS{C>CEiPL=a9HH zdOXx`@01%Kj656&t+}I#WNtabk?+ck%p1Rwr>`|r9p$VtYg)OghgScHwhUQ8TCJ8k zCqOo<(ScAwFDc8ye1sn8`a3AW$~Av_!^J8hM3k$r@Lh|8AAueJ0WF@NOw5nvqyj62 zBPso%%{EvGj<9*h1CEWjs)lZaHpD)FzUUuQekbf7bjv!wp;2k4iD5!WM&!O8iBn5R zW3VPNu*wYB>+^p!(;1!$jR+fjV;RT!0Q5M_8B&MYUD~A^5C!sn=U8nyH)&R675%Ft z?CyE$!}*u^WRM_Kd?+f}A4E|Fj+pLeT*aLvK`|#lI0RdQZG=xi>~;o(wT_a#Hgp4D z+`^Hno{bq_yS~ijXSVB65=~UdmUv6Xi;xX0AX)G%ALf!_;*mS>gLHbQGRhw4`u>>( z96`Av+k7s?W~!;|8cK`Gv|xbtKoAq)ysO40m&Wu=1FX6*og7y6Q5hh!=q_R|{cmY= zzp#>L1lnuP#9{ror3DyX1bjnM6r;1opjNxBlI+^znH7vo$WzddU z4TM8#rlFcWZ-0U61$Yp5DT)04ECzQ{aD{XfXcKilpbL6{LAp2e-YS*#6pDGcr6jF} z{<5&bg?L_6_S;wSGfJW6iM@qE_RwJ~T250rwO?bwW40kAb@V^d)+f`EwFiX`2nq1l zDKeA@i~==knYGVY^GxZTY>lH@WgJZ83B3`+>NCA0+cNJ-IBEBL|K+4fh~_%h>D{+k zEee$lAnLq-4mYJJN7-tu2}ve3%teUGAXDRlrfMST()-7Lz%$TV|fQAcAQsGw3LA zvp+aEkB3se{dP>AdK)AqOJsJsC&VRAp|nS9*&hen3|A{OdD0uHh>!^So3Z&*_0L1zqJ&X zhT78K^rW&7V?&(~cgAldj}!czb^!-NjP97U_{F20Ry+>h{)(uey?J3gFnjiGETR{T zGNgl#F`RtGGLZuAd^N@OQ+ykNKT6T9=5f0%M<|Cop5YCdj4Ph|luI+hbF=D+KRBhG&SL z{oVM0D2FkwCBjt={j(W_46O(hM__+DS8C8@s$&=TqJn1O#dplwR`l}XKyU1#0f3=! zCwa;=;E*&Qd}^BO8)$ZD)B2~58($7E{H-GJ5*!o{F;udNaq2Y`&Rj(~3RpLGXWv!z zB_8*}5uYsP>=AvH^HwJ|<;9XjV^;$z=1#buk4F>nK5lN_*T?sBuDnIHGX25KS51jW z&}rw25z$la(g0uSA?Ic>6`7^I%~6#s5}YdH7-K29tgI=js>nEJ)z%T2@PoZ z=}g0$uy0bj-ktjc*uQjSVjj-5yjG-BZ5(K@sG@LTMHBy}$S1#ZaI1-tYnxtx_P>+# zqpF4BGsz@F2mz!q{}sRf0Q2ntIRP)ku31g_*5R<0UQ;t|Xei0(1P={O3?e8DbvY=d zhvqr3!ZK;aK1D_;*uBilDEJbB2WlIU_i@VmR{DP{wybWffDWb{dAdT;pIOcG=b*~J z>-tozc%67(nV#4D!*R@t;sfS)couLvfwYRCt_e385u&#jyJy zDIfTPha@JUmXlO4T8c8v!iSMQCP+M|jtR#2!(zk^iaCtb=<3%4^C-(DWFC?$U2||| z63i)5XzH5ru+k|ocX8dK(rVkq0?RWaodm0zzi3rEGy6-3(0V8>02BwV&J>^m$7Zrk zTwR-n0BknAe8G5@%ccamCqr;~+(X66>58Jd|9W8yDt|sa*wL0akZbNvJuOUw0Q;!6uk`hd-E2aQeP? zbkA5Ys+OCQ3G{68cT>DXMD#?7K9qCeA?F&?>PrmU=Cx1C~k90pe zW$sO>dpwMvFfTNB2ps;|KKTHy4w^1QK7I&WM2HlexzWQ4*7ldSSx6Np7SCFv4|ijK zl(3xqxa=>pfLU(WsfUpvNvCY(PtqkqdS;vthZ}2Bmkw@J+1F)b?2Jeo#x&5r;O$!~ zl))h+tvPLInT&nFM`ah(xR#?L-H@neT*Tq-H9xsc)j|o{#g|*F$CXA5`lUA-HMlqvvMCq_GHA_s3bA0n04% ztB7qkAcAJ3`fOWa?(qFuZ-2?X@v@qD0e!3BqikWr#&cu*<7k&~lcv`Af z8aGf1Omc0#`I1s0xv{dEm-6VeG)^HfrX#Lte`Sz!i%!9CB<=H$c?%&klNtBpCjM&zeQ#ip4uI#3f-c&2<*qet0os2xmqE@=itiAW zYL2(9GAXwMa(@GoFBIN?mK~u!jn*PsoQSssoF6uPn7~DYO*6l!byNx@X-!$1gBIDj zZ3PHAYtCf`w(Dtn0f2=&U@Vi{qAxE)yNmfDr`8W+G-zl7Xa{4>7w$@fRO(K&Nkn6m za_1o5!(khHK=bG#6QRn7`ZkU2!vtm};_41v4hQ{BP~ep+$UQvW6`kr>7dT2UZ3kDf zR8C)mE}x}>WDtoOfd|sj9RtQ&i^KuOhYQ(U9gBQ;DLQNTbvf)80~uPTd^$9ru}N4~ z+kC0OJ5|4gh*F7u$9tYbFAZ(wZi_-Ag7s$F??ut>(L=8v#R^|x>SL0x&KZN`o2(-0 zO0Q;8#Y&eslwo^$56I9c+ijRL=0=-TuSe9tLD(r^D1@v7ufj~czIt~wi~u%0*tE45 zx_ke){Lrx-Utm3NMCpPIcp^(~6VM#sl67Ne3G+k$U(;)@ff$`fZib981}5C~uEQd< z-xoSIMYRznNaTh8dD;>WN3lp$^z-!<&?isDQZ15Rtpzd#85^+eOkv_9Pymv_%D}fh zzuPO=I8v%(0)&rByt3v`z#ukF5DYd%v(8otF(;34-Pv5ndHP8M&oK;h_|~W7@0DYB zW_Me@I}B&?7r9PMKW{*--(M+RW&@@o%a$$ufvpTn8CCtyUqFLt15)mmkyS_$eL2D2 zqycb(tEEP_x@{K3Y4*E8F>Iyti^;dZFvGfY%_<)ffocM|VRTo6(P14Yd`;3$_*0qq zW-3pxW0fs5H)^X`M8kdIz1g<42b=<*n;s9NFALSLFIHNA$Q(ow%=}3Aw9vNCn9Pyd z0ARTNX5<^!t`HTCCHCtdXR-wllHU($m|W_9*MV1XNo!+){u*T?C4>JP!%Ce*LcwDoh&fxJoXy#Y z9csX$nr%yku=+o>2QYl8-zNpq%C{jU+3Au8(-Xwrz2`$;@FIIe4F68$S&0_g{6LWy zqI3;=*euqoG8d`}imC1@Of_=GHX0Hfw#VyGANXb#Cy=kQdTYGB(DjGU0t%?k5l%ZVsbr znV45VwGwD_2d(EUiMInux6KNkVg3(;h% zP55;^q(KazRyY049eN?t+tK=K#k<~5`!!D)m3E8nnZI~j0NocM!7()%p5uCTV!AQx^_!Hu*u!+IuEm}Wjidf9o|3=#DV1#8FGaFQl2^GPi9-k(M;!#irs zsS=6<*QC5TEJvVl(fS78%Edf{j)&T#5v*#(KvZ5mYo!9-s(2$y{SK)t%O=E=BW4jg z`SwTytO#2G5c0##s(-E5tB#jX!ozH0AJ=s`8EQhr&QIOv0H8{nY*fQ=gxAmxrv6UBMOjODg~ zy++mKaThlD&DRlLN6A85*0H*!^3tZv9L%0Al2np_xtw57Ne72yf`<}=(5`q8O2dy< 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

_#U#&d!<-xlQc$Jc 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 ibpwFmv<{uA!NkdUq$#1fKZ3d_1E#_da_x&R2a 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 FSz4L)JjMV3 literal 327812 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

@yA>$oj%rpI5n(AGM!kM@d&rgT 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

8|zF;SB9~PzaLeTPU?V-l{Jd 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 z Date: Thu, 11 Jun 2026 12:35:42 -0500 Subject: [PATCH 12/71] updated docs --- man/read_waterdata_peaks.Rd | 2 +- man/read_waterdata_use_data.Rd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/man/read_waterdata_peaks.Rd b/man/read_waterdata_peaks.Rd index 79e98b2c2..6cdae7958 100644 --- a/man/read_waterdata_peaks.Rd +++ b/man/read_waterdata_peaks.Rd @@ -41,7 +41,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, time_series_id, monitoring_location_id, parameter_code, peak_id, unit_of_measure, value, last_modified, time, water_year, year, month, day, time_of_day, peak_since. +geometry, time_series_id, monitoring_location_id, parameter_code, peak_id, unit_of_measure, value, last_modified, time, water_year, year, month, day, time_of_day, peak_since, qualifier. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint.} diff --git a/man/read_waterdata_use_data.Rd b/man/read_waterdata_use_data.Rd index 2c4503f08..7513cab2b 100644 --- a/man/read_waterdata_use_data.Rd +++ b/man/read_waterdata_use_data.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/read_waterdata_use.R \name{read_waterdata_use_data} \alias{read_waterdata_use_data} -\title{Get USGS Daily Data} +\title{Get USGS Water Use Data} \usage{ read_waterdata_use_data( model = NA_character_, From 95e4113bdc51e5ae39d0e77400e9f8c152e46f91 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Mon, 15 Jun 2026 08:08:32 -0500 Subject: [PATCH 13/71] rerun docs --- R/read_waterdata_ratings.R | 2 ++ man/read_waterdata_continuous.Rd | 2 +- man/read_waterdata_daily.Rd | 2 +- man/read_waterdata_field_measurements.Rd | 2 +- man/read_waterdata_peaks.Rd | 2 +- tests/testthat/tests_general.R | 2 +- 6 files changed, 7 insertions(+), 5 deletions(-) diff --git a/R/read_waterdata_ratings.R b/R/read_waterdata_ratings.R index 3663592af..3bbc7a9ee 100644 --- a/R/read_waterdata_ratings.R +++ b/R/read_waterdata_ratings.R @@ -147,6 +147,8 @@ read_waterdata_ratings <- function( httr2::req_url_query(limit = limit) |> basic_request() + message("Requesting:\n", request$url) + resp <- httr2::req_perform(request) log_rate_limit(resp) diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index b35db8666..e722a5ede 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -34,7 +34,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, continuous_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint. diff --git a/man/read_waterdata_daily.Rd b/man/read_waterdata_daily.Rd index ef3d7eede..9c0efdd08 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -41,7 +41,7 @@ Multiple statistic_ids can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, daily_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint. diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index b9543526c..95271b34f 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -45,7 +45,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, field_measurement_id, field_measurements_series_id, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified, control_condition, measurement_rated. +geometry, field_measurements_series_id, reading_type, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified, control_condition, measurement_rated, year, month, day, time_of_day. The default (\code{NA}) will return all columns of the data.} \item{field_visit_id}{A universally unique identifier (UUID) for the field visit. Multiple measurements may be made during a single field visit.} diff --git a/man/read_waterdata_peaks.Rd b/man/read_waterdata_peaks.Rd index 79e98b2c2..6cdae7958 100644 --- a/man/read_waterdata_peaks.Rd +++ b/man/read_waterdata_peaks.Rd @@ -41,7 +41,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, time_series_id, monitoring_location_id, parameter_code, peak_id, unit_of_measure, value, last_modified, time, water_year, year, month, day, time_of_day, peak_since. +geometry, time_series_id, monitoring_location_id, parameter_code, peak_id, unit_of_measure, value, last_modified, time, water_year, year, month, day, time_of_day, peak_since, qualifier. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint.} diff --git a/tests/testthat/tests_general.R b/tests/testthat/tests_general.R index 25d272e57..ea8a2e03a 100644 --- a/tests/testthat/tests_general.R +++ b/tests/testthat/tests_general.R @@ -164,7 +164,7 @@ test_that("General NWIS retrievals working", { expect_equal(names(rating_curve), "USGS-01594440.base.rdb") state_rating_list <- read_waterdata_ratings( - datetime = c(Sys.Date() - 1, NA), + datetime = c(Sys.Date() - 1, as.Date(NA)), download_and_parse = FALSE ) From c8c6dbdd8a9da43cce358b8d85ca73f680ca8c49 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 16 Jun 2026 10:06:36 -0500 Subject: [PATCH 14/71] Update R/get_ogc_documentation.R Co-authored-by: Elise Hinman <121896266+ehinman@users.noreply.github.com> --- R/get_ogc_documentation.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/get_ogc_documentation.R b/R/get_ogc_documentation.R index c498bb3be..dc29866a3 100644 --- a/R/get_ogc_documentation.R +++ b/R/get_ogc_documentation.R @@ -59,7 +59,7 @@ get_collection <- function(base = "OGC") { #' available, it will also contain a description. #' #' @param service Character, can be any of the USGS Waterdata API endpoints or collections. -#' @param base Either "OGC" for waterdata, or "NGWMN". +#' @param base Either "OGC" for waterdata, or "NGWMN" for National Groundwater Monitoring Network. #' @return list #' @export #' @examplesIf is_dataRetrieval_user() From 47580263460686738df33f63fab805d2d9c8c51d Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 16 Jun 2026 10:11:59 -0500 Subject: [PATCH 15/71] Add check for required arguments --- R/read_ngwmn_lithology.R | 6 ++++++ R/read_ngwmn_water_level.R | 10 +++++++-- R/read_ngwmn_well_construction.R | 5 +++++ R/setAccess.R | 2 -- man/readNGWMNdata.Rd | 27 ------------------------ man/readNGWMNlevels.Rd | 21 ------------------ man/readNGWMNsites.Rd | 13 ------------ man/read_ngwmn_water_level.Rd | 10 ++++++++- man/read_waterdata_continuous.Rd | 2 +- man/read_waterdata_daily.Rd | 2 +- man/read_waterdata_field_measurements.Rd | 2 +- man/read_waterdata_peaks.Rd | 2 +- 12 files changed, 32 insertions(+), 70 deletions(-) diff --git a/R/read_ngwmn_lithology.R b/R/read_ngwmn_lithology.R index 0cf0cd973..a049a1ace 100644 --- a/R/read_ngwmn_lithology.R +++ b/R/read_ngwmn_lithology.R @@ -38,6 +38,12 @@ read_ngwmn_lithology <- function( attach_request = getOption("dataRetrieval.attach_request") ) { service <- "lithologyObs" + + # Check for mandatory arguments: + if(is.na(monitoring_location_id)){ + stop("monitoring_location_id is a mandatory argument.") + } + rlang::check_dots_empty() args <- mget(names(formals())) diff --git a/R/read_ngwmn_water_level.R b/R/read_ngwmn_water_level.R index 4ae9d34d3..6bdce1bd3 100644 --- a/R/read_ngwmn_water_level.R +++ b/R/read_ngwmn_water_level.R @@ -23,8 +23,8 @@ #' `r get_ogc_params("waterLevelObs", base = "NGWMN")$water_level_above_navd88_ft$description` #' #' @param datetime -#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$sample_time$descriptiond` -#' Multiple time_series_ids can be requested as a character vector. +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$sample_time$description` +#' #' @param properties A vector of requested columns to be returned from the query. #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("waterLevelObs", base = "NGWMN")`. @@ -68,6 +68,12 @@ read_ngwmn_water_level <- function( attach_request = getOption("dataRetrieval.attach_request") ) { service <- "waterLevelObs" + + # Check for mandatory arguments: + if(is.na(monitoring_location_id)){ + stop("monitoring_location_id is a mandatory argument.") + } + rlang::check_dots_empty() args <- mget(names(formals())) diff --git a/R/read_ngwmn_well_construction.R b/R/read_ngwmn_well_construction.R index fedf219b3..e6ce98398 100644 --- a/R/read_ngwmn_well_construction.R +++ b/R/read_ngwmn_well_construction.R @@ -42,6 +42,11 @@ read_ngwmn_well_construction <- function( attach_request = getOption("dataRetrieval.attach_request") ) { service <- "constructionObs" + # Check for mandatory arguments: + if(is.na(monitoring_location_id)){ + stop("monitoring_location_id is a mandatory argument.") + } + rlang::check_dots_empty() args <- mget(names(formals())) diff --git a/R/setAccess.R b/R/setAccess.R index 987093ad4..f0bda6838 100644 --- a/R/setAccess.R +++ b/R/setAccess.R @@ -76,7 +76,5 @@ Please contact comptools@usgs.gov for more information." pkg.env$samplesData <- "https://api.waterdata.usgs.gov/samples-data/summary" pkg.env$status <- "https://www.waterqualitydata.us/wqx3/status/" - pkg.env$NGWMN <- "https://cida.usgs.gov/ngwmn_cache/sos" - # pkg.env$NGWMN <- "https://www.usgs.gov/apps/ngwmn/ngwmn_cache/sos" # nolint end } diff --git a/man/readNGWMNdata.Rd b/man/readNGWMNdata.Rd index c2dd649b1..b56d0dbe6 100644 --- a/man/readNGWMNdata.Rd +++ b/man/readNGWMNdata.Rd @@ -24,30 +24,3 @@ for more information on time zones.} \description{ Only water level data and site locations and names are currently available through the web service. } -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# one site -site <- "USGS.430427089284901" -#oneSite <- readNGWMNdata(siteNumbers = site, service = "observation") - -# multiple sites -sites <- c("USGS.272838082142201", "USGS.404159100494601", "USGS.401216080362703") -# Very slow: -# multiSiteData <- readNGWMNdata(siteNumbers = sites, service = "observation") -# attributes(multiSiteData) - -# non-USGS site -# accepts colon or period between agency and ID -site <- "MBMG:702934" -# data <- readNGWMNdata(siteNumbers = site, service = "featureOfInterest") - -# bounding box -# bboxSites <- readNGWMNdata(service = "featureOfInterest", bbox = c(30, -102, 31, 99)) -# retrieve sites. Set asDateTime to false since one site has an invalid date -# Very slow: -# bboxData <- readNGWMNdata(service = "observation", siteNumbers = bboxSites$site[1:3], -# asDateTime = FALSE) -} -\dontshow{\}) # examplesIf} -} diff --git a/man/readNGWMNlevels.Rd b/man/readNGWMNlevels.Rd index c53e3787d..64637e52e 100644 --- a/man/readNGWMNlevels.Rd +++ b/man/readNGWMNlevels.Rd @@ -24,24 +24,3 @@ for more information on time zones.} \description{ Retrieve groundwater levels from the National Ground Water Monitoring Network. } -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# one site -site <- "USGS.430427089284901" -# oneSite <- readNGWMNlevels(siteNumbers = site) - -# multiple sites -sites <- c("USGS:272838082142201", "USGS:404159100494601", "USGS:401216080362703") -# multiSiteData <- readNGWMNlevels(sites) - -# non-USGS site -site <- "MBMG.103306" -# data <- readNGWMNlevels(siteNumbers = site, asDateTime = FALSE) - -# site with no data returns empty data frame -noDataSite <- "UTGS.401544112060301" -# noDataSite <- readNGWMNlevels(siteNumbers = noDataSite) -} -\dontshow{\}) # examplesIf} -} diff --git a/man/readNGWMNsites.Rd b/man/readNGWMNsites.Rd index 0aa0232bd..4b5c92bef 100644 --- a/man/readNGWMNsites.Rd +++ b/man/readNGWMNsites.Rd @@ -22,16 +22,3 @@ dec_lat_va, dec_lon_va \tab numeric \tab Site latitude and longitude \cr \description{ Retrieve site data from the National Ground Water Monitoring Network. } -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# one site -site <- "USGS.430427089284901" -#oneSite <- readNGWMNsites(siteNumbers = site) - -# non-USGS site -site <- "MBMG.103306" -#siteInfo <- readNGWMNsites(siteNumbers = site) -} -\dontshow{\}) # examplesIf} -} diff --git a/man/read_ngwmn_water_level.Rd b/man/read_ngwmn_water_level.Rd index f0a5a2ba7..949c0751b 100644 --- a/man/read_ngwmn_water_level.Rd +++ b/man/read_ngwmn_water_level.Rd @@ -55,7 +55,15 @@ Available options are: agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, sample_time, orig_unit, orig_value, accuracy_unit, accuracy_value, obs_datum_cd, obs_comment, obs_method, data_provided_by, water_depth_below_land_surface_ft, water_level_above_site_datum_ft, monitoring_location_vertical_datum, water_level_above_navd88_ft. The default (\code{NA}) will return all columns of the data.} -\item{datetime}{Multiple time_series_ids can be requested as a character vector.} +\item{datetime}{The date of an observation. Date and time expressions adhere to RFC 3339. Intervals may be bounded or half-bounded (double-dots at start or end). +Examples: +\itemize{ +\item A date-time: "2018-02-12T23:20:50-00:00" +\item A bounded interval:"2018-02-12T00:00:00+05:00/2018-03-18T12:31:12+05:00" +\item Half-bounded intervals: "2018-02-12T00:00:00-05:00/.." or "../2018-03-18T12:31:12-05:00" +} + +Only features that have a \code{sample_time} that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties.} \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index b35db8666..e722a5ede 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -34,7 +34,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, continuous_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint. diff --git a/man/read_waterdata_daily.Rd b/man/read_waterdata_daily.Rd index ef3d7eede..9c0efdd08 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -41,7 +41,7 @@ Multiple statistic_ids can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, daily_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint. diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index b9543526c..95271b34f 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -45,7 +45,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, field_measurement_id, field_measurements_series_id, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified, control_condition, measurement_rated. +geometry, field_measurements_series_id, reading_type, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified, control_condition, measurement_rated, year, month, day, time_of_day. The default (\code{NA}) will return all columns of the data.} \item{field_visit_id}{A universally unique identifier (UUID) for the field visit. Multiple measurements may be made during a single field visit.} diff --git a/man/read_waterdata_peaks.Rd b/man/read_waterdata_peaks.Rd index ca5240b5e..830040abd 100644 --- a/man/read_waterdata_peaks.Rd +++ b/man/read_waterdata_peaks.Rd @@ -77,7 +77,7 @@ See also Details below for more information.} \item{peak_since}{If not null, this record represents the peak value for the parameter code since the year contained in "peak_since".} -\item{qualifier}{} +\item{qualifier}{This field indicates any qualifiers associated with an observation, for instance if a sensor may have been impacted by ice or if values were estimated.} \item{skipGeometry}{This parameter can be used to skip response geometries for each feature. The returning object will be a data frame with no spatial From 7bbf399d49e8806f28bb942275558483b69640bf Mon Sep 17 00:00:00 2001 From: Matthew Conlon Date: Tue, 16 Jun 2026 16:43:53 -0400 Subject: [PATCH 16/71] add metadata output to read_waterdata_ratings output --- R/read_waterdata_ratings.R | 150 ++++++++++++++++++++++- tests/testthat/tests_userFriendly_fxns.R | 7 +- 2 files changed, 150 insertions(+), 7 deletions(-) diff --git a/R/read_waterdata_ratings.R b/R/read_waterdata_ratings.R index 3663592af..2c4c7269c 100644 --- a/R/read_waterdata_ratings.R +++ b/R/read_waterdata_ratings.R @@ -38,7 +38,13 @@ #' @export #' @inherit read_waterdata_continuous details #' -#' @return List of data frames which contain the requested rating curves. +#' @return List of named lists, one per requested rating file. Each element +#' contains: +#' \describe{ +#' \item{ratings}{Data frame of the rating curve.} +#' \item{metadata}{Data frame of header/value pairs parsed from the comment +#' attribute of the ratings file.} +#' } #' #' @examplesIf is_dataRetrieval_user() #' @@ -49,15 +55,15 @@ #' monitoring_location_id = monitoring_location_id, #' file_type = "exsa") #' -#' head(ratings_exsa[["USGS-01104475.exsa.rdb"]]) -#' comment(ratings_exsa[["USGS-01104475.exsa.rdb"]])[1:15] +#' head(ratings_exsa[["USGS-01104475.exsa.rdb"]]$ratings) +#' ratings_exsa[["USGS-01104475.exsa.rdb"]]$metadata #' #' ratings_corr <- read_waterdata_ratings( #' monitoring_location_id = monitoring_location_id, #' file_type = "corr") #' -#' head(ratings_corr[["USGS-01104460.corr.rdb"]]) -#' comment(ratings_corr[["USGS-01104460.corr.rdb"]])[1:15] +#' head(ratings_corr[["USGS-01104460.corr.rdb"]]$ratings) +#' ratings_corr[["USGS-01104460.corr.rdb"]]$metadata #' #' rating_2 <- read_waterdata_ratings( #' monitoring_location_id = monitoring_location_id, @@ -168,6 +174,7 @@ read_waterdata_ratings <- function( } } +# Download and convert a rating curve feature to a tidy list download_convert <- function(feature, file_path, file_type) { links <- feature$links id <- feature$id @@ -181,8 +188,139 @@ download_convert <- function(feature, file_path, file_type) { message("Requesting: \n", url) resp <- httr2::req_perform(req, path = full_file_path) rating <- importRDB1(full_file_path) - return(rating) + return(list( + ratings = rating, + metadata = parse_ratings_metadata(rating) + )) } return(NULL) } + +# Parse rating comment metadata into a data frame +parse_ratings_metadata <- function(ratings_df) { + raw_comments <- comment(ratings_df) + + if (is.null(raw_comments)) { + return(data.frame( + header = character(), + value = character(), + stringsAsFactors = FALSE + )) + } + + com <- data.frame( + line = raw_comments, + stringsAsFactors = FALSE + ) + + # remove whitespace + com$line <- sub("^#\\s*//?", "", com$line) + com$line <- sub("^//", "", com$line) + com$line <- gsub("\\s+", " ", trimws(com$line)) + + # concatenate warning info + warn_rows <- grepl("^WARNING", com$line) + warn_text <- sub("^WARNING\\s*", "", com$line[warn_rows]) + warn_text <- gsub("\\s+", " ", trimws(warn_text)) + warn_text <- warn_text[warn_text != ""] + + warning_block <- if (length(warn_text) > 0) { + paste(warn_text, collapse = " ") + } else { + "" + } + + non_warn <- com[!warn_rows, , drop = FALSE] + + # group the key-value pairs in the data + kv_pat <- '[A-Za-z0-9_]+\\s*=\\s*"[^"]*"|[A-Za-z0-9_]+\\s*=\\s*[^\\s]+' + kv_match <- regmatches( + non_warn$line, + gregexpr(kv_pat, non_warn$line, perl = TRUE) + ) + has_kv <- sapply(kv_match, length) > 0 + kv_flat <- unlist(kv_match, use.names = FALSE) + + pairs_df <- data.frame( + header = sub("^([A-Za-z0-9_]+).*", "\\1", kv_flat, perl = TRUE), + value = gsub( + '^"|"$', + "", + gsub( + "\\s+", + " ", + trimws( + sub("^[A-Za-z0-9_]+\\s*=\\s*", "", kv_flat, perl = TRUE) + ) + ) + ), + stringsAsFactors = FALSE + ) + + # handle data with colons + colon_pat <- "^[A-Z][A-Z _-]+:" + colon_rows <- grepl(colon_pat, non_warn$line) + colon_lines <- non_warn$line[colon_rows] + + date_df <- data.frame( + header = gsub( + "\\s+", + " ", + trimws( + sub("^([A-Z][A-Z _-]+):.*$", "\\1", colon_lines, perl = TRUE) + ) + ), + value = gsub( + "\\s+", + " ", + trimws( + sub("^[A-Z][A-Z _-]+:\\s*", "", colon_lines, perl = TRUE) + ) + ), + stringsAsFactors = FALSE + ) + + # parse any lines that don't fit other patterns + other_lines <- non_warn$line[!has_kv & !colon_rows] + + other_df <- data.frame( + header = gsub( + "\\s+", + " ", + trimws( + sub("^([A-Z][A-Z _-]+).*$", "\\1", other_lines, perl = TRUE) + ) + ), + value = gsub( + "\\s+", + " ", + trimws( + sub("^[A-Z][A-Z _-]+\\s*", "", other_lines, perl = TRUE) + ) + ), + stringsAsFactors = FALSE + ) + + # combine into one dataframe to be added to list object + final <- rbind( + data.frame( + header = "WARNING", + value = warning_block, + stringsAsFactors = FALSE + ), + pairs_df, + date_df, + other_df + ) + + final$value <- gsub("[\\x00-\\x1F\\x7F]+", " ", final$value, perl = TRUE) + final$value <- gsub("\\s+", " ", trimws(final$value)) + final$header <- gsub("\\s+", " ", trimws(final$header)) + + final <- final[!(final$header == "" & final$value == ""), , drop = FALSE] + final <- unique(final) + rownames(final) <- NULL + + final +} diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index 393c13b4b..c41abfae6 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -123,7 +123,12 @@ test_that("peak, rating curves, surface-water measurements", { monitoring_location_id = siteNumber, file_type = "base" ) - expect_gt(length(comment(data[[1]])), 1) + expect_type(data, "list") + expect_length(data, 1) + + sub <- data[[1]] + expect_type(sub, "list") + expect_setequal(names(sub), c("ratings", "metadata")) # Surface meas: siteNumbers <- c("USGS-01594440", "USGS-040851325") From d818d772b94e6dd287f1529c9d6232a9c2bcdd56 Mon Sep 17 00:00:00 2001 From: Matthew Conlon Date: Thu, 18 Jun 2026 10:44:56 -0400 Subject: [PATCH 17/71] remove stringsAsFactors --- R/read_waterdata_ratings.R | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/R/read_waterdata_ratings.R b/R/read_waterdata_ratings.R index 2c4c7269c..e3b72ba3f 100644 --- a/R/read_waterdata_ratings.R +++ b/R/read_waterdata_ratings.R @@ -204,14 +204,12 @@ parse_ratings_metadata <- function(ratings_df) { if (is.null(raw_comments)) { return(data.frame( header = character(), - value = character(), - stringsAsFactors = FALSE + value = character() )) } com <- data.frame( - line = raw_comments, - stringsAsFactors = FALSE + line = raw_comments ) # remove whitespace @@ -254,8 +252,7 @@ parse_ratings_metadata <- function(ratings_df) { sub("^[A-Za-z0-9_]+\\s*=\\s*", "", kv_flat, perl = TRUE) ) ) - ), - stringsAsFactors = FALSE + ) ) # handle data with colons @@ -277,8 +274,7 @@ parse_ratings_metadata <- function(ratings_df) { trimws( sub("^[A-Z][A-Z _-]+:\\s*", "", colon_lines, perl = TRUE) ) - ), - stringsAsFactors = FALSE + ) ) # parse any lines that don't fit other patterns @@ -298,16 +294,14 @@ parse_ratings_metadata <- function(ratings_df) { trimws( sub("^[A-Z][A-Z _-]+\\s*", "", other_lines, perl = TRUE) ) - ), - stringsAsFactors = FALSE + ) ) # combine into one dataframe to be added to list object final <- rbind( data.frame( header = "WARNING", - value = warning_block, - stringsAsFactors = FALSE + value = warning_block ), pairs_df, date_df, From cacc4ed4aa1c30298aa56d3653563fbdacbc6c8c Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 23 Jun 2026 08:05:11 -0500 Subject: [PATCH 18/71] fix na bug --- R/read_ngwmn.R | 104 +++++++++++++++++++++++++++++++ R/read_ngwmn_lithology.R | 2 +- R/read_ngwmn_providers.R | 2 +- R/read_ngwmn_water_level.R | 2 +- R/read_ngwmn_well_construction.R | 2 +- man/get_ogc_params.Rd | 2 +- man/read_ngwmn_providers.Rd | 2 +- 7 files changed, 110 insertions(+), 6 deletions(-) create mode 100644 R/read_ngwmn.R diff --git a/R/read_ngwmn.R b/R/read_ngwmn.R new file mode 100644 index 000000000..d7bdf41a7 --- /dev/null +++ b/R/read_ngwmn.R @@ -0,0 +1,104 @@ +#' Generalized NGWMN API retrieval function +#' +#' Function that allows complex CQL queries on National Groundwater +#' Monitoring Network API. +#' See +#' for more information. +#' +#' @export +#' @param service character, can be any existing collection. Can be: +#' "providers", "constructionObs", "waterLevelObs", "sites", or "lithologyObs". +#' @param CQL A string in a Common Query Language format. +#' @param convertType logical, defaults to `TRUE`. If `TRUE`, the function +#' will convert the data to dates and qualifier to string vector. +#' @param \dots Additional arguments to send to the request. +#' @inheritParams check_arguments_non_api +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' cql <- '{ +#' "op": "and", +#' "args": [ +#' { +#' "op": "between", +#' "args": [ +#' { "property": "water_level_above_navd88_ft" }, +#' [ "30.00", "80.00" ] +#' ] +#' }, +#' { +#' "op": "in", +#' "args": [ +#' { "property": "monitoring_location_id" }, +#' [ "USGS-272838082142201", "USGS-404159100494601", "USGS-401216080362703" ] +#' ] +#' } +#' ] +#' }' +#' +#' wl_data <- read_ngwmn(service = "waterLevelObs", +#' CQL = cql) +#' +#' +#' } +read_ngwmn <- function( + service, + CQL, + ..., + convertType = getOption("dataRetrieval.convertType"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) { + match.arg(service, c("providers", "constructionObs", + "waterLevelObs", "sites", + "lithologyObs")) + + args <- list(...) + + args[["convertType"]] <- convertType + args[["limit"]] <- limit + args[["attach_request"]] <- attach_request + args[["bbox"]] <- NA + args[["no_paging"]] <- FALSE # drops id if TRUE + args[["chunk_size"]] <- NA # Chunking doesn't make sense. + + if (!"properties" %in% names(args)) { + args[["properties"]] <- NA_character_ + } + + args[["output_id"]] <- "id" + args[["base"]] <- "NGWMN" + args[["service"]] <- service + + data_req <- suppressWarnings(do.call(construct_api_requests, args)) + + data_req <- data_req |> + httr2::req_headers(`Content-Type` = "application/query-cql-json") |> + httr2::req_body_raw(CQL) + + return_list <- walk_pages(data_req) + + return_list <- deal_with_empty(return_list = return_list, + properties = args[["properties"]], + service = service, + skipGeometry = isTRUE(args[["skipGeometry"]]), + convertType = args[["convertType"]], + no_paging = FALSE, + base = "NGWMN" + ) + + return_list <- rejigger_cols( + return_list, + args[["properties"]], + args[["output_id"]] + ) + + if (convertType) { + return_list <- cleanup_cols(return_list, service) + return_list <- order_results(return_list) + return_list <- move_id_col(return_list, args[["output_id"]]) + } + + return(return_list) +} diff --git a/R/read_ngwmn_lithology.R b/R/read_ngwmn_lithology.R index a049a1ace..032352b83 100644 --- a/R/read_ngwmn_lithology.R +++ b/R/read_ngwmn_lithology.R @@ -40,7 +40,7 @@ read_ngwmn_lithology <- function( service <- "lithologyObs" # Check for mandatory arguments: - if(is.na(monitoring_location_id)){ + if(all(is.na(monitoring_location_id))){ stop("monitoring_location_id is a mandatory argument.") } diff --git a/R/read_ngwmn_providers.R b/R/read_ngwmn_providers.R index 08e06f9c4..ae322fdc9 100644 --- a/R/read_ngwmn_providers.R +++ b/R/read_ngwmn_providers.R @@ -21,7 +21,7 @@ #' #' ngwmn_providers <- read_ngwmn_providers(state = "WI") #' -#' ngwml_providers2 <- read_ngwmn_providers(state = c("WI", "MN")) +#' ngwml_providers2 <- read_ngwmn_providers(state = c("WI", "CA", "AZ", "MN")) #' #' org_type <- read_ngwmn_providers(organization_type = "NWIS", state = c("WI", "MN")) #' diff --git a/R/read_ngwmn_water_level.R b/R/read_ngwmn_water_level.R index 6bdce1bd3..307930e9f 100644 --- a/R/read_ngwmn_water_level.R +++ b/R/read_ngwmn_water_level.R @@ -70,7 +70,7 @@ read_ngwmn_water_level <- function( service <- "waterLevelObs" # Check for mandatory arguments: - if(is.na(monitoring_location_id)){ + if(all(is.na(monitoring_location_id))){ stop("monitoring_location_id is a mandatory argument.") } diff --git a/R/read_ngwmn_well_construction.R b/R/read_ngwmn_well_construction.R index e6ce98398..6e11c5868 100644 --- a/R/read_ngwmn_well_construction.R +++ b/R/read_ngwmn_well_construction.R @@ -43,7 +43,7 @@ read_ngwmn_well_construction <- function( ) { service <- "constructionObs" # Check for mandatory arguments: - if(is.na(monitoring_location_id)){ + if(all(is.na(monitoring_location_id))){ stop("monitoring_location_id is a mandatory argument.") } diff --git a/man/get_ogc_params.Rd b/man/get_ogc_params.Rd index d71616671..d7fe7bdc3 100644 --- a/man/get_ogc_params.Rd +++ b/man/get_ogc_params.Rd @@ -9,7 +9,7 @@ get_ogc_params(service, base = "OGC") \arguments{ \item{service}{Character, can be any of the USGS Waterdata API endpoints or collections.} -\item{base}{Either "OGC" for waterdata, or "NGWMN".} +\item{base}{Either "OGC" for waterdata, or "NGWMN" for National Groundwater Monitoring Network.} } \value{ list diff --git a/man/read_ngwmn_providers.Rd b/man/read_ngwmn_providers.Rd index 3ac406a67..82bd71d79 100644 --- a/man/read_ngwmn_providers.Rd +++ b/man/read_ngwmn_providers.Rd @@ -69,7 +69,7 @@ NGWMN contributing providers ngwmn_providers <- read_ngwmn_providers(state = "WI") -ngwml_providers2 <- read_ngwmn_providers(state = c("WI", "MN")) +ngwml_providers2 <- read_ngwmn_providers(state = c("WI", "CA", "AZ", "MN")) org_type <- read_ngwmn_providers(organization_type = "NWIS", state = c("WI", "MN")) From ef7756ac9d62cf4fa30f3c7cc381efa8f32450cc Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 23 Jun 2026 09:11:37 -0500 Subject: [PATCH 19/71] building the docs --- R/read_waterdata_ratings.R | 2 ++ man/read_waterdata_ratings.Rd | 16 +++++++++++----- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/R/read_waterdata_ratings.R b/R/read_waterdata_ratings.R index 6054d6631..cfe024276 100644 --- a/R/read_waterdata_ratings.R +++ b/R/read_waterdata_ratings.R @@ -316,6 +316,8 @@ parse_ratings_metadata <- function(ratings_df) { final <- final[!(final$header == "" & final$value == ""), , drop = FALSE] final <- unique(final) + rownames(final) <- final$header + # final_t <- data.frame(t(final)) rownames(final) <- NULL final diff --git a/man/read_waterdata_ratings.Rd b/man/read_waterdata_ratings.Rd index 4b516e345..c2284e5fd 100644 --- a/man/read_waterdata_ratings.Rd +++ b/man/read_waterdata_ratings.Rd @@ -57,7 +57,13 @@ and return a list of data frames with rating curve data (\code{TRUE}), or to ret just a list of available rating curve files (\code{FALSE}). Default is \code{TRUE}.} } \value{ -List of data frames which contain the requested rating curves. +List of named lists, one per requested rating file. Each element +contains: +\describe{ +\item{ratings}{Data frame of the rating curve.} +\item{metadata}{Data frame of header/value pairs parsed from the comment +attribute of the ratings file.} +} } \description{ Reads current rating table for an active USGS streamgages. More information @@ -89,15 +95,15 @@ ratings_exsa <- read_waterdata_ratings( monitoring_location_id = monitoring_location_id, file_type = "exsa") -head(ratings_exsa[["USGS-01104475.exsa.rdb"]]) -comment(ratings_exsa[["USGS-01104475.exsa.rdb"]])[1:15] +head(ratings_exsa[["USGS-01104475.exsa.rdb"]]$ratings) +ratings_exsa[["USGS-01104475.exsa.rdb"]]$metadata ratings_corr <- read_waterdata_ratings( monitoring_location_id = monitoring_location_id, file_type = "corr") -head(ratings_corr[["USGS-01104460.corr.rdb"]]) -comment(ratings_corr[["USGS-01104460.corr.rdb"]])[1:15] +head(ratings_corr[["USGS-01104460.corr.rdb"]]$ratings) +ratings_corr[["USGS-01104460.corr.rdb"]]$metadata rating_2 <- read_waterdata_ratings( monitoring_location_id = monitoring_location_id, From 7f65eb927e9f075748f36c7aec589a404c02dcfd Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 23 Jun 2026 11:16:22 -0500 Subject: [PATCH 20/71] Adding read_ngwmn function --- NAMESPACE | 1 + R/read_ngwmn.R | 69 ++++++++++++++++++++++--------- man/read_ngwmn.Rd | 101 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 153 insertions(+), 18 deletions(-) create mode 100644 man/read_ngwmn.Rd diff --git a/NAMESPACE b/NAMESPACE index f6c0aa264..9b96ffa72 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -43,6 +43,7 @@ export(readWQPdata) export(readWQPqw) export(readWQPsummary) export(read_USGS_samples) +export(read_ngwmn) export(read_ngwmn_lithology) export(read_ngwmn_providers) export(read_ngwmn_sites) diff --git a/R/read_ngwmn.R b/R/read_ngwmn.R index d7bdf41a7..04550d0d5 100644 --- a/R/read_ngwmn.R +++ b/R/read_ngwmn.R @@ -8,6 +8,8 @@ #' @export #' @param service character, can be any existing collection. Can be: #' "providers", "constructionObs", "waterLevelObs", "sites", or "lithologyObs". +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$sample_time$description` +#' See also Details below for more information. #' @param CQL A string in a Common Query Language format. #' @param convertType logical, defaults to `TRUE`. If `TRUE`, the function #' will convert the data to dates and qualifier to string vector. @@ -19,32 +21,49 @@ #' \donttest{ #' cql <- '{ #' "op": "and", -#' "args": [ -#' { -#' "op": "between", -#' "args": [ +#' "args": +#' "op": "between", +#' "args": [ #' { "property": "water_level_above_navd88_ft" }, -#' [ "30.00", "80.00" ] -#' ] -#' }, -#' { -#' "op": "in", -#' "args": [ -#' { "property": "monitoring_location_id" }, -#' [ "USGS-272838082142201", "USGS-404159100494601", "USGS-401216080362703" ] -#' ] -#' } -#' ] +#' [ "100.00", "120.00" ] +#' ] #' }' #' #' wl_data <- read_ngwmn(service = "waterLevelObs", +#' monitoring_location_id = c("USGS-272838082142201", +#' "USGS-404159100494601", +#' "USGS-401216080362703"), #' CQL = cql) #' +#'cql3 <- '{ +#' "op": "and", +#' "args": [ +#' { +#' "op": "between", +#' "args": [ +#' { "property": "water_level_above_navd88_ft" }, +#' [ "100.00", "200.00" ] +#' ] +#' }, +#' { +#' "op": "in", +#' "args": [ +#' { "property": "monitoring_location_id" }, +#' [ "USGS-272838082142201", "USGS-404159100494601", "USGS-401216080362703" ] +#' ] +#' } +#'] +#'}' +#' +#' +#' wl_data_alt <- read_ngwmn(service = "waterLevelObs", +#' CQL = cql3) #' #' } read_ngwmn <- function( - service, CQL, + service, + monitoring_location_id = NA_character_, ..., convertType = getOption("dataRetrieval.convertType"), limit = getOption("dataRetrieval.limit"), @@ -55,6 +74,20 @@ read_ngwmn <- function( "lithologyObs")) args <- list(...) + args[["monitoring_location_id"]] <- monitoring_location_id + + if(service %in% c("lithologyObs", "waterLevelObs", "constructionObs")){ + # Mandatory monitoring_location_ids + if(all(is.na(monitoring_location_id))){ + args[["monitoring_location_id"]] <- "ALL" + } + + + } else { + if(is.na(monitoring_location_id)){ + args[["monitoring_location_id"]] <- NULL + } + } args[["convertType"]] <- convertType args[["limit"]] <- limit @@ -62,7 +95,7 @@ read_ngwmn <- function( args[["bbox"]] <- NA args[["no_paging"]] <- FALSE # drops id if TRUE args[["chunk_size"]] <- NA # Chunking doesn't make sense. - + if (!"properties" %in% names(args)) { args[["properties"]] <- NA_character_ } @@ -70,7 +103,7 @@ read_ngwmn <- function( args[["output_id"]] <- "id" args[["base"]] <- "NGWMN" args[["service"]] <- service - + args[["..."]] <- NULL data_req <- suppressWarnings(do.call(construct_api_requests, args)) data_req <- data_req |> diff --git a/man/read_ngwmn.Rd b/man/read_ngwmn.Rd new file mode 100644 index 000000000..8c9e8d0cc --- /dev/null +++ b/man/read_ngwmn.Rd @@ -0,0 +1,101 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn.R +\name{read_ngwmn} +\alias{read_ngwmn} +\title{Generalized NGWMN API retrieval function} +\usage{ +read_ngwmn( + CQL, + service, + monitoring_location_id = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) +} +\arguments{ +\item{CQL}{A string in a Common Query Language format.} + +\item{service}{character, can be any existing collection. Can be: +"providers", "constructionObs", "waterLevelObs", "sites", or "lithologyObs". +The date of an observation. Date and time expressions adhere to RFC 3339. Intervals may be bounded or half-bounded (double-dots at start or end). +Examples: +\itemize{ +\item A date-time: "2018-02-12T23:20:50-00:00" +\item A bounded interval:"2018-02-12T00:00:00+05:00/2018-03-18T12:31:12+05:00" +\item Half-bounded intervals: "2018-02-12T00:00:00-05:00/.." or "../2018-03-18T12:31:12-05:00" +} + +Only features that have a \code{sample_time} that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties. + +See also Details below for more information.} + +\item{\dots}{Additional arguments to send to the request.} + +\item{convertType}{logical, defaults to \code{TRUE}. If \code{TRUE}, the function +will convert the data to dates and qualifier to string vector.} + +\item{limit}{numeric, The optional limit parameter is used to control the subset of the +selected features that should be returned in each page. The maximum allowable +limit is 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} +} +\description{ +Function that allows complex CQL queries on National Groundwater +Monitoring Network API. +See \url{https://api.waterdata.usgs.gov/docs/ogcapi/complex-queries/} +for more information. +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +cql <- '{ +"op": "and", +"args": + "op": "between", + "args": [ + { "property": "water_level_above_navd88_ft" }, + [ "100.00", "120.00" ] + ] +}' + +wl_data <- read_ngwmn(service = "waterLevelObs", + monitoring_location_id = c("USGS-272838082142201", + "USGS-404159100494601", + "USGS-401216080362703"), + CQL = cql) + +cql3 <- '{ +"op": "and", +"args": [ + { + "op": "between", + "args": [ + { "property": "water_level_above_navd88_ft" }, + [ "100.00", "200.00" ] + ] + }, + { + "op": "in", + "args": [ + { "property": "monitoring_location_id" }, + [ "USGS-272838082142201", "USGS-404159100494601", "USGS-401216080362703" ] + ] + } +] +}' + + +wl_data_alt <- read_ngwmn(service = "waterLevelObs", + CQL = cql3) + +} +\dontshow{\}) # examplesIf} +} From 6c6a2f73c9a05512f7f88a00261c40ee807bf5c8 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 23 Jun 2026 11:57:33 -0500 Subject: [PATCH 21/71] Add some tests --- R/read_ngwmn.R | 28 +++++++----- man/read_ngwmn.Rd | 14 +++--- tests/testthat/test_ngwmn.R | 56 ++++++++++++++++++++++++ tests/testthat/tests_userFriendly_fxns.R | 13 +++--- 4 files changed, 86 insertions(+), 25 deletions(-) create mode 100644 tests/testthat/test_ngwmn.R diff --git a/R/read_ngwmn.R b/R/read_ngwmn.R index 04550d0d5..f1b9fca6b 100644 --- a/R/read_ngwmn.R +++ b/R/read_ngwmn.R @@ -11,6 +11,7 @@ #' `r get_ogc_params("waterLevelObs", base = "NGWMN")$sample_time$description` #' See also Details below for more information. #' @param CQL A string in a Common Query Language format. +#' @param monitoring_location_id `r get_ogc_params("waterLevelObs", base = "NGWMN")$monitoring_location_id$description` #' @param convertType logical, defaults to `TRUE`. If `TRUE`, the function #' will convert the data to dates and qualifier to string vector. #' @param \dots Additional arguments to send to the request. @@ -20,12 +21,10 @@ #' #' \donttest{ #' cql <- '{ -#' "op": "and", -#' "args": -#' "op": "between", +#' "op": "between", #' "args": [ #' { "property": "water_level_above_navd88_ft" }, -#' [ "100.00", "120.00" ] +#' [ "100.00", "200.00" ] #' ] #' }' #' @@ -61,8 +60,8 @@ #' #' } read_ngwmn <- function( - CQL, service, + CQL = NA_character_, monitoring_location_id = NA_character_, ..., convertType = getOption("dataRetrieval.convertType"), @@ -81,8 +80,6 @@ read_ngwmn <- function( if(all(is.na(monitoring_location_id))){ args[["monitoring_location_id"]] <- "ALL" } - - } else { if(is.na(monitoring_location_id)){ args[["monitoring_location_id"]] <- NULL @@ -103,12 +100,16 @@ read_ngwmn <- function( args[["output_id"]] <- "id" args[["base"]] <- "NGWMN" args[["service"]] <- service - args[["..."]] <- NULL + data_req <- suppressWarnings(do.call(construct_api_requests, args)) - data_req <- data_req |> - httr2::req_headers(`Content-Type` = "application/query-cql-json") |> - httr2::req_body_raw(CQL) + if(isTRUE(!is.na(CQL) | CQL == "")){ + data_req <- data_req |> + httr2::req_headers(`Content-Type` = "application/query-cql-json") |> + httr2::req_body_raw(CQL) + } + + message("Requesting:\n", data_req$url) return_list <- walk_pages(data_req) @@ -133,5 +134,10 @@ read_ngwmn <- function( return_list <- move_id_col(return_list, args[["output_id"]]) } + if (args[["attach_request"]]) { + attr(return_list, "request") <- data_req + } + attr(return_list, "queryTime") <- Sys.time() + return(return_list) } diff --git a/man/read_ngwmn.Rd b/man/read_ngwmn.Rd index 8c9e8d0cc..fd529e9d2 100644 --- a/man/read_ngwmn.Rd +++ b/man/read_ngwmn.Rd @@ -5,8 +5,8 @@ \title{Generalized NGWMN API retrieval function} \usage{ read_ngwmn( - CQL, service, + CQL = NA_character_, monitoring_location_id = NA_character_, ..., convertType = getOption("dataRetrieval.convertType"), @@ -15,8 +15,6 @@ read_ngwmn( ) } \arguments{ -\item{CQL}{A string in a Common Query Language format.} - \item{service}{character, can be any existing collection. Can be: "providers", "constructionObs", "waterLevelObs", "sites", or "lithologyObs". The date of an observation. Date and time expressions adhere to RFC 3339. Intervals may be bounded or half-bounded (double-dots at start or end). @@ -31,6 +29,10 @@ Only features that have a \code{sample_time} that intersects the value of dateti See also Details below for more information.} +\item{CQL}{A string in a Common Query Language format.} + +\item{monitoring_location_id}{This field is required. Combined site identifier of agency code and site number (format of \code{{agency_code}}-\code{{monitoring_location_number}}). A list of values can be passed for this field, seperated by commas.} + \item{\dots}{Additional arguments to send to the request.} \item{convertType}{logical, defaults to \code{TRUE}. If \code{TRUE}, the function @@ -57,12 +59,10 @@ for more information. \donttest{ cql <- '{ -"op": "and", -"args": - "op": "between", + "op": "between", "args": [ { "property": "water_level_above_navd88_ft" }, - [ "100.00", "120.00" ] + [ "100.00", "200.00" ] ] }' diff --git a/tests/testthat/test_ngwmn.R b/tests/testthat/test_ngwmn.R new file mode 100644 index 000000000..32f071d90 --- /dev/null +++ b/tests/testthat/test_ngwmn.R @@ -0,0 +1,56 @@ +context("General NGWMN functions") + +test_that("General NGWMN retrievals working", { + testthat::skip_on_cran() + testthat::skip_on_ci() + + cql <- '{ + "op": "between", + "args": [ + { "property": "water_level_above_navd88_ft" }, + [ "100.00", "200.00" ] + ] +}' + + wl_data <- read_ngwmn(service = "waterLevelObs", + monitoring_location_id = c("USGS-272838082142201", + "USGS-404159100494601", + "USGS-401216080362703"), + CQL = cql) + + # no CQL should work too: + wl_data_full <- read_ngwmn(service = "waterLevelObs", + monitoring_location_id = c("USGS-272838082142201", + "USGS-404159100494601", + "USGS-401216080362703")) + + cql3 <- '{ + "op": "and", + "args": [ + { + "op": "between", + "args": [ + { "property": "water_level_above_navd88_ft" }, + [ "100.00", "200.00" ] + ] + }, + { + "op": "in", + "args": [ + { "property": "monitoring_location_id" }, + [ "USGS-272838082142201", "USGS-404159100494601", "USGS-401216080362703" ] + ] + } + ] + }' + + + wl_data_alt <- read_ngwmn(service = "waterLevelObs", + CQL = cql3) + + expect_equal(nrow(wl_data_alt), nrow(wl_data)) + expect_gt(nrow(wl_data_full), nrow(wl_data)) + + + +}) \ No newline at end of file diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index 393c13b4b..2d05e1141 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -169,13 +169,12 @@ test_that("peak, rating curves, surface-water measurements", { expect_equal(unique(gwl_1$monitoring_location_id), siteID) # No data: - stations <- "06011000" - expect_message(readNWISpeak( - stations, - startDate = "2024-08-01", - endDate = "2024-08-31", - convertType = FALSE - )) + + no_data <- read_waterdata_peaks( + monitoring_location_id = "USGS-06011000", + time = c("2024-08-01", "2024-08-31") + ) + expect_equal(nrow(no_data), 0) }) test_that("read_waterdata_daily", { From 0e79ee8e0f55ddd76b1cb38ca4e789953c0a0fec Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 23 Jun 2026 12:21:53 -0500 Subject: [PATCH 22/71] add more tests --- tests/testthat/test_ngwmn.R | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/tests/testthat/test_ngwmn.R b/tests/testthat/test_ngwmn.R index 32f071d90..1c6256851 100644 --- a/tests/testthat/test_ngwmn.R +++ b/tests/testthat/test_ngwmn.R @@ -1,6 +1,6 @@ -context("General NGWMN functions") +context("NGWMN functions") -test_that("General NGWMN retrievals working", { +test_that("NGWMN retrievals working", { testthat::skip_on_cran() testthat::skip_on_ci() @@ -51,6 +51,26 @@ test_that("General NGWMN retrievals working", { expect_equal(nrow(wl_data_alt), nrow(wl_data)) expect_gt(nrow(wl_data_full), nrow(wl_data)) + sites <- c("ISWS-P428197", + "AKDNR-535143966816631", + "AKDNR-535134236016630") + ngwml_lith_sites <- read_ngwmn_lithology(monitoring_location_id = sites) + expect_all_true(c("ISWS", "AKDNR") %in% unique(ngwml_lith_sites$agency_code)) + + org_type <- read_ngwmn_sites(agency_code = "MN_DNR", + county_name = "Washington County") + expect_true("MN_DNR" == unique(org_type$agency_code)) + + site <- "USGS-272838082142201" + + ngwml_wl_time2 <- read_ngwmn_water_level(monitoring_location_id = site, + datetime = c("2022-01-01", "2024-01-01")) + expect_true(min(as.Date(ngwml_wl_time2$sample_time)) >= as.Date("2022-01-01")) + expect_true(max(as.Date(ngwml_wl_time2$sample_time)) <= as.Date("2024-01-01")) - -}) \ No newline at end of file + sites <- c("USGS-272838082142201", "USGS-404159100494601", + "USGS-401216080362703", "MBMG-702934") + ngwml_well_sites <- read_ngwmn_well_construction(monitoring_location_id = sites) + + expect_all_true(unique(ngwml_well_sites$monitoring_location_id) %in% sites) +}) From 682bbe00290fbb7418a71acaae537447fa248909 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 23 Jun 2026 13:38:38 -0500 Subject: [PATCH 23/71] update wateruse --- NAMESPACE | 2 +- R/read_waterdata_use.R | 130 +++++++++++++----- man/read_waterdata_continuous.Rd | 2 +- man/read_waterdata_daily.Rd | 2 +- man/read_waterdata_field_measurements.Rd | 2 +- ...data_use_data.Rd => read_waterdata_use.Rd} | 70 +++++----- 6 files changed, 136 insertions(+), 72 deletions(-) rename man/{read_waterdata_use_data.Rd => read_waterdata_use.Rd} (54%) diff --git a/NAMESPACE b/NAMESPACE index 948abe69f..882472408 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -61,7 +61,7 @@ export(read_waterdata_samples) export(read_waterdata_stats_daterange) export(read_waterdata_stats_por) export(read_waterdata_ts_meta) -export(read_waterdata_use_data) +export(read_waterdata_use) export(renameNWISColumns) export(setAccess) export(stateCd) diff --git a/R/read_waterdata_use.R b/R/read_waterdata_use.R index fe0d7eb2d..b4d06ee88 100644 --- a/R/read_waterdata_use.R +++ b/R/read_waterdata_use.R @@ -9,6 +9,7 @@ #' @param model See model IDs on the NWDC data catalog page. #' Options are : "wu-public-supply-wd", "wu-thermoelectric", "wu-irrigation-cu", #' "wu-irrigation-wd", and "wu-public-supply-cu" +#' \url{https://water.usgs.gov/nwaa-data/data-catalog} #' @param variable See variable IDs on the NWDC data catalog page. #' @param location Options : huc12, huc10, huc8, huc6, huc4, huc2, countyCd, stateCd #' Locations can be visualized with the Spatial Extent Viewer. Only one location @@ -26,51 +27,104 @@ #' @param limit Defines the number of HUC12s returned per page or file. #' Queries of locations containing more than the below maximum value of HUC12s #' will return multiple pages or files (see location above for details). +#' @param attach_request logical, defaults to `r getOption("dataRetrieval.attach_request")`. +#' If set to `TRUE`, the full request sent to the Water Data API is attached +#' as an attribute to the data set. #' @examplesIf is_dataRetrieval_user() #' #' \donttest{ -#' wu1 <- read_waterdata_use_data(model = "wu-public-supply-wd", -#' variable = c("pswdtot", "pswdgw", "pswdsw"), -#' location = "stateCd:RI", -#' startdate = "2020-01", -#' timeres = "monthly") +#' wu1 <- read_waterdata_use(model = "wu-public-supply-wd", +#' variable = c("pswdtot", "pswdgw", "pswdsw"), +#' location = "stateCd:RI", +#' startdate = "2020-01", +#' timeres = "monthly") #' -#' wu2 <- read_waterdata_use_data(model = "wu-thermoelectric", -#' variable = c('tecufgw', 'tecufsw', 'tecuftot', -#' 'tewdfgw', 'tewdfsw', 'tewdftot', -#' 'tewdssw'), -#' location = "stateCd:RI", -#' startdate = "2020-01", -#' timeres = "monthly") +#' wu2 <- read_waterdata_use(model = "wu-thermoelectric", +#' variable = c('tecufgw', 'tecufsw', 'tecuftot', +#' 'tewdfgw', 'tewdfsw', 'tewdftot', +#' 'tewdssw'), +#' location = "stateCd:RI", +#' startdate = "2020-01", +#' timeres = "monthly") #' -#' wu3 <- read_waterdata_use_data(model = "wu-irrigation-cu", -#' variable = "irrcutot", -#' location = "stateCd:WI", -#' startdate = "2020-01", -#' timeres = "monthly") +#' wu3 <- read_waterdata_use(model = "wu-irrigation-cu", +#' variable = "irrcutot", +#' location = "stateCd:WI", +#' startdate = "2020-01", +#' timeres = "monthly") #' -#' wu4 <- read_waterdata_use_data(model = "wu-irrigation-wd", -#' variable = c("irrwdtot", "irrwdgw", "irrwdsw"), -#' location = "huc2:04", -#' startdate = "2015", -#' timeres = "annualcy") +#' wu4 <- read_waterdata_use(model = "wu-irrigation-wd", +#' variable = c("irrwdtot", "irrwdgw", "irrwdsw"), +#' location = "huc2:04", +#' startdate = "2015", +#' timeres = "annualcy") #' -#' wu5 <- read_waterdata_use_data(model = "wu-public-supply-cu", -#' variable = "pscutot", -#' location = "stateCd:WI", -#' startdate = "2020", -#' timeres = "annualwy") +#' wu5 <- read_waterdata_use(model = "wu-public-supply-cu", +#' variable = "pscutot", +#' location = "stateCd:WI", +#' startdate = "2020", +#' timeres = "annualwy") #' } -read_waterdata_use_data <- function(model = NA_character_, - variable = NA_character_, - location = NA_character_, - timeres = NA_character_, - startdate = NA_character_, - enddate = NA_character_, - intersection = "overlap", - limit = 600){ +read_waterdata_use <- function(model = NA_character_, + variable = NA_character_, + location = NA_character_, + timeres = NA_character_, + startdate = NA_character_, + enddate = NA_character_, + intersection = "overlap", + limit = 500, + attach_request = getOption("dataRetrieval.attach_request")){ + + match.arg(intersection, choices = c("overlap", "envelop"), several.ok = FALSE) + match.arg(model, choices = c("wu-public-supply-wd", + "wu-thermoelectric", + "wu-irrigation-cu", + "wu-irrigation-wd", + "wu-public-supply-cu"), several.ok = FALSE) + + match.arg(timeres, choices = c("monthly", "annualcy", "annualwy")) + + location_prefix <- sapply(strsplit(location, ":"), function(x) x[1]) + choices = c("huc12", "huc10", "huc8", "huc6", "huc4", "huc2", "countyCd", "stateCd") + + + if(!location_prefix %in% choices){ + stop("Invalid location argument.") + } + + if(limit > 500){ + limit <- 500 + message("limit was reset to 500 which is the maximum value for this service.") + } + + if(!is.character(variable)){ + stop("Invalid variable argument.") + } + + # Monthly needs XXXX-XX + if(timeres == "monthly"){ + if(!is.na(startdate) & !grepl("^[0-9]{4}-[0-9]{2}$", startdate, perl = TRUE)){ + stop("Invalid startdate argument.") + } + + if(!is.na(enddate) & !grepl("^[0-9]{4}-[0-9]{2}$", enddate, perl = TRUE)){ + stop("Invalid enddate argument.") + } + } else { # Annual needs XXXX + if(!is.na(startdate) & !grepl("^[0-9]{4}$", startdate, perl = TRUE)){ + stop("Invalid startdate argument.") + } + + if(!is.na(enddate) & !grepl("^[0-9]{4}$", enddate, perl = TRUE)){ + stop("Invalid enddate argument.") + } + } + args <- mget(names(formals())) + + args[["attach_request"]] <- NULL + args <- Filter(Negate(anyNA), args) format <- "csv" @@ -84,6 +138,8 @@ read_waterdata_use_data <- function(model = NA_character_, httr2::req_error(body = error_body) |> httr2::req_timeout(seconds = 180) + baseURL <- add_api_token(baseURL) + baseURL <- explode_query(baseURL, POST = FALSE, args, multi = "comma") message("Requesting:\n", baseURL$url) @@ -98,7 +154,9 @@ read_waterdata_use_data <- function(model = NA_character_, data.table = FALSE, colClasses = list(character = "huc12_id"))) - attr(df, "request") <- baseURL + if(attach_request){ + attr(df, "request") <- baseURL + } attr(df, "queryTime") <- Sys.time() return(df) diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index b35db8666..e722a5ede 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -34,7 +34,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, continuous_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint. diff --git a/man/read_waterdata_daily.Rd b/man/read_waterdata_daily.Rd index ef3d7eede..9c0efdd08 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -41,7 +41,7 @@ Multiple statistic_ids can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, daily_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint. diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index b9543526c..95271b34f 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -45,7 +45,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, field_measurement_id, field_measurements_series_id, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified, control_condition, measurement_rated. +geometry, field_measurements_series_id, reading_type, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified, control_condition, measurement_rated, year, month, day, time_of_day. The default (\code{NA}) will return all columns of the data.} \item{field_visit_id}{A universally unique identifier (UUID) for the field visit. Multiple measurements may be made during a single field visit.} diff --git a/man/read_waterdata_use_data.Rd b/man/read_waterdata_use.Rd similarity index 54% rename from man/read_waterdata_use_data.Rd rename to man/read_waterdata_use.Rd index 7513cab2b..c84c2f589 100644 --- a/man/read_waterdata_use_data.Rd +++ b/man/read_waterdata_use.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/read_waterdata_use.R -\name{read_waterdata_use_data} -\alias{read_waterdata_use_data} +\name{read_waterdata_use} +\alias{read_waterdata_use} \title{Get USGS Water Use Data} \usage{ -read_waterdata_use_data( +read_waterdata_use( model = NA_character_, variable = NA_character_, location = NA_character_, @@ -12,13 +12,15 @@ read_waterdata_use_data( startdate = NA_character_, enddate = NA_character_, intersection = "overlap", - limit = 600 + limit = 500, + attach_request = getOption("dataRetrieval.attach_request") ) } \arguments{ \item{model}{See model IDs on the NWDC data catalog page. Options are : "wu-public-supply-wd", "wu-thermoelectric", "wu-irrigation-cu", -"wu-irrigation-wd", and "wu-public-supply-cu"} +"wu-irrigation-wd", and "wu-public-supply-cu" +\url{https://water.usgs.gov/nwaa-data/data-catalog}} \item{variable}{See variable IDs on the NWDC data catalog page.} @@ -43,6 +45,10 @@ multiple pages or files, depending on their size.} \item{limit}{Defines the number of HUC12s returned per page or file. Queries of locations containing more than the below maximum value of HUC12s will return multiple pages or files (see location above for details).} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} } \description{ USGS's National Water Availability Assessment Data Companion @@ -54,37 +60,37 @@ Assessment. More information at \url{https://water.usgs.gov/nwaa-data}. \dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} \donttest{ -wu1 <- read_waterdata_use_data(model = "wu-public-supply-wd", - variable = c("pswdtot", "pswdgw", "pswdsw"), - location = "stateCd:RI", - startdate = "2020-01", - timeres = "monthly") +wu1 <- read_waterdata_use(model = "wu-public-supply-wd", + variable = c("pswdtot", "pswdgw", "pswdsw"), + location = "stateCd:RI", + startdate = "2020-01", + timeres = "monthly") -wu2 <- read_waterdata_use_data(model = "wu-thermoelectric", - variable = c('tecufgw', 'tecufsw', 'tecuftot', - 'tewdfgw', 'tewdfsw', 'tewdftot', - 'tewdssw'), - location = "stateCd:RI", - startdate = "2020-01", - timeres = "monthly") +wu2 <- read_waterdata_use(model = "wu-thermoelectric", + variable = c('tecufgw', 'tecufsw', 'tecuftot', + 'tewdfgw', 'tewdfsw', 'tewdftot', + 'tewdssw'), + location = "stateCd:RI", + startdate = "2020-01", + timeres = "monthly") -wu3 <- read_waterdata_use_data(model = "wu-irrigation-cu", - variable = "irrcutot", - location = "stateCd:WI", - startdate = "2020-01", - timeres = "monthly") +wu3 <- read_waterdata_use(model = "wu-irrigation-cu", + variable = "irrcutot", + location = "stateCd:WI", + startdate = "2020-01", + timeres = "monthly") -wu4 <- read_waterdata_use_data(model = "wu-irrigation-wd", - variable = c("irrwdtot", "irrwdgw", "irrwdsw"), - location = "huc2:04", - startdate = "2015", - timeres = "annualcy") +wu4 <- read_waterdata_use(model = "wu-irrigation-wd", + variable = c("irrwdtot", "irrwdgw", "irrwdsw"), + location = "huc2:04", + startdate = "2015", + timeres = "annualcy") -wu5 <- read_waterdata_use_data(model = "wu-public-supply-cu", - variable = "pscutot", - location = "stateCd:WI", - startdate = "2020", - timeres = "annualwy") +wu5 <- read_waterdata_use(model = "wu-public-supply-cu", + variable = "pscutot", + location = "stateCd:WI", + startdate = "2020", + timeres = "annualwy") } \dontshow{\}) # examplesIf} } From cc009c1c916ff2f00b931faaf0112c9ba6e9abd1 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 23 Jun 2026 15:01:30 -0500 Subject: [PATCH 24/71] add tests --- R/readNWISunit.R | 2 +- tests/testthat/tests_wateruse.R | 52 +++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 tests/testthat/tests_wateruse.R diff --git a/R/readNWISunit.R b/R/readNWISunit.R index bdee1a123..0478f0b02 100644 --- a/R/readNWISunit.R +++ b/R/readNWISunit.R @@ -461,7 +461,7 @@ readNWISuse <- function(stateCd, convertType = TRUE, transform = FALSE) { - .Deprecated(new = "read_waterdata_use_data in development", + .Deprecated(new = "read_waterdata_use", package = "dataRetrieval", msg = "NWIS servers for water use have been decommission. New functions are being developed.") return(NULL) diff --git a/tests/testthat/tests_wateruse.R b/tests/testthat/tests_wateruse.R new file mode 100644 index 000000000..aa85eb8b6 --- /dev/null +++ b/tests/testthat/tests_wateruse.R @@ -0,0 +1,52 @@ +context("Water Use functions") + +test_that("Water Use retrievals working", { + testthat::skip_on_cran() + testthat::skip_on_ci() + + vars <- c("pswdtot", "pswdgw", "pswdsw") + wu1 <- read_waterdata_use(model = "wu-public-supply-wd", + variable = vars, + location = "stateCd:RI", + startdate = "2020-01", + timeres = "monthly") + + expect_all_true(paste0(vars, "_mgd") %in% names(wu1)) + + expect_error(read_waterdata_use(model = "wu-public-supply-wd", + variable = c("pswdtot", "pswdgw", "pswdsw"), + location = "stateCd:RI", + startdate = "2020", #wrong type of startdate + timeres = "monthly")) + + wu2 <- read_waterdata_use(model = "wu-thermoelectric", + variable = c('tecufgw'), + location = "stateCd:RI", + startdate = "2020-01", + timeres = "monthly") + + expect_all_true(paste0("tecufgw", "_mgd") %in% names(wu2)) + + wu3 <- read_waterdata_use(model = "wu-irrigation-cu", + variable = "irrcutot", + location = "stateCd:WI", + startdate = "2020-01", + timeres = "monthly") + + expect_all_true(paste0("irrcutot", "_mgd") %in% names(wu3)) + + vars <- c("irrwdtot", "irrwdgw", "irrwdsw") + wu4 <- read_waterdata_use(model = "wu-irrigation-wd", + variable = vars, + location = "huc2:04", + startdate = "2015", + timeres = "annualcy") + expect_all_true(paste0(vars, "_mgd") %in% names(wu4)) + + wu5 <- read_waterdata_use(model = "wu-public-supply-cu", + variable = "pscutot", + location = "stateCd:WI", + startdate = "2020", + timeres = "annualwy") + expect_all_true(paste0("pscutot", "_mgd") %in% names(wu5)) +}) From 4c1d0c98672bf7226808d932264754d51d4d49b6 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 23 Jun 2026 15:38:10 -0500 Subject: [PATCH 25/71] rename --- NAMESPACE | 2 +- R/read_waterdata_use.R | 81 +++++++++---------- _pkgdown.yml | 9 ++- ...read_waterdata_use.Rd => read_wateruse.Rd} | 64 +++++++-------- tests/testthat/tests_wateruse.R | 12 +-- 5 files changed, 84 insertions(+), 84 deletions(-) rename man/{read_waterdata_use.Rd => read_wateruse.Rd} (61%) diff --git a/NAMESPACE b/NAMESPACE index 1aba8ab50..ea42a034c 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -67,7 +67,7 @@ export(read_waterdata_samples) export(read_waterdata_stats_daterange) export(read_waterdata_stats_por) export(read_waterdata_ts_meta) -export(read_waterdata_use) +export(read_wateruse) export(renameNWISColumns) export(setAccess) export(stateCd) diff --git a/R/read_waterdata_use.R b/R/read_waterdata_use.R index b4d06ee88..4b43a8a85 100644 --- a/R/read_waterdata_use.R +++ b/R/read_waterdata_use.R @@ -33,47 +33,47 @@ #' @examplesIf is_dataRetrieval_user() #' #' \donttest{ -#' wu1 <- read_waterdata_use(model = "wu-public-supply-wd", -#' variable = c("pswdtot", "pswdgw", "pswdsw"), -#' location = "stateCd:RI", -#' startdate = "2020-01", -#' timeres = "monthly") +#' wu1 <- read_wateruse(model = "wu-public-supply-wd", +#' variable = c("pswdtot", "pswdgw", "pswdsw"), +#' location = "stateCd:RI", +#' startdate = "2020-01", +#' timeres = "monthly") #' -#' wu2 <- read_waterdata_use(model = "wu-thermoelectric", -#' variable = c('tecufgw', 'tecufsw', 'tecuftot', -#' 'tewdfgw', 'tewdfsw', 'tewdftot', -#' 'tewdssw'), -#' location = "stateCd:RI", -#' startdate = "2020-01", -#' timeres = "monthly") -#' -#' wu3 <- read_waterdata_use(model = "wu-irrigation-cu", -#' variable = "irrcutot", -#' location = "stateCd:WI", -#' startdate = "2020-01", -#' timeres = "monthly") +#' wu2 <- read_wateruse(model = "wu-thermoelectric", +#' variable = c('tecufgw', 'tecufsw', 'tecuftot', +#' 'tewdfgw', 'tewdfsw', 'tewdftot', +#' 'tewdssw'), +#' location = "stateCd:RI", +#' startdate = "2020-01", +#' timeres = "monthly") #' -#' wu4 <- read_waterdata_use(model = "wu-irrigation-wd", -#' variable = c("irrwdtot", "irrwdgw", "irrwdsw"), -#' location = "huc2:04", -#' startdate = "2015", -#' timeres = "annualcy") -#' -#' wu5 <- read_waterdata_use(model = "wu-public-supply-cu", -#' variable = "pscutot", -#' location = "stateCd:WI", -#' startdate = "2020", -#' timeres = "annualwy") +#' wu3 <- read_wateruse(model = "wu-irrigation-cu", +#' variable = "irrcutot", +#' location = "stateCd:WI", +#' startdate = "2020-01", +#' timeres = "monthly") +#' +#' wu4 <- read_wateruse(model = "wu-irrigation-wd", +#' variable = c("irrwdtot", "irrwdgw", "irrwdsw"), +#' location = "huc2:04", +#' startdate = "2015", +#' timeres = "annualcy") +#' +#' wu5 <- read_wateruse(model = "wu-public-supply-cu", +#' variable = "pscutot", +#' location = "stateCd:WI", +#' startdate = "2020", +#' timeres = "annualwy") #' } -read_waterdata_use <- function(model = NA_character_, - variable = NA_character_, - location = NA_character_, - timeres = NA_character_, - startdate = NA_character_, - enddate = NA_character_, - intersection = "overlap", - limit = 500, - attach_request = getOption("dataRetrieval.attach_request")){ +read_wateruse <- function(model = NA_character_, + variable = NA_character_, + location = NA_character_, + timeres = NA_character_, + startdate = NA_character_, + enddate = NA_character_, + intersection = "overlap", + limit = 500, + attach_request = getOption("dataRetrieval.attach_request")){ match.arg(intersection, choices = c("overlap", "envelop"), several.ok = FALSE) match.arg(model, choices = c("wu-public-supply-wd", @@ -120,7 +120,6 @@ read_waterdata_use <- function(model = NA_character_, } } - args <- mget(names(formals())) args[["attach_request"]] <- NULL @@ -137,9 +136,7 @@ read_waterdata_use <- function(model = NA_character_, httr2::req_url_query(format = format ) |> httr2::req_error(body = error_body) |> httr2::req_timeout(seconds = 180) - - baseURL <- add_api_token(baseURL) - + baseURL <- explode_query(baseURL, POST = FALSE, args, multi = "comma") message("Requesting:\n", baseURL$url) diff --git a/_pkgdown.yml b/_pkgdown.yml index c9ff3b353..38223daef 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -88,7 +88,6 @@ reference: - read_waterdata_combined_meta - read_waterdata_ratings - read_waterdata_peaks - - read_waterdata_use - summarize_waterdata_samples - check_waterdata_sample_params - title: National Water Information System (NWIS) @@ -119,7 +118,7 @@ reference: - title: National Ground-Water Monitoring Network desc: Functions to retrieve NGWMN data. contents: - - read_ngwmn_water_levels + - read_ngwmn_water_level - read_ngwmn_sites - read_ngwmn_providers - read_ngwmn_well_construction @@ -130,6 +129,10 @@ reference: contents: - findNLDI - get_nldi_sources + - title: National Water Availability Assessment Data + desc: Functions to get Water Use data + contents: + - read_wateruse - title: Import data desc: Functions to import different data formats contents: @@ -164,4 +167,4 @@ reference: - getWebServiceData - is_dataRetrieval_user - checkWQPdates - - get_ogc_params \ No newline at end of file + - get_ogc_params diff --git a/man/read_waterdata_use.Rd b/man/read_wateruse.Rd similarity index 61% rename from man/read_waterdata_use.Rd rename to man/read_wateruse.Rd index c84c2f589..f475e0e5e 100644 --- a/man/read_waterdata_use.Rd +++ b/man/read_wateruse.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/read_waterdata_use.R -\name{read_waterdata_use} -\alias{read_waterdata_use} +\name{read_wateruse} +\alias{read_wateruse} \title{Get USGS Water Use Data} \usage{ -read_waterdata_use( +read_wateruse( model = NA_character_, variable = NA_character_, location = NA_character_, @@ -60,37 +60,37 @@ Assessment. More information at \url{https://water.usgs.gov/nwaa-data}. \dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} \donttest{ -wu1 <- read_waterdata_use(model = "wu-public-supply-wd", - variable = c("pswdtot", "pswdgw", "pswdsw"), - location = "stateCd:RI", - startdate = "2020-01", - timeres = "monthly") +wu1 <- read_wateruse(model = "wu-public-supply-wd", + variable = c("pswdtot", "pswdgw", "pswdsw"), + location = "stateCd:RI", + startdate = "2020-01", + timeres = "monthly") -wu2 <- read_waterdata_use(model = "wu-thermoelectric", - variable = c('tecufgw', 'tecufsw', 'tecuftot', - 'tewdfgw', 'tewdfsw', 'tewdftot', - 'tewdssw'), - location = "stateCd:RI", - startdate = "2020-01", - timeres = "monthly") - -wu3 <- read_waterdata_use(model = "wu-irrigation-cu", - variable = "irrcutot", - location = "stateCd:WI", - startdate = "2020-01", - timeres = "monthly") +wu2 <- read_wateruse(model = "wu-thermoelectric", + variable = c('tecufgw', 'tecufsw', 'tecuftot', + 'tewdfgw', 'tewdfsw', 'tewdftot', + 'tewdssw'), + location = "stateCd:RI", + startdate = "2020-01", + timeres = "monthly") -wu4 <- read_waterdata_use(model = "wu-irrigation-wd", - variable = c("irrwdtot", "irrwdgw", "irrwdsw"), - location = "huc2:04", - startdate = "2015", - timeres = "annualcy") - -wu5 <- read_waterdata_use(model = "wu-public-supply-cu", - variable = "pscutot", - location = "stateCd:WI", - startdate = "2020", - timeres = "annualwy") +wu3 <- read_wateruse(model = "wu-irrigation-cu", + variable = "irrcutot", + location = "stateCd:WI", + startdate = "2020-01", + timeres = "monthly") + +wu4 <- read_wateruse(model = "wu-irrigation-wd", + variable = c("irrwdtot", "irrwdgw", "irrwdsw"), + location = "huc2:04", + startdate = "2015", + timeres = "annualcy") + +wu5 <- read_wateruse(model = "wu-public-supply-cu", + variable = "pscutot", + location = "stateCd:WI", + startdate = "2020", + timeres = "annualwy") } \dontshow{\}) # examplesIf} } diff --git a/tests/testthat/tests_wateruse.R b/tests/testthat/tests_wateruse.R index aa85eb8b6..a908de63f 100644 --- a/tests/testthat/tests_wateruse.R +++ b/tests/testthat/tests_wateruse.R @@ -5,7 +5,7 @@ test_that("Water Use retrievals working", { testthat::skip_on_ci() vars <- c("pswdtot", "pswdgw", "pswdsw") - wu1 <- read_waterdata_use(model = "wu-public-supply-wd", + wu1 <- read_wateruse(model = "wu-public-supply-wd", variable = vars, location = "stateCd:RI", startdate = "2020-01", @@ -13,13 +13,13 @@ test_that("Water Use retrievals working", { expect_all_true(paste0(vars, "_mgd") %in% names(wu1)) - expect_error(read_waterdata_use(model = "wu-public-supply-wd", + expect_error(read_wateruse(model = "wu-public-supply-wd", variable = c("pswdtot", "pswdgw", "pswdsw"), location = "stateCd:RI", startdate = "2020", #wrong type of startdate timeres = "monthly")) - wu2 <- read_waterdata_use(model = "wu-thermoelectric", + wu2 <- read_wateruse(model = "wu-thermoelectric", variable = c('tecufgw'), location = "stateCd:RI", startdate = "2020-01", @@ -27,7 +27,7 @@ test_that("Water Use retrievals working", { expect_all_true(paste0("tecufgw", "_mgd") %in% names(wu2)) - wu3 <- read_waterdata_use(model = "wu-irrigation-cu", + wu3 <- read_wateruse(model = "wu-irrigation-cu", variable = "irrcutot", location = "stateCd:WI", startdate = "2020-01", @@ -36,14 +36,14 @@ test_that("Water Use retrievals working", { expect_all_true(paste0("irrcutot", "_mgd") %in% names(wu3)) vars <- c("irrwdtot", "irrwdgw", "irrwdsw") - wu4 <- read_waterdata_use(model = "wu-irrigation-wd", + wu4 <- read_wateruse(model = "wu-irrigation-wd", variable = vars, location = "huc2:04", startdate = "2015", timeres = "annualcy") expect_all_true(paste0(vars, "_mgd") %in% names(wu4)) - wu5 <- read_waterdata_use(model = "wu-public-supply-cu", + wu5 <- read_wateruse(model = "wu-public-supply-cu", variable = "pscutot", location = "stateCd:WI", startdate = "2020", From f1d8510f88dfd15ce87eedbd6b42303b0eccb576 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 23 Jun 2026 15:38:49 -0500 Subject: [PATCH 26/71] rename file --- R/{read_waterdata_use.R => read_wateruse.R} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename R/{read_waterdata_use.R => read_wateruse.R} (100%) diff --git a/R/read_waterdata_use.R b/R/read_wateruse.R similarity index 100% rename from R/read_waterdata_use.R rename to R/read_wateruse.R From cb6e1bd7fd93f554cc700786d53403210d9d7bfb Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 23 Jun 2026 15:44:16 -0500 Subject: [PATCH 27/71] remove functions that don't work --- R/readNGWMNdata.R | 226 ---------------------------------------------- _pkgdown.yml | 3 +- 2 files changed, 2 insertions(+), 227 deletions(-) delete mode 100644 R/readNGWMNdata.R diff --git a/R/readNGWMNdata.R b/R/readNGWMNdata.R deleted file mode 100644 index f9c9a621a..000000000 --- a/R/readNGWMNdata.R +++ /dev/null @@ -1,226 +0,0 @@ -#' Import data from the National Groundwater Monitoring Network. -#' -#' Only water level data and site locations and names are currently available through the web service. -#' @param service char Service for the request - "observation" and "featureOfInterest" are implemented. -#' @param \dots Other parameters to supply, namely `siteNumbers` or `bbox` -#' @param asDateTime logical if `TRUE`, will convert times to POSIXct format. Currently defaults to -#' `FALSE` since time zone information is not included. -#' @param tz character to set timezone attribute of dateTime. Default is "UTC", and converts the -#' date times to UTC, properly accounting for daylight savings times based on the data's provided time zone offset. -#' Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", -#' "America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", -#' "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also `OlsonNames()` -#' for more information on time zones. -#' @export -readNGWMNdata <- function(service, ..., asDateTime = TRUE, tz = "UTC") { - .Deprecated( - new = "read_ngwmn_water_level", - package = "dataRetrieval", - msg = "Updated NGWMN APIs will use read_ngwmn set of functions." - ) - - dots <- convertLists(...) - - match.arg(service, c("observation", "featureOfInterest")) - - if (service == "observation") { - # these attributes are pulled out and saved when doing binds to be reattached - attrs <- c( - "url", - "gml:identifier", - "generationDate", - "responsibleParty", - "contact" - ) - featureID <- stats::na.omit(gsub(":", ".", dots[["siteNumbers"]])) - - obs_list <- vector("list", length(featureID)) - attr_list <- vector("list", length(featureID)) - for (idx in seq_along(featureID)) { - obsFID <- retrieveObservation( - featureID = featureID[idx], - asDateTime, - attrs, - tz = tz - ) - attr_list[[idx]] <- saveAttrs(attrs, obsFID) - obs_list[[idx]] <- removeAttrs(attrs, obsFID) - } - allObs <- Reduce(r_bind_dr, obs_list, init = data.frame()) - allAttrs <- Reduce(r_bind_dr, attr_list, init = data.frame()) - - allSites <- tryCatch( - { - retrieveFeatureOfInterest(featureID = featureID) - }, - error = function(cond) { - return(NULL) - } - ) - - if (!is.null(allSites)) { - attr(allObs, "siteInfo") <- allSites - } - - attr(allObs, "other") <- allAttrs - returnData <- allObs - } else if (service == "featureOfInterest") { - if ("siteNumbers" %in% names(dots)) { - featureID <- stats::na.omit(gsub(":", ".", dots[["siteNumbers"]])) - allSites <- tryCatch({ - retrieveFeatureOfInterest(featureID = featureID) - }) - } - - if ("bbox" %in% names(dots)) { - allSites <- tryCatch({ - retrieveFeatureOfInterest(bbox = dots[["bbox"]]) - }) - } - returnData <- allSites - } - - return(returnData) -} - -#' Retrieve groundwater levels from the National Ground Water Monitoring Network. -#' -#' @param siteNumbers character Vector of feature IDs formatted with agency code and site number -#' separated by a period or semicolon, e.g. `USGS.404159100494601`. -#' @param asDateTime logical Should dates and times be converted to date/time objects, -#' or returned as character? Defaults to `TRUE`. Must be set to `FALSE` if a site -#' contains non-standard dates. -#' @param tz character to set timezone attribute of dateTime. Default is "UTC", and converts the -#' date times to UTC, properly accounting for daylight savings times based on the data's provided time zone offset. -#' Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", -#' "America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", -#' "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also `OlsonNames()` -#' for more information on time zones. -#' @export -readNGWMNlevels <- function(siteNumbers, asDateTime = TRUE, tz = "UTC") { - data <- readNGWMNdata( - siteNumbers = siteNumbers, - service = "observation", - asDateTime = asDateTime, - tz = tz - ) - return(data) -} - -#' Retrieve site data from the National Ground Water Monitoring Network. -#' -#' @param siteNumbers character Vector of feature IDs formatted with agency code and site number -#' separated by a period or semicolon, e.g. `USGS.404159100494601`. -#' -#' @export -#' @return A data frame the following columns: -#' #' \tabular{lll}{ -#' Name \tab Type \tab Description \cr -#' site \tab char \tab Site FID \cr -#' description \tab char \tab Site description \cr -#' dec_lat_va, dec_lon_va \tab numeric \tab Site latitude and longitude \cr -#' } - -readNGWMNsites <- function(siteNumbers) { - sites <- readNGWMNdata( - siteNumbers = siteNumbers, - service = "featureOfInterest" - ) - return(sites) -} - -retrieveObservation <- function(featureID, asDateTime, attrs, tz) { - baseURL <- httr2::request(pkg.env[["NGWMN"]]) - baseURL <- httr2::req_url_query( - baseURL, - request = "GetObservation", - service = "SOS", - version = "2.0.0", - observedProperty = "urn:ogc:def:property:OGC:GroundWaterLevel", - responseFormat = "text/xml", - featureOfInterest = paste("VW_GWDP_GEOSERVER", featureID, sep = ".") - ) - - returnData <- importNGWMN(baseURL, asDateTime = asDateTime, tz = tz) - if (nrow(returnData) == 0) { - # need to add NA attributes, so they aren't messed up when stored as DFs - attr(returnData, "gml:identifier") <- NA - attr(returnData, "generationDate") <- NA - } - - # mutate removes the attributes, need to save and append - attribs <- saveAttrs(attrs, returnData) - if (nrow(returnData) > 0) { - # tack on site number - siteNum <- rep(sub(".*\\.", "", featureID), nrow(returnData)) - returnData$site <- siteNum - numCol <- ncol(returnData) - returnData <- returnData[, c(numCol, 1:(numCol - 1))] # move siteNum to the left - } - attributes(returnData) <- c(attributes(returnData), as.list(attribs)) - - return(returnData) -} - -# retrieve feature of interest -# could allow pass through srsName - needs to be worked in higher-up in dots -retrieveFeatureOfInterest <- function( - ..., - asDateTime, - srsName = "urn:ogc:def:crs:EPSG::4269" -) { - values <- convertLists(...) - - baseURL <- httr2::request(pkg.env[["NGWMN"]]) - baseURL <- httr2::req_url_query( - baseURL, - request = "GetFeatureOfInterest", - service = "SOS", - version = "2.0.0", - responseFormat = "text/xml" - ) - - if ("featureID" %in% names(values)) { - features <- paste("VW_GWDP_GEOSERVER", values[["featureID"]], sep = ".") - - baseURL <- httr2::req_url_query( - baseURL, - featureOfInterest = features, - .multi = "comma" - ) - } else if ("bbox" %in% names(values)) { - baseURL <- httr2::req_url_query( - baseURL, - bbox = paste(values[["bbox"]], collapse = ","), - srsName = srsName - ) - } else { - stop("Geographical filter not specified. Please use siteNumbers or bbox") - } - - siteDF <- importNGWMN(baseURL, asDateTime, tz = "") - attr(siteDF, "url") <- baseURL$url - attr(siteDF, "queryTime") <- Sys.time() - return(siteDF) -} - - -# save specified attributes from a data frame -saveAttrs <- function(attrs, df) { - attribs <- sapply(attrs, function(x) attr(df, x)) - if (is.vector(attribs)) { - toReturn <- as.data.frame(t(attribs), stringsAsFactors = FALSE) - } else { - # don't need to transpose - toReturn <- as.data.frame(attribs, stringsAsFactors = FALSE) - } - return(toReturn) -} - -# strip specified attributes from a data frame -removeAttrs <- function(attrs, df) { - for (a in attrs) { - attr(df, a) <- NULL - } - return(df) -} diff --git a/_pkgdown.yml b/_pkgdown.yml index 8af889bdc..cde33ded4 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -85,7 +85,6 @@ reference: - read_waterdata - summarize_waterdata_samples - check_waterdata_sample_params - - get_ogc_params - read_waterdata_channel - read_waterdata_field_meta - read_waterdata_combined_meta @@ -124,6 +123,7 @@ reference: - read_ngwmn_providers - read_ngwmn_well_construction - read_ngwmn_lithology + - read_ngwmn - title: Network Linked Data Index desc: Functions to interface with the NLDI. contents: @@ -163,3 +163,4 @@ reference: - getWebServiceData - is_dataRetrieval_user - checkWQPdates + - get_ogc_params From ddaca79ee2c70380a10c8d315d6caaa780e069a8 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 23 Jun 2026 15:50:03 -0500 Subject: [PATCH 28/71] Cleanup pkgdown --- NAMESPACE | 3 --- _pkgdown.yml | 2 +- man/readNGWMNdata.Rd | 26 -------------------------- man/readNGWMNlevels.Rd | 26 -------------------------- man/readNGWMNsites.Rd | 24 ------------------------ 5 files changed, 1 insertion(+), 80 deletions(-) delete mode 100644 man/readNGWMNdata.Rd delete mode 100644 man/readNGWMNlevels.Rd delete mode 100644 man/readNGWMNsites.Rd diff --git a/NAMESPACE b/NAMESPACE index 9b96ffa72..45be56a32 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -27,9 +27,6 @@ export(pCodeToName) export(parameterCdFile) export(parse_WQP) export(pcode_to_name) -export(readNGWMNdata) -export(readNGWMNlevels) -export(readNGWMNsites) export(readNWISdata) export(readNWISdv) export(readNWISpCode) diff --git a/_pkgdown.yml b/_pkgdown.yml index cde33ded4..2adf3191a 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -118,7 +118,7 @@ reference: - title: National Ground-Water Monitoring Network desc: Functions to retrieve NGWMN data. contents: - - read_ngwmn_water_levels + - read_ngwmn_water_level - read_ngwmn_sites - read_ngwmn_providers - read_ngwmn_well_construction diff --git a/man/readNGWMNdata.Rd b/man/readNGWMNdata.Rd deleted file mode 100644 index b56d0dbe6..000000000 --- a/man/readNGWMNdata.Rd +++ /dev/null @@ -1,26 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/readNGWMNdata.R -\name{readNGWMNdata} -\alias{readNGWMNdata} -\title{Import data from the National Groundwater Monitoring Network.} -\usage{ -readNGWMNdata(service, ..., asDateTime = TRUE, tz = "UTC") -} -\arguments{ -\item{service}{char Service for the request - "observation" and "featureOfInterest" are implemented.} - -\item{\dots}{Other parameters to supply, namely \code{siteNumbers} or \code{bbox}} - -\item{asDateTime}{logical if \code{TRUE}, will convert times to POSIXct format. Currently defaults to -\code{FALSE} since time zone information is not included.} - -\item{tz}{character to set timezone attribute of dateTime. Default is "UTC", and converts the -date times to UTC, properly accounting for daylight savings times based on the data's provided time zone offset. -Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", -"America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", -"America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also \code{OlsonNames()} -for more information on time zones.} -} -\description{ -Only water level data and site locations and names are currently available through the web service. -} diff --git a/man/readNGWMNlevels.Rd b/man/readNGWMNlevels.Rd deleted file mode 100644 index 64637e52e..000000000 --- a/man/readNGWMNlevels.Rd +++ /dev/null @@ -1,26 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/readNGWMNdata.R -\name{readNGWMNlevels} -\alias{readNGWMNlevels} -\title{Retrieve groundwater levels from the National Ground Water Monitoring Network.} -\usage{ -readNGWMNlevels(siteNumbers, asDateTime = TRUE, tz = "UTC") -} -\arguments{ -\item{siteNumbers}{character Vector of feature IDs formatted with agency code and site number -separated by a period or semicolon, e.g. \code{USGS.404159100494601}.} - -\item{asDateTime}{logical Should dates and times be converted to date/time objects, -or returned as character? Defaults to \code{TRUE}. Must be set to \code{FALSE} if a site -contains non-standard dates.} - -\item{tz}{character to set timezone attribute of dateTime. Default is "UTC", and converts the -date times to UTC, properly accounting for daylight savings times based on the data's provided time zone offset. -Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", -"America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", -"America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also \code{OlsonNames()} -for more information on time zones.} -} -\description{ -Retrieve groundwater levels from the National Ground Water Monitoring Network. -} diff --git a/man/readNGWMNsites.Rd b/man/readNGWMNsites.Rd deleted file mode 100644 index 4b5c92bef..000000000 --- a/man/readNGWMNsites.Rd +++ /dev/null @@ -1,24 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/readNGWMNdata.R -\name{readNGWMNsites} -\alias{readNGWMNsites} -\title{Retrieve site data from the National Ground Water Monitoring Network.} -\usage{ -readNGWMNsites(siteNumbers) -} -\arguments{ -\item{siteNumbers}{character Vector of feature IDs formatted with agency code and site number -separated by a period or semicolon, e.g. \code{USGS.404159100494601}.} -} -\value{ -A data frame the following columns: -#' \tabular{lll}{ -Name \tab Type \tab Description \cr -site \tab char \tab Site FID \cr -description \tab char \tab Site description \cr -dec_lat_va, dec_lon_va \tab numeric \tab Site latitude and longitude \cr -} -} -\description{ -Retrieve site data from the National Ground Water Monitoring Network. -} From c7fe17916b7431511cceabe030b67b1310776d59 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 24 Jun 2026 11:47:24 -0500 Subject: [PATCH 29/71] Allow geometry in continuous --- DESCRIPTION | 5 ++++- R/read_waterdata_continuous.R | 4 +++- man/read_waterdata_combined_meta.Rd | 4 ++-- man/read_waterdata_continuous.Rd | 14 ++++++++++++++ man/read_waterdata_field_meta.Rd | 2 +- man/read_waterdata_latest_continuous.Rd | 2 +- man/read_waterdata_latest_daily.Rd | 2 +- man/read_waterdata_monitoring_location.Rd | 2 +- man/read_waterdata_peaks.Rd | 2 +- man/read_waterdata_ts_meta.Rd | 4 ++-- 10 files changed, 30 insertions(+), 11 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 101d0fc5c..4df9e8d4c 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -34,7 +34,10 @@ Authors@R: c( comment=c(ORCID = "0000-0001-5396-1583")), person("Michael", "Mahoney", role="ctb", email = "mjmahoney@usgs.gov", - comment=c(ORCID = "0000-0003-2402-304X")) + comment=c(ORCID = "0000-0003-2402-304X")), + person("Matthew", "Conlon", role="ctb", + email = "mconlon@usgs.gov", + comment=c(ORCID = "0000-0001-8266-9610")) ) Description: Collection of functions to help retrieve U.S. Geological Survey and U.S. Environmental Protection Agency water quality and diff --git a/R/read_waterdata_continuous.R b/R/read_waterdata_continuous.R index d9291e560..0f260ff7b 100644 --- a/R/read_waterdata_continuous.R +++ b/R/read_waterdata_continuous.R @@ -35,6 +35,7 @@ #' @param \dots Not used. Included to help differentiate official Water Data API arguments #' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_non_api +#' @inheritParams check_arguments_api #' #' @details #' You can also use a vector of length 2 for any time queries (such as time @@ -120,6 +121,8 @@ read_waterdata_continuous <- function( value = NA, last_modified = NA_character_, time = NA_character_, + skipGeometry = TRUE, + bbox = NA, ..., convertType = getOption("dataRetrieval.convertType"), limit = getOption("dataRetrieval.limit"), @@ -132,7 +135,6 @@ read_waterdata_continuous <- function( rlang::check_dots_empty() args <- mget(names(formals())) - args[["skipGeometry"]] <- TRUE return_list <- get_ogc_data(args, output_id, service) diff --git a/man/read_waterdata_combined_meta.Rd b/man/read_waterdata_combined_meta.Rd index 4e7a3519a..f51477936 100644 --- a/man/read_waterdata_combined_meta.Rd +++ b/man/read_waterdata_combined_meta.Rd @@ -185,7 +185,7 @@ See also Details below for more information.} \item{site_type}{A description of the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} -\item{hydrologic_unit_code}{The United States is divided and sub-divided into successively smaller hydrologic units which are classified into four levels: regions, sub-regions, accounting units, and cataloging units. The hydrologic units are arranged within each other, from the smallest (cataloging units) to the largest (regions). Each hydrologic unit is identified by a unique hydrologic unit code (HUC) consisting of two to eight digits based on the four levels of classification in the hydrologic unit system.} +\item{hydrologic_unit_code}{The hydrologic unit code (HUC) for the monitoring location. Supports prefix matching — querying with a shorter HUC (e.g. "04") matches all locations within that hydrologic region.} \item{basin_code}{The Basin Code or "drainage basin code" is a two-digit code that further subdivides the 8-digit hydrologic-unit code. The drainage basin code is defined by the USGS State Office where the monitoring location is located.} @@ -237,7 +237,7 @@ See also Details below for more information.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, monitoring_location_id, agency_code, agency_name, monitoring_location_number, monitoring_location_name, district_code, country_code, country_name, state_code, state_name, county_code, county_name, minor_civil_division_code, site_type_code, site_type, hydrologic_unit_code, basin_code, altitude, altitude_accuracy, altitude_method_code, altitude_method_name, vertical_datum, vertical_datum_name, horizontal_positional_accuracy_code, horizontal_positional_accuracy, horizontal_position_method_code, horizontal_position_method_name, original_horizontal_datum, original_horizontal_datum_name, drainage_area, contributing_drainage_area, time_zone_abbreviation, uses_daylight_savings, construction_date, aquifer_code, national_aquifer_code, aquifer_type_code, well_constructed_depth, hole_constructed_depth, depth_source_code, field_measurement_id, unit_of_measure, parameter_name, parameter_code, statistic_id, last_modified, begin, end, data_type, computation_identifier, thresholds, sublocation_identifier, primary, web_description, parameter_description, parent_time_series_id. +geometry, monitoring_location_id, agency_code, agency_name, monitoring_location_number, monitoring_location_name, district_code, country_code, country_name, state_code, state_name, county_code, county_name, minor_civil_division_code, site_type_code, site_type, hydrologic_unit_code, basin_code, altitude, altitude_accuracy, altitude_method_code, altitude_method_name, vertical_datum, vertical_datum_name, horizontal_positional_accuracy_code, horizontal_positional_accuracy, horizontal_position_method_code, horizontal_position_method_name, original_horizontal_datum, original_horizontal_datum_name, drainage_area, contributing_drainage_area, time_zone_abbreviation, uses_daylight_savings, construction_date, aquifer_code, national_aquifer_code, aquifer_type_code, well_constructed_depth, hole_constructed_depth, depth_source_code, field_measurement_id, unit_of_measure, parameter_name, parameter_code, statistic_id, last_modified, begin, end, data_type, computation_identifier, thresholds, sublocation_identifier, primary, web_description, parameter_description, parent_time_series_id, data_gap_interval, reading_type. The default (\code{NA}) will return all columns of the data.} \item{skipGeometry}{This parameter can be used to skip response geometries for diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index e722a5ede..d7506db76 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -15,6 +15,8 @@ read_waterdata_continuous( value = NA, last_modified = NA_character_, time = NA_character_, + skipGeometry = TRUE, + bbox = NA, ..., convertType = getOption("dataRetrieval.convertType"), limit = getOption("dataRetrieval.limit"), @@ -76,6 +78,18 @@ Only features that have a \code{time} that intersects the value of datetime are See also Details below for more information.} +\item{skipGeometry}{This parameter can be used to skip response geometries for +each feature. The returning object will be a data frame with no spatial +information. The default \code{NA} will not specify the argument in the request.} + +\item{bbox}{Only features that have a geometry that intersects the bounding +box are selected.The bounding box is provided as four or six numbers, depending +on whether the coordinate reference system includes a vertical axis (height or +depth). Coordinates are assumed to be in crs 4326. The expected format is a numeric +vector structured: c(xmin,ymin,xmax,ymax). +Another way to think of it is c(Western-most longitude, +Southern-most latitude, Eastern-most longitude, Northern-most longitude).} + \item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} diff --git a/man/read_waterdata_field_meta.Rd b/man/read_waterdata_field_meta.Rd index 1ecfe588f..30bec39af 100644 --- a/man/read_waterdata_field_meta.Rd +++ b/man/read_waterdata_field_meta.Rd @@ -83,7 +83,7 @@ See also Details below for more information.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, field_measurement_id, monitoring_location_id, parameter_code, parameter_name, parameter_description, begin, end, last_modified. +geometry, field_measurement_id, reading_type, monitoring_location_id, parameter_code, parameter_name, parameter_description, begin, end, last_modified. The default (\code{NA}) will return all columns of the data.} \item{skipGeometry}{This parameter can be used to skip response geometries for diff --git a/man/read_waterdata_latest_continuous.Rd b/man/read_waterdata_latest_continuous.Rd index e980a60e6..5af72c3f8 100644 --- a/man/read_waterdata_latest_continuous.Rd +++ b/man/read_waterdata_latest_continuous.Rd @@ -36,7 +36,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, latest_continuous_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint. diff --git a/man/read_waterdata_latest_daily.Rd b/man/read_waterdata_latest_daily.Rd index 6eb5a386b..3989eb396 100644 --- a/man/read_waterdata_latest_daily.Rd +++ b/man/read_waterdata_latest_daily.Rd @@ -41,7 +41,7 @@ Multiple statistic_ids can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, latest_daily_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint. diff --git a/man/read_waterdata_monitoring_location.Rd b/man/read_waterdata_monitoring_location.Rd index 5072a644f..be42815ce 100644 --- a/man/read_waterdata_monitoring_location.Rd +++ b/man/read_waterdata_monitoring_location.Rd @@ -88,7 +88,7 @@ Multiple monitoring_location_ids can be requested as a character vector.} \item{site_type}{A description of the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} -\item{hydrologic_unit_code}{The United States is divided and sub-divided into successively smaller hydrologic units which are classified into four levels: regions, sub-regions, accounting units, and cataloging units. The hydrologic units are arranged within each other, from the smallest (cataloging units) to the largest (regions). Each hydrologic unit is identified by a unique hydrologic unit code (HUC) consisting of two to eight digits based on the four levels of classification in the hydrologic unit system.} +\item{hydrologic_unit_code}{The hydrologic unit code (HUC) for the monitoring location. Supports prefix matching — querying with a shorter HUC (e.g. "04") matches all locations within that hydrologic region.} \item{basin_code}{The Basin Code or "drainage basin code" is a two-digit code that further subdivides the 8-digit hydrologic-unit code. The drainage basin code is defined by the USGS State Office where the monitoring location is located.} diff --git a/man/read_waterdata_peaks.Rd b/man/read_waterdata_peaks.Rd index 830040abd..260b36548 100644 --- a/man/read_waterdata_peaks.Rd +++ b/man/read_waterdata_peaks.Rd @@ -42,7 +42,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, time_series_id, monitoring_location_id, parameter_code, peak_id, unit_of_measure, value, last_modified, time, water_year, year, month, day, time_of_day, peak_since, qualifier. +geometry, time_series_id, monitoring_location_id, parameter_code, unit_of_measure, value, last_modified, time, water_year, year, month, day, time_of_day, peak_since, qualifier. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint.} diff --git a/man/read_waterdata_ts_meta.Rd b/man/read_waterdata_ts_meta.Rd index 3188d4b8b..dd4c80cb2 100644 --- a/man/read_waterdata_ts_meta.Rd +++ b/man/read_waterdata_ts_meta.Rd @@ -49,7 +49,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, time_series_id, unit_of_measure, parameter_name, parameter_code, statistic_id, hydrologic_unit_code, state_name, last_modified, begin, end, begin_utc, end_utc, computation_period_identifier, computation_identifier, thresholds, sublocation_identifier, primary, monitoring_location_id, web_description, parameter_description, parent_time_series_id. +geometry, time_series_id, unit_of_measure, parameter_name, parameter_code, statistic_id, hydrologic_unit_code, state_name, last_modified, begin, end, begin_utc, end_utc, computation_period_identifier, computation_identifier, thresholds, sublocation_identifier, primary, monitoring_location_id, web_description, parameter_description, parent_time_series_id, data_gap_interval. The default (\code{NA}) will return all columns of the data.} \item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/statistic-codes/items}. @@ -99,7 +99,7 @@ Only features that have a \code{end_utc} that intersects the value of datetime a See also Details below for more information.} -\item{hydrologic_unit_code}{The United States is divided and sub-divided into successively smaller hydrologic units which are classified into four levels: regions, sub-regions, accounting units, and cataloging units. The hydrologic units are arranged within each other, from the smallest (cataloging units) to the largest (regions). Each hydrologic unit is identified by a unique hydrologic unit code (HUC) consisting of two to eight digits based on the four levels of classification in the hydrologic unit system.} +\item{hydrologic_unit_code}{The hydrologic unit code (HUC) for the monitoring location. Supports prefix matching — querying with a shorter HUC (e.g. "04") matches all locations within that hydrologic region.} \item{state_name}{The name of the state or state equivalent in which the monitoring location is located.} From bbfcca7013702baa2ff67a3379fa3cd5de91e393 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 24 Jun 2026 11:57:27 -0500 Subject: [PATCH 30/71] fix note --- R/read_waterdata_continuous.R | 1 - man/read_waterdata_continuous.Rd | 2 -- 2 files changed, 3 deletions(-) diff --git a/R/read_waterdata_continuous.R b/R/read_waterdata_continuous.R index 0f260ff7b..eff8cc876 100644 --- a/R/read_waterdata_continuous.R +++ b/R/read_waterdata_continuous.R @@ -8,7 +8,6 @@ #' for new direct download functions that are expected to be available sometime #' in 2026. #' -#' Geometry output is not supported in the continuous data API endpoint. #' #' @export #' @param monitoring_location_id `r get_ogc_params("continuous")$monitoring_location_id` diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index d7506db76..cb48d15b6 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -128,8 +128,6 @@ a single request. If no "time" is specified, the service will return the last single year of data. If this is a bottleneck, please check back for new direct download functions that are expected to be available sometime in 2026. - -Geometry output is not supported in the continuous data API endpoint. } \details{ You can also use a vector of length 2 for any time queries (such as time From 23e4b460e07e007ebeb1bc7bbd30ffd8fca3bfff Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 7 Jul 2026 13:25:15 -0500 Subject: [PATCH 31/71] cleanup metadata list --- R/read_waterdata_ratings.R | 207 +++++++++++++++------------------- man/read_waterdata_ratings.Rd | 9 +- 2 files changed, 96 insertions(+), 120 deletions(-) diff --git a/R/read_waterdata_ratings.R b/R/read_waterdata_ratings.R index cfe024276..3bb181211 100644 --- a/R/read_waterdata_ratings.R +++ b/R/read_waterdata_ratings.R @@ -56,19 +56,23 @@ #' file_type = "exsa") #' #' head(ratings_exsa[["USGS-01104475.exsa.rdb"]]$ratings) -#' ratings_exsa[["USGS-01104475.exsa.rdb"]]$metadata +#' m1 <- ratings_exsa[["USGS-01104475.exsa.rdb"]]$metadata +#' m1 #' #' ratings_corr <- read_waterdata_ratings( #' monitoring_location_id = monitoring_location_id, #' file_type = "corr") #' #' head(ratings_corr[["USGS-01104460.corr.rdb"]]$ratings) -#' ratings_corr[["USGS-01104460.corr.rdb"]]$metadata +#' m2 <- ratings_corr[["USGS-01104460.corr.rdb"]]$metadata +#' m2 #' #' rating_2 <- read_waterdata_ratings( #' monitoring_location_id = monitoring_location_id, #' file_type = c("corr", "exsa")) #' names(rating_2) +#' m3 <- rating_2$`USGS-01104460.exsa.rdb`$metadata +#' rat_data <- rating_2$`USGS-01104460.exsa.rdb`$ratings #' #' bbox <- c(-95.00, 40.0, -92.0, 42) #' @@ -78,7 +82,6 @@ #' recent_query <- read_waterdata_ratings(bbox = bbox, #' datetime = c(Sys.Date()-7, NA), #' download_and_parse = FALSE) -#' length(recent_query) #'} read_waterdata_ratings <- function( monitoring_location_id = NA_character_, @@ -154,7 +157,7 @@ read_waterdata_ratings <- function( basic_request() message("Requesting:\n", request$url) - + resp <- httr2::req_perform(request) log_rate_limit(resp) @@ -199,126 +202,96 @@ download_convert <- function(feature, file_path, file_type) { return(NULL) } -# Parse rating comment metadata into a data frame -parse_ratings_metadata <- function(ratings_df) { - raw_comments <- comment(ratings_df) - - if (is.null(raw_comments)) { - return(data.frame( - header = character(), - value = character() - )) +# Parse a single key=value or key="value" token into a named list +parse_kv_tokens <- function(line) { + kv_pat <- '([A-Za-z0-9_]+)\\s*=\\s*"([^"]*)"|([A-Za-z0-9_]+)\\s*=\\s*(\\S+)' + m <- gregexpr(kv_pat, line, perl = TRUE) + tokens <- regmatches(line, m)[[1]] + result <- list() + for (tok in tokens) { + key <- sub("^([A-Za-z0-9_]+)\\s*=.*", "\\1", tok, perl = TRUE) + val <- sub('^[A-Za-z0-9_]+\\s*=\\s*"?([^"]*)"?$', "\\1", tok, perl = TRUE) + result[[key]] <- val } + result +} - com <- data.frame( - line = raw_comments - ) - - # remove whitespace - com$line <- sub("^#\\s*//?", "", com$line) - com$line <- sub("^//", "", com$line) - com$line <- gsub("\\s+", " ", trimws(com$line)) - # concatenate warning info - warn_rows <- grepl("^WARNING", com$line) - warn_text <- sub("^WARNING\\s*", "", com$line[warn_rows]) - warn_text <- gsub("\\s+", " ", trimws(warn_text)) - warn_text <- warn_text[warn_text != ""] +parse_ratings_metadata <- function(ratings_df) { + raw_comments <- comment(ratings_df) - warning_block <- if (length(warn_text) > 0) { - paste(warn_text, collapse = " ") - } else { - "" + if (is.null(raw_comments)) { + return(data.frame()) } - non_warn <- com[!warn_rows, , drop = FALSE] + # strip leading # // or // + lines <- sub("^#\\s*//?\\s*", "", raw_comments) + lines <- sub("^//\\s*", "", lines) + lines <- trimws(lines) + lines <- lines[lines != ""] + + # collect WARNING lines + warn_idx <- grepl("^WARNING", lines) + warn_text <- trimws(sub("^WARNING\\s*", "", lines[warn_idx])) + warning_value <- paste(warn_text[warn_text != ""], collapse = " ") + lines <- lines[!warn_idx] + + # split each line into header and the rest + # header is the first all-caps+underscore token + header_pat <- "^([A-Z][A-Z0-9_]*)\\s*(.*)" + headers <- sub(header_pat, "\\1", lines, perl = TRUE) + bodies <- sub(header_pat, "\\2", lines, perl = TRUE) + + # group lines by header, preserving order of first appearance + unique_headers <- unique(headers) + + result <- list(WARNING = warning_value) + i <- 1 + for (hdr in unique_headers) { + idx <- which(headers == hdr) + body_lines <- bodies[idx] + + # parse each line's key=value pairs + parsed_rows <- lapply(body_lines, parse_kv_tokens) + + # check if any line has key=value pairs; if not, treat as plain text + has_kv <- sapply(parsed_rows, length) > 0 + + if (any(has_kv)) { + p_rows <- unlist(parsed_rows) + if (anyDuplicated(names(p_rows))) { + columns <- unique(names(p_rows)) + df <- data.frame(matrix( + NA_character_, + nrow = length(p_rows) / length(columns), + ncol = length(columns) + )) + names(df) <- columns + for (i in columns) { + df[[i]] <- p_rows[names(p_rows) %in% i] + } + } else { + df <- data.frame(t(p_rows)) + } - # group the key-value pairs in the data - kv_pat <- '[A-Za-z0-9_]+\\s*=\\s*"[^"]*"|[A-Za-z0-9_]+\\s*=\\s*[^\\s]+' - kv_match <- regmatches( - non_warn$line, - gregexpr(kv_pat, non_warn$line, perl = TRUE) - ) - has_kv <- sapply(kv_match, length) > 0 - kv_flat <- unlist(kv_match, use.names = FALSE) - - pairs_df <- data.frame( - header = sub("^([A-Za-z0-9_]+).*", "\\1", kv_flat, perl = TRUE), - value = gsub( - '^"|"$', - "", - gsub( - "\\s+", - " ", - trimws( - sub("^[A-Za-z0-9_]+\\s*=\\s*", "", kv_flat, perl = TRUE) + if (nrow(df) == 1 && ncol(df) == 1) { + result[[hdr]] <- df[[1]] + } else { + result[[hdr]] <- df + } + } else { + if (substr(body_lines, start = 1, stop = 1) == "=") { + result[[hdr]] <- substr(body_lines, start = 2, stop = nchar(body_lines)) + } else { + comment_label <- paste("Comment", i) + result[[comment_label]] <- paste( + trimws(c(hdr, body_lines)), + collapse = " " ) - ) - ) - ) - - # handle data with colons - colon_pat <- "^[A-Z][A-Z _-]+:" - colon_rows <- grepl(colon_pat, non_warn$line) - colon_lines <- non_warn$line[colon_rows] - - date_df <- data.frame( - header = gsub( - "\\s+", - " ", - trimws( - sub("^([A-Z][A-Z _-]+):.*$", "\\1", colon_lines, perl = TRUE) - ) - ), - value = gsub( - "\\s+", - " ", - trimws( - sub("^[A-Z][A-Z _-]+:\\s*", "", colon_lines, perl = TRUE) - ) - ) - ) - - # parse any lines that don't fit other patterns - other_lines <- non_warn$line[!has_kv & !colon_rows] - - other_df <- data.frame( - header = gsub( - "\\s+", - " ", - trimws( - sub("^([A-Z][A-Z _-]+).*$", "\\1", other_lines, perl = TRUE) - ) - ), - value = gsub( - "\\s+", - " ", - trimws( - sub("^[A-Z][A-Z _-]+\\s*", "", other_lines, perl = TRUE) - ) - ) - ) - - # combine into one dataframe to be added to list object - final <- rbind( - data.frame( - header = "WARNING", - value = warning_block - ), - pairs_df, - date_df, - other_df - ) - - final$value <- gsub("[\\x00-\\x1F\\x7F]+", " ", final$value, perl = TRUE) - final$value <- gsub("\\s+", " ", trimws(final$value)) - final$header <- gsub("\\s+", " ", trimws(final$header)) - - final <- final[!(final$header == "" & final$value == ""), , drop = FALSE] - final <- unique(final) - rownames(final) <- final$header - # final_t <- data.frame(t(final)) - rownames(final) <- NULL + i <- i + 1 + } + } + } - final + return(result) } diff --git a/man/read_waterdata_ratings.Rd b/man/read_waterdata_ratings.Rd index c2284e5fd..c883e0af5 100644 --- a/man/read_waterdata_ratings.Rd +++ b/man/read_waterdata_ratings.Rd @@ -96,19 +96,23 @@ ratings_exsa <- read_waterdata_ratings( file_type = "exsa") head(ratings_exsa[["USGS-01104475.exsa.rdb"]]$ratings) -ratings_exsa[["USGS-01104475.exsa.rdb"]]$metadata +m1 <- ratings_exsa[["USGS-01104475.exsa.rdb"]]$metadata +m1 ratings_corr <- read_waterdata_ratings( monitoring_location_id = monitoring_location_id, file_type = "corr") head(ratings_corr[["USGS-01104460.corr.rdb"]]$ratings) -ratings_corr[["USGS-01104460.corr.rdb"]]$metadata +m2 <- ratings_corr[["USGS-01104460.corr.rdb"]]$metadata +m2 rating_2 <- read_waterdata_ratings( monitoring_location_id = monitoring_location_id, file_type = c("corr", "exsa")) names(rating_2) +m3 <- rating_2$`USGS-01104460.exsa.rdb`$metadata +rat_data <- rating_2$`USGS-01104460.exsa.rdb`$ratings bbox <- c(-95.00, 40.0, -92.0, 42) @@ -118,7 +122,6 @@ length(bbox_query) recent_query <- read_waterdata_ratings(bbox = bbox, datetime = c(Sys.Date()-7, NA), download_and_parse = FALSE) -length(recent_query) } \dontshow{\}) # examplesIf} } From e94f179c8e480d1c30469dae1fc9b12c8d98509b Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 7 Jul 2026 13:56:35 -0500 Subject: [PATCH 32/71] latest field --- NAMESPACE | 1 + R/AAA.R | 5 +- R/read_waterdata_latest_field.R | 88 +++++++++++++++ _pkgdown.yml | 1 + man/read_waterdata_latest_field.Rd | 172 +++++++++++++++++++++++++++++ 5 files changed, 266 insertions(+), 1 deletion(-) create mode 100644 R/read_waterdata_latest_field.R create mode 100644 man/read_waterdata_latest_field.Rd diff --git a/NAMESPACE b/NAMESPACE index 45be56a32..57aa60499 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -55,6 +55,7 @@ export(read_waterdata_field_measurements) export(read_waterdata_field_meta) export(read_waterdata_latest_continuous) export(read_waterdata_latest_daily) +export(read_waterdata_latest_field) export(read_waterdata_metadata) export(read_waterdata_monitoring_location) export(read_waterdata_parameter_codes) diff --git a/R/AAA.R b/R/AAA.R index ad96e4649..1cd88cada 100644 --- a/R/AAA.R +++ b/R/AAA.R @@ -3,7 +3,9 @@ pkg.env <- new.env() .onLoad <- function(libname, pkgname) { suppressMessages(setAccess("public")) pkg.env$local_sf <- requireNamespace("sf", quietly = TRUE) - options("dataRetrieval.nldi_base" = "https://api.water.usgs.gov/nldi/linked-data/") + options( + "dataRetrieval.nldi_base" = "https://api.water.usgs.gov/nldi/linked-data/" + ) options("dataRetrieval.api_version" = "v0") options("dataRetrieval.api_version_stat" = "v0") options("dataRetrieval.attach_request" = TRUE) @@ -21,6 +23,7 @@ pkg.env <- new.env() "latest-continuous", "field-measurements", "latest-daily", + "latest-field-measurements", "continuous", "field-measurements-metadata", "combined-metadata", diff --git a/R/read_waterdata_latest_field.R b/R/read_waterdata_latest_field.R new file mode 100644 index 000000000..eece4a905 --- /dev/null +++ b/R/read_waterdata_latest_field.R @@ -0,0 +1,88 @@ +#' Get Latest USGS field Data +#' +#' @description `r get_description("latest-field-measurements")` +#' +#' @export +#' @param monitoring_location_id `r get_ogc_params("latest-field-measurements")$monitoring_location_id` +#' Multiple monitoring_location_ids can be requested as a character vector. +#' @param parameter_code `r get_ogc_params("latest-field-measurements")$parameter_code` +#' Multiple parameter_codes can be requested as a character vector. +#' @param statistic_id `r get_ogc_params("latest-field-measurements")$statistic_id` +#' Multiple statistic_ids can be requested as a character vector. +#' @param time `r get_ogc_params("latest-field-measurements")$time` +#' +#' See also Details below for more information. +#' @param value `r get_ogc_params("latest-field-measurements")$value` +#' @param unit_of_measure `r get_ogc_params("latest-field-measurements")$unit_of_measure` +#' @param approval_status `r get_ogc_params("latest-field-measurements")$approval_status` +#' @param last_modified `r get_ogc_params("latest-field-measurements")$last_modified` +#' +#' See also Details below for more information. +#' @param time_series_id `r get_ogc_params("latest-field-measurements")$time_series_id` +#' Multiple time_series_ids can be requested as a character vector. +#' @param qualifier `r get_ogc_params("latest-field-measurements")$qualifier` +#' @param properties A vector of requested columns to be returned from the query. +#' Available options are: +#' `r dataRetrieval:::get_properties_for_docs("latest-field-measurements", "latest_field_id")`. +#' The default (`NA`) will return all columns of the data. +#' +#' @inheritParams check_arguments_api +#' @inheritParams check_arguments_non_api +#' @inherit read_waterdata_continuous details +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' site <- "USGS-02238500" +#' pcode <- "00060" +#' dv_data_sf <- read_waterdata_latest_field(monitoring_location_id = site, +#' parameter_code = pcode) +#' +#' dv_data_last_modified <- read_waterdata_latest_field(monitoring_location_id = site, +#' parameter_code = pcode, +#' last_modified = "P7D") +#' +#' dv_data_trim <- read_waterdata_latest_field(monitoring_location_id = site, +#' parameter_code = pcode, +#' properties = c("monitoring_location_id", +#' "value", +#' "time")) +#' +#' dv_data <- read_waterdata_latest_field(monitoring_location_id = site, +#' parameter_code = pcode, +#' skipGeometry = TRUE) +#' +#' multi_site <- read_waterdata_latest_field(monitoring_location_id = c("USGS-01491000", +#' "USGS-01645000")) +#' +#' } +read_waterdata_latest_field <- function( + monitoring_location_id = NA_character_, + parameter_code = NA_character_, + statistic_id = NA_character_, + properties = NA_character_, + time_series_id = NA_character_, + approval_status = NA_character_, + unit_of_measure = NA_character_, + qualifier = NA_character_, + value = NA, + last_modified = NA_character_, + skipGeometry = NA, + time = NA_character_, + bbox = NA, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + limit = getOption("dataRetrieval.limit"), + chunk_size = getOption("dataRetrieval.site_chunk_size_meta"), + attach_request = getOption("dataRetrieval.attach_request") +) { + service <- "latest-field-measurements" + output_id <- "latest_field_id" + rlang::check_dots_empty() + + args <- mget(names(formals())) + return_list <- get_ogc_data(args, output_id, service) + + return(return_list) +} diff --git a/_pkgdown.yml b/_pkgdown.yml index 2adf3191a..c6e298089 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -79,6 +79,7 @@ reference: - read_waterdata_monitoring_location - read_waterdata_latest_continuous - read_waterdata_latest_daily + - read_waterdata_latest_field - read_waterdata_field_measurements - read_waterdata_parameter_codes - read_waterdata_metadata diff --git a/man/read_waterdata_latest_field.Rd b/man/read_waterdata_latest_field.Rd new file mode 100644 index 000000000..a05dc71e9 --- /dev/null +++ b/man/read_waterdata_latest_field.Rd @@ -0,0 +1,172 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_waterdata_latest_field.R +\name{read_waterdata_latest_field} +\alias{read_waterdata_latest_field} +\title{Get Latest USGS field Data} +\usage{ +read_waterdata_latest_field( + monitoring_location_id = NA_character_, + parameter_code = NA_character_, + statistic_id = NA_character_, + properties = NA_character_, + time_series_id = NA_character_, + approval_status = NA_character_, + unit_of_measure = NA_character_, + qualifier = NA_character_, + value = NA, + last_modified = NA_character_, + skipGeometry = NA, + time = NA_character_, + bbox = NA, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + limit = getOption("dataRetrieval.limit"), + chunk_size = getOption("dataRetrieval.site_chunk_size_meta"), + attach_request = getOption("dataRetrieval.attach_request") +) +} +\arguments{ +\item{monitoring_location_id}{A unique identifier representing a single monitoring location. This corresponds to the \code{id} field in the \code{monitoring-locations} endpoint. Monitoring location IDs are created by combining the agency code of the agency responsible for the monitoring location (e.g. USGS) with the ID number of the monitoring location (e.g. 02238500), separated by a hyphen (e.g. USGS-02238500). + +Multiple monitoring_location_ids can be requested as a character vector.} + +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. + +Multiple parameter_codes can be requested as a character vector.} + +\item{statistic_id}{Multiple statistic_ids can be requested as a character vector.} + +\item{properties}{A vector of requested columns to be returned from the query. +Available options are: +geometry, field_measurements_series_id, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified, control_condition, measurement_rated, year, month, day, time_of_day. +The default (\code{NA}) will return all columns of the data.} + +\item{time_series_id}{Multiple time_series_ids can be requested as a character vector.} + +\item{approval_status}{Some of the data that you have obtained from this U.S. Geological Survey database may not have received Director's approval. Any such data values are qualified as provisional and are subject to revision. Provisional data are released on the condition that neither the USGS nor the United States Government may be held liable for any damages resulting from its use. This field reflects the approval status of each record, and is either "Approved", meaining processing review has been completed and the data is approved for publication, or "Provisional" and subject to revision. For more information about provisional data, go to \url{https://waterdata.usgs.gov/provisional-data-statement/}.} + +\item{unit_of_measure}{A human-readable description of the units of measurement associated with an observation.} + +\item{qualifier}{This field indicates any qualifiers associated with an observation, for instance if a sensor may have been impacted by ice or if values were estimated.} + +\item{value}{The value of the observation. Values are transmitted as strings in the JSON response format in order to preserve precision.} + +\item{last_modified}{The last time a record was refreshed in our database. This may happen due to regular operational processes and does not necessarily indicate anything about the measurement has changed. +You can query this field using date-times or intervals, adhering to RFC 3339, or using ISO 8601 duration objects. Intervals may be bounded or half-bounded (double-dots at start or end). +Examples: +\itemize{ +\item A date-time: "2018-02-12T23:20:50Z" +\item A bounded interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" +\item Half-bounded intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z" +\item Duration objects: "P1M" for data from the past month or "PT36H" for the last 36 hours +} + +Only features that have a \code{last_modified} that intersects the value of datetime are selected. + +See also Details below for more information.} + +\item{skipGeometry}{This parameter can be used to skip response geometries for +each feature. The returning object will be a data frame with no spatial +information. The default \code{NA} will not specify the argument in the request.} + +\item{time}{The date an observation represents. You can query this field using date-times or intervals, adhering to RFC 3339, or using ISO 8601 duration objects. Intervals may be bounded or half-bounded (double-dots at start or end). +Examples: +\itemize{ +\item A date-time: "2018-02-12T23:20:50Z" +\item A bounded interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" +\item Half-bounded intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z" +\item Duration objects: "P1M" for data from the past month or "PT36H" for the last 36 hours +} + +Only features that have a \code{time} that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties. + +See also Details below for more information.} + +\item{bbox}{Only features that have a geometry that intersects the bounding +box are selected.The bounding box is provided as four or six numbers, depending +on whether the coordinate reference system includes a vertical axis (height or +depth). Coordinates are assumed to be in crs 4326. The expected format is a numeric +vector structured: c(xmin,ymin,xmax,ymax). +Another way to think of it is c(Western-most longitude, +Southern-most latitude, Eastern-most longitude, Northern-most longitude).} + +\item{...}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} + +\item{no_paging}{logical, defaults to FALSE. +If \code{TRUE}, the data will +be requested from a native csv format. This can be dangerous because the +data will cut off at 50,000 rows without indication that more data +is available. Use \code{TRUE} with caution.} + +\item{limit}{numeric, The optional limit parameter is used to control the subset of the +selected features that should be returned in each page. The maximum allowable +limit is 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{chunk_size}{Number of monitoring_location_ids to chunk requests into. +The default for functions that don't generally return long-term data records +is 250, while +the default for time series functions is +10. +Setting to \code{NA} will eliminate site chunking, giving users full control.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} +} +\description{ +Field measurements are physically measured values collected during a visit to the monitoring location. Field measurements consist of measurements of gage height and discharge, and readings of groundwater levels, and are primarily used as calibration readings for the automated sensors collecting continuous data. They are collected at a low frequency, and delivery of the data in WDFN may be delayed due to data processing time. +} +\details{ +You can also use a vector of length 2 for any time queries (such as time +or last_modified). The first value is the starting date (or datetime), +the second value is the ending date(or datetime). +NA's within the vector indicate a half-bound date. +For example, \code{time = c("2024-01-01", NA)} will return all data starting +at 2024-01-01. +\code{time = c(NA, "2024-01-01")} will return all data from the beginning of +the timeseries until 2024-01-01. +By default, time is assumed UTC, although time zone attributes +will be accommodated. As an example, setting \code{time = as.POSIXct(c("2021-01-01 12:00:00", +"2021-01-01 14:00"), tz = "America/New_York")} will request data that between +noon and 2pm eastern time on 2021-01-01. +All time values RETURNED from the service are UTC with the exception of +daily data, which returns time values in local dates. +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +site <- "USGS-02238500" +pcode <- "00060" +dv_data_sf <- read_waterdata_latest_field(monitoring_location_id = site, + parameter_code = pcode) + +dv_data_last_modified <- read_waterdata_latest_field(monitoring_location_id = site, + parameter_code = pcode, + last_modified = "P7D") + +dv_data_trim <- read_waterdata_latest_field(monitoring_location_id = site, + parameter_code = pcode, + properties = c("monitoring_location_id", + "value", + "time")) + +dv_data <- read_waterdata_latest_field(monitoring_location_id = site, + parameter_code = pcode, + skipGeometry = TRUE) + +multi_site <- read_waterdata_latest_field(monitoring_location_id = c("USGS-01491000", + "USGS-01645000"), + parameter_code = c("00060", "00010")) + +} +\dontshow{\}) # examplesIf} +} From 51792cff3eea534ded807be1439b76916a09f858 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 7 Jul 2026 14:52:45 -0500 Subject: [PATCH 33/71] First pass at latest_field --- R/read_waterdata_latest_field.R | 17 +++++------------ man/read_waterdata_latest_field.Rd | 18 +++++------------- man/read_wateruse.Rd | 2 +- tests/testthat/tests_userFriendly_fxns.R | 10 +++++++++- 4 files changed, 20 insertions(+), 27 deletions(-) diff --git a/R/read_waterdata_latest_field.R b/R/read_waterdata_latest_field.R index eece4a905..46e179701 100644 --- a/R/read_waterdata_latest_field.R +++ b/R/read_waterdata_latest_field.R @@ -33,27 +33,20 @@ #' @examplesIf is_dataRetrieval_user() #' #' \donttest{ -#' site <- "USGS-02238500" -#' pcode <- "00060" -#' dv_data_sf <- read_waterdata_latest_field(monitoring_location_id = site, -#' parameter_code = pcode) +#' site <- "USGS-01435000" #' -#' dv_data_last_modified <- read_waterdata_latest_field(monitoring_location_id = site, -#' parameter_code = pcode, -#' last_modified = "P7D") +#' field_data_sf <- read_waterdata_latest_field(monitoring_location_id = site) #' #' dv_data_trim <- read_waterdata_latest_field(monitoring_location_id = site, -#' parameter_code = pcode, #' properties = c("monitoring_location_id", #' "value", #' "time")) #' -#' dv_data <- read_waterdata_latest_field(monitoring_location_id = site, -#' parameter_code = pcode, +#' field_data <- read_waterdata_latest_field(monitoring_location_id = site, #' skipGeometry = TRUE) #' -#' multi_site <- read_waterdata_latest_field(monitoring_location_id = c("USGS-01491000", -#' "USGS-01645000")) +#' multi_site <- read_waterdata_latest_field(monitoring_location_id = c("USGS-01435000", +#' "USGS-14202650")) #' #' } read_waterdata_latest_field <- function( diff --git a/man/read_waterdata_latest_field.Rd b/man/read_waterdata_latest_field.Rd index a05dc71e9..6abc209bb 100644 --- a/man/read_waterdata_latest_field.Rd +++ b/man/read_waterdata_latest_field.Rd @@ -144,28 +144,20 @@ daily data, which returns time values in local dates. \dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} \donttest{ -site <- "USGS-02238500" -pcode <- "00060" -dv_data_sf <- read_waterdata_latest_field(monitoring_location_id = site, - parameter_code = pcode) +site <- "USGS-01435000" -dv_data_last_modified <- read_waterdata_latest_field(monitoring_location_id = site, - parameter_code = pcode, - last_modified = "P7D") +field_data_sf <- read_waterdata_latest_field(monitoring_location_id = site) dv_data_trim <- read_waterdata_latest_field(monitoring_location_id = site, - parameter_code = pcode, properties = c("monitoring_location_id", "value", "time")) -dv_data <- read_waterdata_latest_field(monitoring_location_id = site, - parameter_code = pcode, +field_data <- read_waterdata_latest_field(monitoring_location_id = site, skipGeometry = TRUE) -multi_site <- read_waterdata_latest_field(monitoring_location_id = c("USGS-01491000", - "USGS-01645000"), - parameter_code = c("00060", "00010")) +multi_site <- read_waterdata_latest_field(monitoring_location_id = c("USGS-01435000", + "USGS-14202650")) } \dontshow{\}) # examplesIf} diff --git a/man/read_wateruse.Rd b/man/read_wateruse.Rd index f475e0e5e..96affc46c 100644 --- a/man/read_wateruse.Rd +++ b/man/read_wateruse.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/read_waterdata_use.R +% Please edit documentation in R/read_wateruse.R \name{read_wateruse} \alias{read_wateruse} \title{Get USGS Water Use Data} diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index 1ba3d9853..0ec325d96 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -132,7 +132,15 @@ test_that("peak, rating curves, surface-water measurements", { # Surface meas: siteNumbers <- c("USGS-01594440", "USGS-040851325") - data <- read_waterdata_field_measurements(siteNumbers) + data <- read_waterdata_field_measurements( + monitoring_location_id = siteNumbers + ) + expect_is(data$monitoring_location_id, "character") + + # Latest Surface meas: + latest_data <- read_waterdata_latest_field( + monitoring_location_id = siteNumbers + ) expect_is(data$monitoring_location_id, "character") siteINFO_USGS <- read_waterdata_monitoring_location( From ffc5adb68750d898537136041273ab27f67c5f4b Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 8 Jul 2026 13:52:12 -0500 Subject: [PATCH 34/71] adding non-returned query arguments --- NAMESPACE | 1 + R/check_non_returned.R | 194 ++++++++++++++++++++++ R/get_ogc_data.R | 55 ++---- R/read_waterdata_continuous.R | 21 ++- R/read_waterdata_daily.R | 24 ++- man/make_monitoring_location_arguments.Rd | 149 +++++++++++++++++ man/read_waterdata_continuous.Rd | 17 +- man/read_waterdata_daily.Rd | 15 ++ man/read_wateruse.Rd | 2 +- 9 files changed, 430 insertions(+), 48 deletions(-) create mode 100644 R/check_non_returned.R create mode 100644 man/make_monitoring_location_arguments.Rd diff --git a/NAMESPACE b/NAMESPACE index f4a171a28..5ec04a04d 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -23,6 +23,7 @@ export(importWQP) export(importWaterML1) export(importWaterML2) export(is_dataRetrieval_user) +export(make_monitoring_location_arguments) export(pCodeToName) export(parameterCdFile) export(parse_WQP) diff --git a/R/check_non_returned.R b/R/check_non_returned.R new file mode 100644 index 000000000..da0b4d47b --- /dev/null +++ b/R/check_non_returned.R @@ -0,0 +1,194 @@ +#' Check for arguments that can be queried but not returned +#' +#' @param agency_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_code$description` +#' @param agency_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_name$description` +#' @param monitoring_location_number `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$monitoring_location_number$description` +#' @param monitoring_location_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$monitoring_location_name$description` +#' @param district_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$district_code$description` +#' @param country_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$country_code$description` +#' @param country_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$country_name$description` +#' @param state_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$state_code$description` +#' @param state_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$state_name$description` +#' @param county_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$county_code$description` +#' @param county_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$county_name$description` +#' @param minor_civil_division_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$minor_civil_division_code$description` +#' @param site_type_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$site_type_code$description` +#' @param site_type `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$site_type$description` +#' @param hydrologic_unit_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$hydrologic_unit_code$description` +#' @param basin_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$basin_code$description` +#' @param altitude `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$altitude$description` +#' @param altitude_accuracy `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$altitude_accuracy$description` +#' @param altitude_method_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$altitude_method_code$description` +#' @param altitude_method_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$altitude_method_name$description` +#' @param vertical_datum `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$vertical_datum$description` +#' @param vertical_datum_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$vertical_datum_name$description` +#' @param horizontal_positional_accuracy_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$horizontal_positional_accuracy_code$description` +#' @param horizontal_positional_accuracy `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_code$description` +#' @param horizontal_position_method_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$horizontal_position_method_code$description` +#' @param horizontal_position_method_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$horizontal_position_method_name$description` +#' @param original_horizontal_datum `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$original_horizontal_datum$description` +#' @param original_horizontal_datum_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$original_horizontal_datum_name$description` +#' @param drainage_area `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$drainage_area$description` +#' @param contributing_drainage_area `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$contributing_drainage_area$description` +#' @param time_zone_abbreviation `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$time_zone_abbreviation$description` +#' @param uses_daylight_savings `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_code$description` +#' @param construction_date `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$construction_date$description` +#' @param aquifer_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$aquifer_code$description` +#' @param national_aquifer_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$national_aquifer_code$description` +#' @param aquifer_type_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_code$description` +#' @param well_constructed_depth `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$well_constructed_depth$description` +#' @param hole_constructed_depth `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$hole_constructed_depth$description` +#' @param depth_source_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$depth_source_code$description` +#' @param data_gap_interval `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$data_gap_interval$description` +#' @param \dots Not used. Used to make sure the user isn't passing in arguments that aren't available. +#' @param check_arguments Logical. Used to decide if the arguments passed in are available or not. The +#' default is `FALSE`. Using `TRUE` will make two calls to the API, so if you are concerted +#' with minimizing API calls, keep this value as `FALSE`. If you are concerned with +#' making sure your calls are accepted by the service, set to `TRUE`. +#' @export +#' @examples +#' +#' make_monitoring_location_arguments(service = "daily", agency_name = "USGS") +#' make_monitoring_location_arguments(service = "field-measurements", +#' state_name = c("Ohio", "Wisconsin")) +make_monitoring_location_arguments <- function( + service = c("daily"), + agency_code = NA_character_, + agency_name = NA_character_, + monitoring_location_number = NA_character_, + monitoring_location_name = NA_character_, + district_code = NA_character_, + country_code = NA_character_, + country_name = NA_character_, + state_code = NA_character_, + state_name = NA_character_, + county_code = NA_character_, + county_name = NA_character_, + minor_civil_division_code = NA_character_, + site_type_code = NA_character_, + site_type = NA_character_, + hydrologic_unit_code = NA_character_, + basin_code = NA_character_, + altitude = NA_character_, + altitude_accuracy = NA_character_, + altitude_method_code = NA_character_, + altitude_method_name = NA_character_, + vertical_datum = NA_character_, + vertical_datum_name = NA_character_, + horizontal_positional_accuracy_code = NA_character_, + horizontal_positional_accuracy = NA_character_, + horizontal_position_method_code = NA_character_, + horizontal_position_method_name = NA_character_, + original_horizontal_datum = NA_character_, + original_horizontal_datum_name = NA_character_, + drainage_area = NA_character_, + contributing_drainage_area = NA_character_, + time_zone_abbreviation = NA_character_, + uses_daylight_savings = NA_character_, + construction_date = NA_character_, + aquifer_code = NA_character_, + national_aquifer_code = NA_character_, + aquifer_type_code = NA_character_, + well_constructed_depth = NA_character_, + hole_constructed_depth = NA_character_, + depth_source_code = NA_character_, + data_gap_interval = NA_character_, + ..., + check_arguments = FALSE +) { + # Make sure no one passes in an argument that's not suppose to be there + rlang::check_dots_empty() + service_with_extra_queries <- c( + "daily", + "latest-continuous", + "field-measurements", + "latest-daily", + "latest-field-measurements", + "continuous", + "peaks" + ) + match.arg(service, choices = service_with_extra_queries, several.ok = FALSE) + + args <- mget(names(formals())) + args[["..."]] <- NULL + args[["service"]] <- NULL + args[["check_arguments"]] <- NULL + + n_args <- names(args) + + lapply(n_args, function(x) { + check_character(args[[x]], x) + }) + + if (check_arguments) { + # think about if we want this as an option + # don't want to waste a lot of hits to the API if people are + # running into their token limits + properties <- dataRetrieval::get_ogc_params(service) + queryables <- check_OGC_requests(endpoint = service, type = "queryables") + non_returned <- queryables$properties[ + !names(queryables$properties) %in% names(properties) + ] + + args_not_available <- args[!names(args) %in% names(non_returned)] + if (length(args_not_available) > 0) { + message( + "The ", + service, + " service doesn't accept: ", + paste0(names(args_not_available), collapse = ", "), + "." + ) + message("Those arguments will be ignored.") + } + + args <- args[names(args) %in% names(non_returned)] + } + + return(args) +} + +cleanup_arguments <- function(args, monitoring_location_arguments, service) { + query_args <- do.call( + make_monitoring_location_arguments, + c(monitoring_location_arguments, service = service) + ) + + args[["monitoring_location_arguments"]] <- NULL + + args <- c(args, query_args) + + return(args) +} + +check_character <- function(x, name) { + if (!is.null(x)) { + if (all(!is.na(x) & !is.character(x))) { + stop(paste(name, "should be a character")) + } + } +} + +check_numeric <- function(x, name) { + if (!is.null(x)) { + if (all(!is.na(x) & !is.numeric(x))) { + stop(paste(name, "should be a numeric")) + } + } +} + +check_integer <- function(x, name) { + if (!is.null(x)) { + if (all(!is.na(x) & !is.numeric(x))) { + stop(paste(name, "should be a integer")) + } + } +} + +check_logical <- function(x, name) { + if (!is.null(x)) { + if (all(!is.na(x) & !is.logical(x))) { + stop(paste(name, "should be a logical (TRUE/FALSE)")) + } + } +} diff --git a/R/get_ogc_data.R b/R/get_ogc_data.R index 4b01df231..0c929af29 100644 --- a/R/get_ogc_data.R +++ b/R/get_ogc_data.R @@ -54,13 +54,14 @@ get_ogc_data <- function(args, output_id, service, base = "OGC") { return_list <- walk_pages(req) } - return_list <- deal_with_empty(return_list = return_list, - properties = args[["properties"]], - service = service, - skipGeometry = isTRUE(args[["skipGeometry"]]), - convertType = args[["convertType"]], - no_paging = no_paging, - base = base + return_list <- deal_with_empty( + return_list = return_list, + properties = args[["properties"]], + service = service, + skipGeometry = isTRUE(args[["skipGeometry"]]), + convertType = args[["convertType"]], + no_paging = no_paging, + base = base ) return_list <- rejigger_cols(return_list, args[["properties"]], output_id) @@ -223,35 +224,11 @@ check_arguments_non_api <- function( chunk_size, ... ) { - if (!is.null(convertType)) { - if (!is.na(convertType) & !is.logical(convertType)) { - stop("convertType should be a logical TRUE/FALSE") - } - } - - if (!is.null(no_paging)) { - if (!is.na(no_paging) & !is.logical(no_paging)) { - stop("no_paging should be a logical TRUE/FALSE") - } - } - - if (!is.null(attach_request)) { - if (!is.na(attach_request) & !is.logical(attach_request)) { - stop("attach_request should be a logical TRUE/FALSE") - } - } - - if (!is.null(limit)) { - if (!is.na(limit) & !is.numeric(limit)) { - stop("limit should be an integer") - } - } - - if (!is.null(chunk_size)) { - if (!is.na(chunk_size) & !is.numeric(chunk_size)) { - stop("chunk_size should be an integer") - } - } + check_logical(convertType, "convertType") + check_logical(no_paging, "no_paging") + check_logical(attach_request, "attach_request") + check_integer(limit, "limit") + check_integer(chunk_size, "chunk_size") } #' Check other arguments @@ -271,11 +248,7 @@ check_arguments_non_api <- function( #' #' @keywords internal check_arguments_api <- function(bbox, skipGeometry) { - if (!is.null(skipGeometry)) { - if (!is.na(skipGeometry) & !is.logical(skipGeometry)) { - stop("skipGeometry should be a logical TRUE/FALSE") - } - } + check_logical(skipGeometry, "skipGeometry") if (!is.null(bbox)) { if (!all(is.na(bbox))) { diff --git a/R/read_waterdata_continuous.R b/R/read_waterdata_continuous.R index eff8cc876..c94bcec82 100644 --- a/R/read_waterdata_continuous.R +++ b/R/read_waterdata_continuous.R @@ -31,8 +31,10 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("continuous", "continuous_id")`. #' The default (`NA`) will return all columns of the data. -#' @param \dots Not used. Included to help differentiate official Water Data API arguments -#' from more seldom used, optional dataRetrieval-specific arguments. +#' @param monitoring_location_arguments A list of arguments that can be queried, +#' but are not returned. These are used as alternatives to specifying specific +#' monitoring_location_ids. +#' @seealso [make_monitoring_location_arguments()] #' @inheritParams check_arguments_non_api #' @inheritParams check_arguments_api #' @@ -76,6 +78,12 @@ #' parameter_code = c("00060", "72019"), #' last_modified = "P7D") #' +#' dane <- read_waterdata_continuous(monitoring_location_arguments = list( +#' state_name = "Wisconsin", +#' county_name = "Dane County"), +#' parameter_code = "00060", +#' time = "P1D") +#' #' # how to split up request into roughly 3 year chunks #' #' site <- "USGS-0208458892" @@ -122,6 +130,9 @@ read_waterdata_continuous <- function( time = NA_character_, skipGeometry = TRUE, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments( + service = "continuous" + ), ..., convertType = getOption("dataRetrieval.convertType"), limit = getOption("dataRetrieval.limit"), @@ -135,6 +146,12 @@ read_waterdata_continuous <- function( args <- mget(names(formals())) + args <- cleanup_arguments( + args = args, + monitoring_location_arguments = monitoring_location_arguments, + service = service + ) + return_list <- get_ogc_data(args, output_id, service) attr(return_list$time, "tzone") <- "UTC" diff --git a/R/read_waterdata_daily.R b/R/read_waterdata_daily.R index 13922ae1d..6d918268a 100644 --- a/R/read_waterdata_daily.R +++ b/R/read_waterdata_daily.R @@ -25,10 +25,12 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("daily", "daily_id")`. #' The default (`NA`) will return all columns of the data. -#' +#' @param monitoring_location_arguments A list of arguments that can be queried, +#' but are not returned. These are used as alternatives to specifying specific +#' monitoring_location_ids. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api -#' +#' @seealso [make_monitoring_location_arguments()] #' @inherit read_waterdata_continuous details #' #' @examplesIf is_dataRetrieval_user() @@ -73,6 +75,13 @@ #' dv_data_no_request <- read_waterdata_daily(monitoring_location_id = site, #' parameter_code = "00060", #' time = c("2021-01-01", "2022-01-01")) +#' +#' dv_dane <- read_waterdata_daily(monitoring_location_arguments = list( +#' state_name = "Wisconsin", +#' county_name = "Dane County"), +#' parameter_code = "00060", +#' time = "P7D") +#' #' } read_waterdata_daily <- function( monitoring_location_id = NA_character_, @@ -88,6 +97,9 @@ read_waterdata_daily <- function( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments( + service = "daily" + ), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -98,8 +110,14 @@ read_waterdata_daily <- function( service <- "daily" output_id <- "daily_id" rlang::check_dots_empty() - args <- mget(names(formals())) + + args <- cleanup_arguments( + args = args, + monitoring_location_arguments = monitoring_location_arguments, + service = service + ) + return_list <- get_ogc_data(args, output_id, service, base = "OGC") return(return_list) diff --git a/man/make_monitoring_location_arguments.Rd b/man/make_monitoring_location_arguments.Rd new file mode 100644 index 000000000..0668ce21a --- /dev/null +++ b/man/make_monitoring_location_arguments.Rd @@ -0,0 +1,149 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/check_non_returned.R +\name{make_monitoring_location_arguments} +\alias{make_monitoring_location_arguments} +\title{Check for arguments that can be queried but not returned} +\usage{ +make_monitoring_location_arguments( + service = c("daily"), + agency_code = NA_character_, + agency_name = NA_character_, + monitoring_location_number = NA_character_, + monitoring_location_name = NA_character_, + district_code = NA_character_, + country_code = NA_character_, + country_name = NA_character_, + state_code = NA_character_, + state_name = NA_character_, + county_code = NA_character_, + county_name = NA_character_, + minor_civil_division_code = NA_character_, + site_type_code = NA_character_, + site_type = NA_character_, + hydrologic_unit_code = NA_character_, + basin_code = NA_character_, + altitude = NA_character_, + altitude_accuracy = NA_character_, + altitude_method_code = NA_character_, + altitude_method_name = NA_character_, + vertical_datum = NA_character_, + vertical_datum_name = NA_character_, + horizontal_positional_accuracy_code = NA_character_, + horizontal_positional_accuracy = NA_character_, + horizontal_position_method_code = NA_character_, + horizontal_position_method_name = NA_character_, + original_horizontal_datum = NA_character_, + original_horizontal_datum_name = NA_character_, + drainage_area = NA_character_, + contributing_drainage_area = NA_character_, + time_zone_abbreviation = NA_character_, + uses_daylight_savings = NA_character_, + construction_date = NA_character_, + aquifer_code = NA_character_, + national_aquifer_code = NA_character_, + aquifer_type_code = NA_character_, + well_constructed_depth = NA_character_, + hole_constructed_depth = NA_character_, + depth_source_code = NA_character_, + data_gap_interval = NA_character_, + ..., + check_arguments = FALSE +) +} +\arguments{ +\item{agency_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} + +\item{agency_name}{The name of the agency that is reporting the data.} + +\item{monitoring_location_number}{Each monitoring location in the USGS data base has a unique 8- to 15-digit identification number.} + +\item{monitoring_location_name}{This is the official name of the monitoring location in the database. For well information this can be a district-assigned local number.} + +\item{district_code}{The Water Science Centers (WSCs) across the United States use the FIPS state code as the district code. In some case, monitoring locations and samples may be managed by a water science center that is adjacent to the state in which the monitoring location actually resides. For example a monitoring location may have a district code of 30 which translates to Montana, but the state code could be 56 for Wyoming because that is where the monitoring location actually is located.} + +\item{country_code}{The code for the country in which the monitoring location is located.} + +\item{country_name}{The name of the country in which the monitoring location is located.} + +\item{state_code}{State code. A \href{https://www2.census.gov/geo/docs/reference/state.txt}{two-digit ANSI code} (formerly FIPS code) as defined by the American National Standards Institute, to define States and equivalents. A three-digit ANSI code is used to define counties and county equivalents. \href{https://www.census.gov/library/reference/code-lists/ansi.html#states}{A lookup table is available.} The only countries with political subdivisions other than the US are Mexico and Canada. The Mexican states have US state codes ranging from 81-86 and Canadian provinces have state codes ranging from 90-98.} + +\item{state_name}{The name of the state or state equivalent in which the monitoring location is located.} + +\item{county_code}{The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items}.} + +\item{county_name}{The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. [A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items}.} + +\item{minor_civil_division_code}{Codes for primary governmental or administrative divisions of the county or county equivalent in which the monitoring location is located.} + +\item{site_type_code}{A code describing the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} + +\item{site_type}{A description of the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} + +\item{hydrologic_unit_code}{The hydrologic unit code (HUC) for the monitoring location. Supports prefix matching — querying with a shorter HUC (e.g. "04") matches all locations within that hydrologic region.} + +\item{basin_code}{The Basin Code or "drainage basin code" is a two-digit code that further subdivides the 8-digit hydrologic-unit code. The drainage basin code is defined by the USGS State Office where the monitoring location is located.} + +\item{altitude}{Altitude of the monitoring location referenced to the specified Vertical Datum.} + +\item{altitude_accuracy}{Accuracy of the altitude, in feet. An accuracy of +/- 0.1 foot would be entered as “.1”. Many altitudes are interpolated from the contours on topographic maps; accuracies determined in this way are generally entered as one-half of the contour interval.} + +\item{altitude_method_code}{Codes representing the method used to measure altitude.} + +\item{altitude_method_name}{The name of the method used to measure altitude.} + +\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} + +\item{vertical_datum_name}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} + +\item{horizontal_positional_accuracy_code}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items}.} + +\item{horizontal_positional_accuracy}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} + +\item{horizontal_position_method_code}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items}.} + +\item{horizontal_position_method_name}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items}.} + +\item{original_horizontal_datum}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items}.} + +\item{original_horizontal_datum_name}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items}.} + +\item{drainage_area}{The area enclosed by a topographic divide from which direct surface runoff from precipitation normally drains by gravity into the stream above that point.} + +\item{contributing_drainage_area}{The contributing drainage area of a lake, stream, wetland, or estuary monitoring location, in square miles. This item should be present only if the contributing area is different from the total drainage area. This situation can occur when part of the drainage area consists of very porous soil or depressions that either allow all runoff to enter the groundwater or traps the water in ponds so that rainfall does not contribute to runoff. A transbasin diversion can also affect the total drainage area.} + +\item{time_zone_abbreviation}{A short code describing the time zone used by a monitoring location.} + +\item{uses_daylight_savings}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} + +\item{construction_date}{Date the well was completed.} + +\item{aquifer_code}{Local aquifers in the USGS water resources data base are identified by a geohydrologic unit code (a three-digit number related to the age of the formation, followed by a 4 or 5 character abbreviation for the geologic unit or aquifer name).} + +\item{national_aquifer_code}{National aquifers are the principal aquifers or aquifer systems in the United States, defined as regionally extensive aquifers or aquifer systems that have the potential to be used as a source of potable water. Not all groundwater monitoring locations can be associated with a National Aquifer. Such monitoring locations will not be retrieved using this search criteria. A list of National aquifer codes and names is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/national-aquifer-codes/items}.} + +\item{aquifer_type_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} + +\item{well_constructed_depth}{The depth of the finished well, in feet below land surface datum. Note: Not all groundwater monitoring locations have information on Well Depth. Such monitoring locations will not be retrieved using this search criteria.} + +\item{hole_constructed_depth}{The total depth to which the hole is drilled, in feet below land surface datum. Note: Not all groundwater monitoring locations have information on Hole Depth. Such monitoring locations will not be retrieved using this search criteria.} + +\item{depth_source_code}{A code indicating the source of water-level data.} + +\item{data_gap_interval}{The time interval threshold used for gap detection in the time series.} + +\item{\dots}{Not used. Used to make sure the user isn't passing in arguments that aren't available.} + +\item{check_arguments}{Logical. Used to decide if the arguments passed in are available or not. The +default is \code{FALSE}. Using \code{TRUE} will make two calls to the API, so if you are concerted +with minimizing API calls, keep this value as \code{FALSE}. If you are concerned with +making sure your calls are accepted by the service, set to \code{TRUE}.} +} +\description{ +Check for arguments that can be queried but not returned +} +\examples{ + +make_monitoring_location_arguments(service = "daily", agency_name = "USGS") +make_monitoring_location_arguments(service = "field-measurements", + state_name = c("Ohio", "Wisconsin")) +} diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index cb48d15b6..fd1ae7eb2 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -17,6 +17,8 @@ read_waterdata_continuous( time = NA_character_, skipGeometry = TRUE, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments(service = + "continuous"), ..., convertType = getOption("dataRetrieval.convertType"), limit = getOption("dataRetrieval.limit"), @@ -90,7 +92,11 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} -\item{\dots}{Not used. Included to help differentiate official Water Data API arguments +\item{monitoring_location_arguments}{A list of arguments that can be queried, +but are not returned. These are used as alternatives to specifying specific +monitoring_location_ids.} + +\item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} \item{convertType}{logical, defaults to TRUE. @@ -170,6 +176,12 @@ multi_site2 <- read_waterdata_continuous(monitoring_location_id = c("USGS-45160 parameter_code = c("00060", "72019"), last_modified = "P7D") +dane <- read_waterdata_continuous(monitoring_location_arguments = list( + state_name = "Wisconsin", + county_name = "Dane County"), + parameter_code = "00060", + time = "P1D") + # how to split up request into roughly 3 year chunks site <- "USGS-0208458892" @@ -205,3 +217,6 @@ time_df <- data.frame(start = time_chunks[-length(time_chunks)], } \dontshow{\}) # examplesIf} } +\seealso{ +\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +} diff --git a/man/read_waterdata_daily.Rd b/man/read_waterdata_daily.Rd index 9c0efdd08..051fe248a 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -18,6 +18,7 @@ read_waterdata_daily( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments(service = "daily"), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -95,6 +96,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} +\item{monitoring_location_arguments}{A list of arguments that can be queried, +but are not returned. These are used as alternatives to specifying specific +monitoring_location_ids.} + \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} @@ -187,6 +192,16 @@ options("dataRetrieval.attach_request" = FALSE) dv_data_no_request <- read_waterdata_daily(monitoring_location_id = site, parameter_code = "00060", time = c("2021-01-01", "2022-01-01")) + +dv_dane <- read_waterdata_daily(monitoring_location_arguments = list( + state_name = "Wisconsin", + county_name = "Dane County"), + parameter_code = "00060", + time = "P7D") + } \dontshow{\}) # examplesIf} } +\seealso{ +\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +} diff --git a/man/read_wateruse.Rd b/man/read_wateruse.Rd index f475e0e5e..96affc46c 100644 --- a/man/read_wateruse.Rd +++ b/man/read_wateruse.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/read_waterdata_use.R +% Please edit documentation in R/read_wateruse.R \name{read_wateruse} \alias{read_wateruse} \title{Get USGS Water Use Data} From cce5080357bfc408d449b96afb8a6b714dccdfea Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 8 Jul 2026 15:02:11 -0500 Subject: [PATCH 35/71] add service --- R/check_non_returned.R | 3 +++ 1 file changed, 3 insertions(+) diff --git a/R/check_non_returned.R b/R/check_non_returned.R index da0b4d47b..32e4c0895 100644 --- a/R/check_non_returned.R +++ b/R/check_non_returned.R @@ -1,5 +1,8 @@ #' Check for arguments that can be queried but not returned #' +#' @param service Endpoint to check arguments against. Possible values are +#' "daily", "latest-continuous", "field-measurements", "latest-daily", +#' "latest-field-measurements", "continuous", "peaks". #' @param agency_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_code$description` #' @param agency_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_name$description` #' @param monitoring_location_number `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$monitoring_location_number$description` From eb88086e54f0f7a59f73de8d54af9e0d45f7138c Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 8 Jul 2026 15:09:29 -0500 Subject: [PATCH 36/71] change name --- NAMESPACE | 2 +- R/read_waterdata_latest_field.R | 12 ++++++------ ... read_waterdata_latest_field_measurements.Rd} | 16 ++++++++-------- tests/testthat/tests_userFriendly_fxns.R | 2 +- 4 files changed, 16 insertions(+), 16 deletions(-) rename man/{read_waterdata_latest_field.Rd => read_waterdata_latest_field_measurements.Rd} (94%) diff --git a/NAMESPACE b/NAMESPACE index 5e6588bcc..58e18e703 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -55,7 +55,7 @@ export(read_waterdata_field_measurements) export(read_waterdata_field_meta) export(read_waterdata_latest_continuous) export(read_waterdata_latest_daily) -export(read_waterdata_latest_field) +export(read_waterdata_latest_field_measurements) export(read_waterdata_metadata) export(read_waterdata_monitoring_location) export(read_waterdata_parameter_codes) diff --git a/R/read_waterdata_latest_field.R b/R/read_waterdata_latest_field.R index 46e179701..f7a1dcf28 100644 --- a/R/read_waterdata_latest_field.R +++ b/R/read_waterdata_latest_field.R @@ -1,4 +1,4 @@ -#' Get Latest USGS field Data +#' Get latest USGS field measurement data #' #' @description `r get_description("latest-field-measurements")` #' @@ -35,21 +35,21 @@ #' \donttest{ #' site <- "USGS-01435000" #' -#' field_data_sf <- read_waterdata_latest_field(monitoring_location_id = site) +#' field_data_sf <- read_waterdata_latest_field_measurements(monitoring_location_id = site) #' -#' dv_data_trim <- read_waterdata_latest_field(monitoring_location_id = site, +#' dv_data_trim <- read_waterdata_latest_field_measurements(monitoring_location_id = site, #' properties = c("monitoring_location_id", #' "value", #' "time")) #' -#' field_data <- read_waterdata_latest_field(monitoring_location_id = site, +#' field_data <- read_waterdata_latest_field_measurements(monitoring_location_id = site, #' skipGeometry = TRUE) #' -#' multi_site <- read_waterdata_latest_field(monitoring_location_id = c("USGS-01435000", +#' multi_site <- read_waterdata_latest_field_measurements(monitoring_location_id = c("USGS-01435000", #' "USGS-14202650")) #' #' } -read_waterdata_latest_field <- function( +read_waterdata_latest_field_measurements <- function( monitoring_location_id = NA_character_, parameter_code = NA_character_, statistic_id = NA_character_, diff --git a/man/read_waterdata_latest_field.Rd b/man/read_waterdata_latest_field_measurements.Rd similarity index 94% rename from man/read_waterdata_latest_field.Rd rename to man/read_waterdata_latest_field_measurements.Rd index 6abc209bb..3303acfe5 100644 --- a/man/read_waterdata_latest_field.Rd +++ b/man/read_waterdata_latest_field_measurements.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/read_waterdata_latest_field.R -\name{read_waterdata_latest_field} -\alias{read_waterdata_latest_field} -\title{Get Latest USGS field Data} +\name{read_waterdata_latest_field_measurements} +\alias{read_waterdata_latest_field_measurements} +\title{Get latest USGS field measurement data} \usage{ -read_waterdata_latest_field( +read_waterdata_latest_field_measurements( monitoring_location_id = NA_character_, parameter_code = NA_character_, statistic_id = NA_character_, @@ -146,17 +146,17 @@ daily data, which returns time values in local dates. \donttest{ site <- "USGS-01435000" -field_data_sf <- read_waterdata_latest_field(monitoring_location_id = site) +field_data_sf <- read_waterdata_latest_field_measurements(monitoring_location_id = site) -dv_data_trim <- read_waterdata_latest_field(monitoring_location_id = site, +dv_data_trim <- read_waterdata_latest_field_measurements(monitoring_location_id = site, properties = c("monitoring_location_id", "value", "time")) -field_data <- read_waterdata_latest_field(monitoring_location_id = site, +field_data <- read_waterdata_latest_field_measurements(monitoring_location_id = site, skipGeometry = TRUE) -multi_site <- read_waterdata_latest_field(monitoring_location_id = c("USGS-01435000", +multi_site <- read_waterdata_latest_field_measurements(monitoring_location_id = c("USGS-01435000", "USGS-14202650")) } diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index 0ec325d96..b59e8fbd9 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -138,7 +138,7 @@ test_that("peak, rating curves, surface-water measurements", { expect_is(data$monitoring_location_id, "character") # Latest Surface meas: - latest_data <- read_waterdata_latest_field( + latest_data <- read_waterdata_latest_field_measurements( monitoring_location_id = siteNumbers ) expect_is(data$monitoring_location_id, "character") From 93383c5af36232d82f9b211ebd6e7077ec8ef0e6 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 8 Jul 2026 15:20:01 -0500 Subject: [PATCH 37/71] more functions with queries --- R/read_waterdata_continuous.R | 12 +++++++----- R/read_waterdata_field_measurements.R | 22 ++++++++++++++++++++++ R/read_waterdata_latest_continuous.R | 14 ++++++++++++++ 3 files changed, 43 insertions(+), 5 deletions(-) diff --git a/R/read_waterdata_continuous.R b/R/read_waterdata_continuous.R index c94bcec82..842aa1183 100644 --- a/R/read_waterdata_continuous.R +++ b/R/read_waterdata_continuous.R @@ -78,11 +78,13 @@ #' parameter_code = c("00060", "72019"), #' last_modified = "P7D") #' -#' dane <- read_waterdata_continuous(monitoring_location_arguments = list( -#' state_name = "Wisconsin", -#' county_name = "Dane County"), -#' parameter_code = "00060", -#' time = "P1D") +#' dane <- read_waterdata_continuous( +#' monitoring_location_arguments = list( +#' state_name = "Wisconsin", +#' county_name = "Dane County" +#' ), +#' parameter_code = "00060", +#' time = "P1D") #' #' # how to split up request into roughly 3 year chunks #' diff --git a/R/read_waterdata_field_measurements.R b/R/read_waterdata_field_measurements.R index 25d822569..99a458632 100644 --- a/R/read_waterdata_field_measurements.R +++ b/R/read_waterdata_field_measurements.R @@ -37,8 +37,12 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("field-measurements", "field_measurement_id")`. #' The default (`NA`) will return all columns of the data. +#' @param monitoring_location_arguments A list of arguments that can be queried, +#' but are not returned. These are used as alternatives to specifying specific +#' monitoring_location_ids. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api +#' @seealso [make_monitoring_location_arguments()] #' #' @inherit read_waterdata_continuous details #' @@ -81,6 +85,14 @@ #' time = "2024-07-01T00:00:00Z/..", #' parameter_code = "00060") #' +#' dane <- read_waterdata_field_measurements( +#' monitoring_location_arguments = list( +#' state_name = "Wisconsin", +#' county_name = "Dane County" +#' ), +#' parameter_code = "00060", +#' time = "P30D") +#' #' #' } read_waterdata_field_measurements <- function( @@ -103,6 +115,9 @@ read_waterdata_field_measurements <- function( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments( + service = "field-measurements" + ), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -115,6 +130,13 @@ read_waterdata_field_measurements <- function( rlang::check_dots_empty() args <- mget(names(formals())) + + args <- cleanup_arguments( + args = args, + monitoring_location_arguments = monitoring_location_arguments, + service = service + ) + return_list <- get_ogc_data(args, output_id, service) return(return_list) diff --git a/R/read_waterdata_latest_continuous.R b/R/read_waterdata_latest_continuous.R index e450561ae..948ba63e4 100644 --- a/R/read_waterdata_latest_continuous.R +++ b/R/read_waterdata_latest_continuous.R @@ -23,8 +23,12 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("latest-continuous", "latest_continuous_id")`. #' The default (`NA`) will return all columns of the data. +#' @param monitoring_location_arguments A list of arguments that can be queried, +#' but are not returned. These are used as alternatives to specifying specific +#' monitoring_location_ids. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api +#' @seealso [make_monitoring_location_arguments()] #' #' @inherit read_waterdata_continuous details #' @examplesIf is_dataRetrieval_user() @@ -74,6 +78,9 @@ read_waterdata_latest_continuous <- function( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments( + service = "latest-continuous" + ), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -86,6 +93,13 @@ read_waterdata_latest_continuous <- function( rlang::check_dots_empty() args <- mget(names(formals())) + + args <- cleanup_arguments( + args = args, + monitoring_location_arguments = monitoring_location_arguments, + service = service + ) + return_list <- get_ogc_data(args, output_id, service) return(return_list) From 1cb928e32449f5bb30667a324f0691d85e79018d Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 8 Jul 2026 15:37:38 -0500 Subject: [PATCH 38/71] more functions with extra queries --- R/read_waterdata_latest_continuous.R | 8 ++++++++ R/read_waterdata_latest_daily.R | 22 ++++++++++++++++++++++ R/read_waterdata_peaks.R | 21 +++++++++++++++++++++ man/make_monitoring_location_arguments.Rd | 4 ++++ man/read_waterdata_continuous.Rd | 12 +++++++----- man/read_waterdata_field_measurements.Rd | 17 +++++++++++++++++ man/read_waterdata_latest_continuous.Rd | 17 +++++++++++++++++ man/read_waterdata_latest_daily.Rd | 17 +++++++++++++++++ man/read_waterdata_peaks.Rd | 15 +++++++++++++++ 9 files changed, 128 insertions(+), 5 deletions(-) diff --git a/R/read_waterdata_latest_continuous.R b/R/read_waterdata_latest_continuous.R index 948ba63e4..f3575dc5c 100644 --- a/R/read_waterdata_latest_continuous.R +++ b/R/read_waterdata_latest_continuous.R @@ -64,6 +64,14 @@ #' parameter_code = c("00060", "72019"), #' last_modified = "P7D") #' +#' dane <- read_waterdata_latest_continuous( +#' monitoring_location_arguments = list( +#' state_name = "Wisconsin", +#' county_name = "Dane County" +#' ), +#' parameter_code = "00060", +#' time = "P1D") +#' #' } read_waterdata_latest_continuous <- function( monitoring_location_id = NA_character_, diff --git a/R/read_waterdata_latest_daily.R b/R/read_waterdata_latest_daily.R index 85bc6c11f..6c67904bd 100644 --- a/R/read_waterdata_latest_daily.R +++ b/R/read_waterdata_latest_daily.R @@ -25,9 +25,13 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("latest-daily", "latest_daily_id")`. #' The default (`NA`) will return all columns of the data. +#' @param monitoring_location_arguments A list of arguments that can be queried, +#' but are not returned. These are used as alternatives to specifying specific +#' monitoring_location_ids. #' #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api +#' @seealso [make_monitoring_location_arguments()] #' @inherit read_waterdata_continuous details #' #' @examplesIf is_dataRetrieval_user() @@ -56,6 +60,14 @@ #' "USGS-01645000"), #' parameter_code = c("00060", "00010")) #' +#' dane <- read_waterdata_latest_daily( +#' monitoring_location_arguments = list( +#' state_name = "Wisconsin", +#' county_name = "Dane County" +#' ), +#' parameter_code = "00060", +#' time = "P7D") +#' #' } read_waterdata_latest_daily <- function( monitoring_location_id = NA_character_, @@ -71,6 +83,9 @@ read_waterdata_latest_daily <- function( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments( + service = "latest-daily" + ), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -83,6 +98,13 @@ read_waterdata_latest_daily <- function( rlang::check_dots_empty() args <- mget(names(formals())) + + args <- cleanup_arguments( + args = args, + monitoring_location_arguments = monitoring_location_arguments, + service = service + ) + return_list <- get_ogc_data(args, output_id, service) return(return_list) diff --git a/R/read_waterdata_peaks.R b/R/read_waterdata_peaks.R index 3fb614475..d49cf9f91 100644 --- a/R/read_waterdata_peaks.R +++ b/R/read_waterdata_peaks.R @@ -36,8 +36,12 @@ #' or whether to set those dates to `NA` (`FALSE`). Peaks with uncertain days #' are stored on the first of the month, and those with uncertain #' month stored on January 1. Default is `FALSE`. +#' @param monitoring_location_arguments A list of arguments that can be queried, +#' but are not returned. These are used as alternatives to specifying specific +#' monitoring_location_ids. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api +#' @seealso [make_monitoring_location_arguments()] #' #' @inherit read_waterdata_continuous details #' @@ -54,6 +58,13 @@ #' monitoring_location_id = wi_peaks$monitoring_location_id[1], #' parameter_code = "00060") #' +#' dane <- read_waterdata_peaks( +#' monitoring_location_arguments = list( +#' state_name = "Wisconsin", +#' county_name = "Dane County" +#' ), +#' parameter_code = "00060") +#' #' incomplete_dates_not_allowed <- read_waterdata_peaks( #' monitoring_location_id = "USGS-06334330", #' parameter_code = "00060") @@ -83,6 +94,9 @@ read_waterdata_peaks <- function( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments( + service = "peaks" + ), ..., allow_incomplete_dates = FALSE, convertType = getOption("dataRetrieval.convertType"), @@ -96,6 +110,13 @@ read_waterdata_peaks <- function( rlang::check_dots_empty() args <- mget(names(formals())) + + args <- cleanup_arguments( + args = args, + monitoring_location_arguments = monitoring_location_arguments, + service = service + ) + args[["allow_incomplete_dates"]] <- NULL return_list <- get_ogc_data(args, output_id, service) diff --git a/man/make_monitoring_location_arguments.Rd b/man/make_monitoring_location_arguments.Rd index 0668ce21a..ebe061f2e 100644 --- a/man/make_monitoring_location_arguments.Rd +++ b/man/make_monitoring_location_arguments.Rd @@ -51,6 +51,10 @@ make_monitoring_location_arguments( ) } \arguments{ +\item{service}{Endpoint to check arguments against. Possible values are +"daily", "latest-continuous", "field-measurements", "latest-daily", +"latest-field-measurements", "continuous", "peaks".} + \item{agency_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} \item{agency_name}{The name of the agency that is reporting the data.} diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index fd1ae7eb2..83b184eab 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -176,11 +176,13 @@ multi_site2 <- read_waterdata_continuous(monitoring_location_id = c("USGS-45160 parameter_code = c("00060", "72019"), last_modified = "P7D") -dane <- read_waterdata_continuous(monitoring_location_arguments = list( - state_name = "Wisconsin", - county_name = "Dane County"), - parameter_code = "00060", - time = "P1D") +dane <- read_waterdata_continuous( + monitoring_location_arguments = list( + state_name = "Wisconsin", + county_name = "Dane County" + ), + parameter_code = "00060", + time = "P1D") # how to split up request into roughly 3 year chunks diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index 95271b34f..e07b9a992 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -24,6 +24,8 @@ read_waterdata_field_measurements( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments(service = + "field-measurements"), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -118,6 +120,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} +\item{monitoring_location_arguments}{A list of arguments that can be queried, +but are not returned. These are used as alternatives to specifying specific +monitoring_location_ids.} + \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} @@ -206,7 +212,18 @@ surface_water <- read_waterdata_field_measurements( time = "2024-07-01T00:00:00Z/..", parameter_code = "00060") +dane <- read_waterdata_field_measurements( + monitoring_location_arguments = list( + state_name = "Wisconsin", + county_name = "Dane County" + ), + parameter_code = "00060", + time = "P30D") + } \dontshow{\}) # examplesIf} } +\seealso{ +\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +} diff --git a/man/read_waterdata_latest_continuous.Rd b/man/read_waterdata_latest_continuous.Rd index 5af72c3f8..dbeea2957 100644 --- a/man/read_waterdata_latest_continuous.Rd +++ b/man/read_waterdata_latest_continuous.Rd @@ -17,6 +17,8 @@ read_waterdata_latest_continuous( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments(service = + "latest-continuous"), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -90,6 +92,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} +\item{monitoring_location_arguments}{A list of arguments that can be queried, +but are not returned. These are used as alternatives to specifying specific +monitoring_location_ids.} + \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} @@ -173,6 +179,17 @@ multi_site2 <- read_waterdata_latest_continuous(monitoring_location_id = c("USG parameter_code = c("00060", "72019"), last_modified = "P7D") +dane <- read_waterdata_latest_continuous( + monitoring_location_arguments = list( + state_name = "Wisconsin", + county_name = "Dane County" + ), + parameter_code = "00060", + time = "P1D") + } \dontshow{\}) # examplesIf} } +\seealso{ +\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +} diff --git a/man/read_waterdata_latest_daily.Rd b/man/read_waterdata_latest_daily.Rd index 3989eb396..a535c5ba4 100644 --- a/man/read_waterdata_latest_daily.Rd +++ b/man/read_waterdata_latest_daily.Rd @@ -18,6 +18,8 @@ read_waterdata_latest_daily( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments(service = + "latest-daily"), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -95,6 +97,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} +\item{monitoring_location_arguments}{A list of arguments that can be queried, +but are not returned. These are used as alternatives to specifying specific +monitoring_location_ids.} + \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} @@ -171,6 +177,17 @@ multi_site <- read_waterdata_latest_daily(monitoring_location_id = c("USGS-0149 "USGS-01645000"), parameter_code = c("00060", "00010")) +dane <- read_waterdata_latest_daily( + monitoring_location_arguments = list( + state_name = "Wisconsin", + county_name = "Dane County" + ), + parameter_code = "00060", + time = "P7D") + } \dontshow{\}) # examplesIf} } +\seealso{ +\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +} diff --git a/man/read_waterdata_peaks.Rd b/man/read_waterdata_peaks.Rd index 260b36548..a69bb681c 100644 --- a/man/read_waterdata_peaks.Rd +++ b/man/read_waterdata_peaks.Rd @@ -22,6 +22,7 @@ read_waterdata_peaks( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments(service = "peaks"), ..., allow_incomplete_dates = FALSE, convertType = getOption("dataRetrieval.convertType"), @@ -104,6 +105,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} +\item{monitoring_location_arguments}{A list of arguments that can be queried, +but are not returned. These are used as alternatives to specifying specific +monitoring_location_ids.} + \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} @@ -176,6 +181,13 @@ dv_data_sf <- read_waterdata_peaks( monitoring_location_id = wi_peaks$monitoring_location_id[1], parameter_code = "00060") +dane <- read_waterdata_peaks( + monitoring_location_arguments = list( + state_name = "Wisconsin", + county_name = "Dane County" + ), + parameter_code = "00060") + incomplete_dates_not_allowed <- read_waterdata_peaks( monitoring_location_id = "USGS-06334330", parameter_code = "00060") @@ -189,3 +201,6 @@ incomplete_dates_allowed$time } \dontshow{\}) # examplesIf} } +\seealso{ +\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +} From 042903851cba16c770171ce8dc8d237bb629e475 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 8 Jul 2026 15:38:05 -0500 Subject: [PATCH 39/71] pkgdown --- _pkgdown.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_pkgdown.yml b/_pkgdown.yml index dacf3d73e..d67dbae8b 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -79,7 +79,7 @@ reference: - read_waterdata_monitoring_location - read_waterdata_latest_continuous - read_waterdata_latest_daily - - read_waterdata_latest_field + - read_waterdata_latest_field_measurements - read_waterdata_field_measurements - read_waterdata_parameter_codes - read_waterdata_metadata From 600ef57f8f727399201a2670d6513c56460ad80c Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 8 Jul 2026 16:11:21 -0500 Subject: [PATCH 40/71] adding q --- R/read_waterdata_monitoring_location.R | 20 ++++++++++++++++++ _pkgdown.yml | 1 + man/read_waterdata_monitoring_location.Rd | 25 +++++++++++++++++++++++ 3 files changed, 46 insertions(+) diff --git a/R/read_waterdata_monitoring_location.R b/R/read_waterdata_monitoring_location.R index 8561f98a8..983591836 100644 --- a/R/read_waterdata_monitoring_location.R +++ b/R/read_waterdata_monitoring_location.R @@ -44,10 +44,25 @@ #' @param well_constructed_depth `r get_ogc_params("monitoring-locations")$well_constructed_depth` #' @param hole_constructed_depth `r get_ogc_params("monitoring-locations")$hole_constructed_depth` #' @param depth_source_code `r get_ogc_params("monitoring-locations")$depth_source_code` +#' @param revision_note `r get_ogc_params("monitoring-locations")$revision_note` +#' @param revision_created `r get_ogc_params("monitoring-locations")$revision_created` +#' @param revision_modified `r get_ogc_params("monitoring-locations")$revision_modified` #' @param properties A vector of requested columns to be returned from the query. #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("monitoring-locations", "monitoring_location_id")`. #' The default (`NA`) will return all columns of the data. +#' @param q Full-text search across the most relevant text fields for this collection +#' (e.g. site name, identifier, number, state, county, and site type). +#' Matching rules: +#' - Case-insensitive, with prefix matching (e.g. poud matches POUDRE). +#' - Words separated by spaces are AND'd together (all must match). +#' - Terms separated by commas are OR'd together (any may match). +#' - Common abbreviations are expanded, so river also matches sites stored as RV (and vice versa). +#' Examples are: +#' q=poudre - sites whose name/identifier starts with or contains poudre +#' q=colorado river - sites matching both colorado and river/rv +#' q=poudre,cache creek - sites matching poudre OR (cache AND creek/ck) +#' #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @examplesIf is_dataRetrieval_user() @@ -80,6 +95,7 @@ #' bbox_vals = c(-94.00, 35.0, -93.5, 35.5) #' multi_site <- read_waterdata_monitoring_location(bbox = bbox_vals) #' +#' poudre <- read_waterdata_monitoring_location(q = "poudre") #' #' } read_waterdata_monitoring_location <- function( @@ -123,7 +139,11 @@ read_waterdata_monitoring_location <- function( well_constructed_depth = NA_character_, hole_constructed_depth = NA_character_, depth_source_code = NA_character_, + revision_note = NA_character_, + revision_created = NA_character_, + revision_modified = NA_character_, properties = NA_character_, + q = NA_character_, bbox = NA, skipGeometry = NA, ..., diff --git a/_pkgdown.yml b/_pkgdown.yml index d67dbae8b..a95d78a12 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -91,6 +91,7 @@ reference: - read_waterdata_peaks - summarize_waterdata_samples - check_waterdata_sample_params + - make_monitoring_location_arguments - title: National Water Information System (NWIS) desc: Functions to retrieve (USGS) NWIS data. These will be slowly phased out and replaced with the read_waterdata family of functions. contents: diff --git a/man/read_waterdata_monitoring_location.Rd b/man/read_waterdata_monitoring_location.Rd index be42815ce..e9c20e686 100644 --- a/man/read_waterdata_monitoring_location.Rd +++ b/man/read_waterdata_monitoring_location.Rd @@ -45,7 +45,11 @@ read_waterdata_monitoring_location( well_constructed_depth = NA_character_, hole_constructed_depth = NA_character_, depth_source_code = NA_character_, + revision_note = NA_character_, + revision_created = NA_character_, + revision_modified = NA_character_, properties = NA_character_, + q = NA_character_, bbox = NA, skipGeometry = NA, ..., @@ -138,11 +142,31 @@ Multiple monitoring_location_ids can be requested as a character vector.} \item{depth_source_code}{A code indicating the source of water-level data.} +\item{revision_note}{Approved water data are considered published record, but on occasion changes or deletions (revisions) must be made to data after they are approved. Data revisions are rare because of USGS quality assurance practices, including documentation of all data before they are officially approved. This field contains text explanations for data revisions at this monitoring location. Changes to data also are indicated with revision qualifier codes alongside the data. Text explanations before 2017 are not necessarily available online, but can be requested.} + +\item{revision_created}{The date a revision statement was created.} + +\item{revision_modified}{The most recent date a revision statement was modified.} + \item{properties}{A vector of requested columns to be returned from the query. Available options are: geometry, monitoring_location_id, agency_code, agency_name, monitoring_location_number, monitoring_location_name, district_code, country_code, country_name, state_code, state_name, county_code, county_name, minor_civil_division_code, site_type_code, site_type, hydrologic_unit_code, basin_code, altitude, altitude_accuracy, altitude_method_code, altitude_method_name, vertical_datum, vertical_datum_name, horizontal_positional_accuracy_code, horizontal_positional_accuracy, horizontal_position_method_code, horizontal_position_method_name, original_horizontal_datum, original_horizontal_datum_name, drainage_area, contributing_drainage_area, time_zone_abbreviation, uses_daylight_savings, construction_date, aquifer_code, national_aquifer_code, aquifer_type_code, well_constructed_depth, hole_constructed_depth, depth_source_code, revision_note, revision_created, revision_modified. The default (\code{NA}) will return all columns of the data.} +\item{q}{Full-text search across the most relevant text fields for this collection +(e.g. site name, identifier, number, state, county, and site type). +Matching rules: +\itemize{ +\item Case-insensitive, with prefix matching (e.g. poud matches POUDRE). +\item Words separated by spaces are AND'd together (all must match). +\item Terms separated by commas are OR'd together (any may match). +\item Common abbreviations are expanded, so river also matches sites stored as RV (and vice versa). +Examples are: +q=poudre - sites whose name/identifier starts with or contains poudre +q=colorado river - sites matching both colorado and river/rv +q=poudre,cache creek - sites matching poudre OR (cache AND creek/ck) +}} + \item{bbox}{Only features that have a geometry that intersects the bounding box are selected.The bounding box is provided as four or six numbers, depending on whether the coordinate reference system includes a vertical axis (height or @@ -215,6 +239,7 @@ site_info_no_sf <- read_waterdata_monitoring_location( bbox_vals = c(-94.00, 35.0, -93.5, 35.5) multi_site <- read_waterdata_monitoring_location(bbox = bbox_vals) +poudre <- read_waterdata_monitoring_location(q = "poudre") } \dontshow{\}) # examplesIf} From 717d7ea515e4ce2ab9fd8826226bdbd5bfcdf8d7 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 8 Jul 2026 16:26:43 -0500 Subject: [PATCH 41/71] bring these back someday --- tests/testthat/tests_userFriendly_fxns.R | 77 ++++++++++++------------ 1 file changed, 38 insertions(+), 39 deletions(-) diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index b59e8fbd9..23215ed97 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -272,45 +272,44 @@ test_that("read_waterdata_daily", { # "ICE, REGULATED, UNKNOWNREGULATION")) }) -test_that("WQP qw tests", { - testthat::skip_on_cran() - skip_on_ci() - # nameToUse <- "Specific conductance" - # pcodeToUse <- "00095" - # - # INFO_WQP <- readWQPqw( - # "USGS-04024315", - # pcodeToUse, - # startDate = "", - # endDate = "", - # legacy = FALSE - # ) - # expect_is(INFO_WQP$Activity_StartDateTime, "POSIXct") - # - # INFO2 <- readWQPqw( - # "WIDNR_WQX-10032762", - # nameToUse, - # startDate = "", - # endDate = "", - # legacy = FALSE - # ) - # expect_is(INFO2$Activity_StartDateTime, "POSIXct") - # - # df <- readWQPqw("USGS-04193500", parameterCd = "00665", legacy = FALSE) - # expect_true(nrow(df) > 0) - # - # df2 <- readWQPqw("USGS-05427718", parameterCd = "all") - # expect_true(nrow(df2) > 0) - # - # #Empty legacy: - # df3 <- readWQPqw( - # siteNumbers = "USGS-385032115220501", - # parameterCd = "all", - # legacy = TRUE - # ) - # expect_true(nrow(df3) == 0) -}) - +# test_that("WQP qw tests", { +# testthat::skip_on_cran() +# skip_on_ci() +# nameToUse <- "Specific conductance" +# pcodeToUse <- "00095" +# +# INFO_WQP <- readWQPqw( +# "USGS-04024315", +# pcodeToUse, +# startDate = "", +# endDate = "", +# legacy = FALSE +# ) +# expect_is(INFO_WQP$Activity_StartDateTime, "POSIXct") +# +# INFO2 <- readWQPqw( +# "WIDNR_WQX-10032762", +# nameToUse, +# startDate = "", +# endDate = "", +# legacy = FALSE +# ) +# expect_is(INFO2$Activity_StartDateTime, "POSIXct") +# +# df <- readWQPqw("USGS-04193500", parameterCd = "00665", legacy = FALSE) +# expect_true(nrow(df) > 0) +# +# df2 <- readWQPqw("USGS-05427718", parameterCd = "all") +# expect_true(nrow(df2) > 0) +# +# #Empty legacy: +# df3 <- readWQPqw( +# siteNumbers = "USGS-385032115220501", +# parameterCd = "all", +# legacy = TRUE +# ) +# expect_true(nrow(df3) == 0) +# }) context("state tests") test_that("state county tests", { From c0577a1296cb76f45af046a90fcd431f030994bf Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 8 Jul 2026 16:50:14 -0500 Subject: [PATCH 42/71] update docs --- R/check_non_returned.R | 11 +++++++-- R/read_waterdata_continuous.R | 3 ++- R/read_waterdata_daily.R | 3 ++- R/read_waterdata_field_measurements.R | 3 ++- R/read_waterdata_latest_continuous.R | 3 ++- R/read_waterdata_latest_daily.R | 3 ++- R/read_waterdata_latest_field.R | 24 ++++++++++++++++++- R/read_waterdata_peaks.R | 3 ++- man/make_monitoring_location_arguments.Rd | 11 ++++++--- man/read_waterdata_continuous.Rd | 3 ++- man/read_waterdata_daily.Rd | 3 ++- man/read_waterdata_field_measurements.Rd | 3 ++- man/read_waterdata_latest_continuous.Rd | 3 ++- man/read_waterdata_latest_daily.Rd | 3 ++- ...ead_waterdata_latest_field_measurements.Rd | 19 ++++++++++++++- man/read_waterdata_peaks.Rd | 3 ++- 16 files changed, 82 insertions(+), 19 deletions(-) diff --git a/R/check_non_returned.R b/R/check_non_returned.R index 32e4c0895..cd41f85c2 100644 --- a/R/check_non_returned.R +++ b/R/check_non_returned.R @@ -1,4 +1,11 @@ -#' Check for arguments that can be queried but not returned +#' Get Monitoring Location Arguments +#' +#' Many read_waterdata functions have a long list of arguments that can be used +#' to find sites that have data. Users can use this function to create a list +#' of possible arguments that can be used as input to the `monitoring_location_arguments` +#' argument (found in many of the read_waterdata functions). This function +#' also is used to check that user supplied available parameters to their queries +#' when using the `monitoring_location_arguments` argument. #' #' @param service Endpoint to check arguments against. Possible values are #' "daily", "latest-continuous", "field-measurements", "latest-daily", @@ -45,7 +52,7 @@ #' @param data_gap_interval `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$data_gap_interval$description` #' @param \dots Not used. Used to make sure the user isn't passing in arguments that aren't available. #' @param check_arguments Logical. Used to decide if the arguments passed in are available or not. The -#' default is `FALSE`. Using `TRUE` will make two calls to the API, so if you are concerted +#' default is `FALSE`. Using `TRUE` will make two calls to the API, so if you are concerned #' with minimizing API calls, keep this value as `FALSE`. If you are concerned with #' making sure your calls are accepted by the service, set to `TRUE`. #' @export diff --git a/R/read_waterdata_continuous.R b/R/read_waterdata_continuous.R index 842aa1183..ba9aefaaa 100644 --- a/R/read_waterdata_continuous.R +++ b/R/read_waterdata_continuous.R @@ -33,7 +33,8 @@ #' The default (`NA`) will return all columns of the data. #' @param monitoring_location_arguments A list of arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. +#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "continuous")` +#' to get a list of all possible arguments available in this list. #' @seealso [make_monitoring_location_arguments()] #' @inheritParams check_arguments_non_api #' @inheritParams check_arguments_api diff --git a/R/read_waterdata_daily.R b/R/read_waterdata_daily.R index 6d918268a..2e9dde692 100644 --- a/R/read_waterdata_daily.R +++ b/R/read_waterdata_daily.R @@ -27,7 +27,8 @@ #' The default (`NA`) will return all columns of the data. #' @param monitoring_location_arguments A list of arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. +#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "daily")` +#' to get a list of all possible arguments available in this list. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] diff --git a/R/read_waterdata_field_measurements.R b/R/read_waterdata_field_measurements.R index 99a458632..8db1a9f3f 100644 --- a/R/read_waterdata_field_measurements.R +++ b/R/read_waterdata_field_measurements.R @@ -39,7 +39,8 @@ #' The default (`NA`) will return all columns of the data. #' @param monitoring_location_arguments A list of arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. +#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "field-measurements")` +#' to get a list of all possible arguments available in this list. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] diff --git a/R/read_waterdata_latest_continuous.R b/R/read_waterdata_latest_continuous.R index f3575dc5c..2678cac1f 100644 --- a/R/read_waterdata_latest_continuous.R +++ b/R/read_waterdata_latest_continuous.R @@ -25,7 +25,8 @@ #' The default (`NA`) will return all columns of the data. #' @param monitoring_location_arguments A list of arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. +#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "latest-continuous")` +#' to get a list of all possible arguments available in this list. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] diff --git a/R/read_waterdata_latest_daily.R b/R/read_waterdata_latest_daily.R index 6c67904bd..f27fbe6e2 100644 --- a/R/read_waterdata_latest_daily.R +++ b/R/read_waterdata_latest_daily.R @@ -27,7 +27,8 @@ #' The default (`NA`) will return all columns of the data. #' @param monitoring_location_arguments A list of arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. +#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "latest-daily")` +#' to get a list of all possible arguments available in this list. #' #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api diff --git a/R/read_waterdata_latest_field.R b/R/read_waterdata_latest_field.R index f7a1dcf28..a27300561 100644 --- a/R/read_waterdata_latest_field.R +++ b/R/read_waterdata_latest_field.R @@ -1,4 +1,4 @@ -#' Get latest USGS field measurement data +#' Get Latest USGS Field Measurement Data #' #' @description `r get_description("latest-field-measurements")` #' @@ -25,9 +25,14 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("latest-field-measurements", "latest_field_id")`. #' The default (`NA`) will return all columns of the data. +#' @param monitoring_location_arguments A list of arguments that can be queried, +#' but are not returned. These are used as alternatives to specifying specific +#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "latest-field-measurements")` +#' to get a list of all possible arguments available in this list. #' #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api +#' @seealso [make_monitoring_location_arguments()] #' @inherit read_waterdata_continuous details #' #' @examplesIf is_dataRetrieval_user() @@ -48,6 +53,13 @@ #' multi_site <- read_waterdata_latest_field_measurements(monitoring_location_id = c("USGS-01435000", #' "USGS-14202650")) #' +#' dane <- read_waterdata_latest_field_measurements( +#' monitoring_location_arguments = list( +#' state_name = "Wisconsin", +#' county_name = "Dane County" +#' ), +#' time = "P30D") +#' #' } read_waterdata_latest_field_measurements <- function( monitoring_location_id = NA_character_, @@ -63,6 +75,9 @@ read_waterdata_latest_field_measurements <- function( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments( + service = "latest-field-measurements" + ), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -75,6 +90,13 @@ read_waterdata_latest_field_measurements <- function( rlang::check_dots_empty() args <- mget(names(formals())) + + args <- cleanup_arguments( + args = args, + monitoring_location_arguments = monitoring_location_arguments, + service = service + ) + return_list <- get_ogc_data(args, output_id, service) return(return_list) diff --git a/R/read_waterdata_peaks.R b/R/read_waterdata_peaks.R index d49cf9f91..d3d0ccf3c 100644 --- a/R/read_waterdata_peaks.R +++ b/R/read_waterdata_peaks.R @@ -38,7 +38,8 @@ #' month stored on January 1. Default is `FALSE`. #' @param monitoring_location_arguments A list of arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. +#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "peaks")` +#' to get a list of all possible arguments available in this list. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] diff --git a/man/make_monitoring_location_arguments.Rd b/man/make_monitoring_location_arguments.Rd index ebe061f2e..af08765ec 100644 --- a/man/make_monitoring_location_arguments.Rd +++ b/man/make_monitoring_location_arguments.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/check_non_returned.R \name{make_monitoring_location_arguments} \alias{make_monitoring_location_arguments} -\title{Check for arguments that can be queried but not returned} +\title{Get Monitoring Location Arguments} \usage{ make_monitoring_location_arguments( service = c("daily"), @@ -138,12 +138,17 @@ make_monitoring_location_arguments( \item{\dots}{Not used. Used to make sure the user isn't passing in arguments that aren't available.} \item{check_arguments}{Logical. Used to decide if the arguments passed in are available or not. The -default is \code{FALSE}. Using \code{TRUE} will make two calls to the API, so if you are concerted +default is \code{FALSE}. Using \code{TRUE} will make two calls to the API, so if you are concerned with minimizing API calls, keep this value as \code{FALSE}. If you are concerned with making sure your calls are accepted by the service, set to \code{TRUE}.} } \description{ -Check for arguments that can be queried but not returned +Many read_waterdata functions have a long list of arguments that can be used +to find sites that have data. Users can use this function to create a list +of possible arguments that can be used as input to the \code{monitoring_location_arguments} +argument (found in many of the read_waterdata functions). This function +also is used to check that user supplied available parameters to their queries +when using the \code{monitoring_location_arguments} argument. } \examples{ diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index 83b184eab..85d774bba 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -94,7 +94,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{monitoring_location_arguments}{A list of arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids.} +monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "continuous")} +to get a list of all possible arguments available in this list.} \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} diff --git a/man/read_waterdata_daily.Rd b/man/read_waterdata_daily.Rd index 051fe248a..c28c775c3 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -98,7 +98,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{monitoring_location_arguments}{A list of arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids.} +monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "daily")} +to get a list of all possible arguments available in this list.} \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index e07b9a992..9beb5099d 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -122,7 +122,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{monitoring_location_arguments}{A list of arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids.} +monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "field-measurements")} +to get a list of all possible arguments available in this list.} \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} diff --git a/man/read_waterdata_latest_continuous.Rd b/man/read_waterdata_latest_continuous.Rd index dbeea2957..9de7f1a6a 100644 --- a/man/read_waterdata_latest_continuous.Rd +++ b/man/read_waterdata_latest_continuous.Rd @@ -94,7 +94,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{monitoring_location_arguments}{A list of arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids.} +monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-continuous")} +to get a list of all possible arguments available in this list.} \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} diff --git a/man/read_waterdata_latest_daily.Rd b/man/read_waterdata_latest_daily.Rd index a535c5ba4..0c443fb55 100644 --- a/man/read_waterdata_latest_daily.Rd +++ b/man/read_waterdata_latest_daily.Rd @@ -99,7 +99,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{monitoring_location_arguments}{A list of arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids.} +monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-daily")} +to get a list of all possible arguments available in this list.} \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} diff --git a/man/read_waterdata_latest_field_measurements.Rd b/man/read_waterdata_latest_field_measurements.Rd index 3303acfe5..c0cdd0793 100644 --- a/man/read_waterdata_latest_field_measurements.Rd +++ b/man/read_waterdata_latest_field_measurements.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/read_waterdata_latest_field.R \name{read_waterdata_latest_field_measurements} \alias{read_waterdata_latest_field_measurements} -\title{Get latest USGS field measurement data} +\title{Get Latest USGS Field Measurement Data} \usage{ read_waterdata_latest_field_measurements( monitoring_location_id = NA_character_, @@ -18,6 +18,8 @@ read_waterdata_latest_field_measurements( skipGeometry = NA, time = NA_character_, bbox = NA, + monitoring_location_arguments = make_monitoring_location_arguments(service = + "latest-field-measurements"), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -91,6 +93,11 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} +\item{monitoring_location_arguments}{A list of arguments that can be queried, +but are not returned. These are used as alternatives to specifying specific +monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-field-measurements")} +to get a list of all possible arguments available in this list.} + \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} @@ -159,6 +166,16 @@ field_data <- read_waterdata_latest_field_measurements(monitoring_location_id = multi_site <- read_waterdata_latest_field_measurements(monitoring_location_id = c("USGS-01435000", "USGS-14202650")) +dane <- read_waterdata_latest_field_measurements( + monitoring_location_arguments = list( + state_name = "Wisconsin", + county_name = "Dane County" + ), + time = "P30D") + } \dontshow{\}) # examplesIf} } +\seealso{ +\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +} diff --git a/man/read_waterdata_peaks.Rd b/man/read_waterdata_peaks.Rd index a69bb681c..20258e916 100644 --- a/man/read_waterdata_peaks.Rd +++ b/man/read_waterdata_peaks.Rd @@ -107,7 +107,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{monitoring_location_arguments}{A list of arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids.} +monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "peaks")} +to get a list of all possible arguments available in this list.} \item{...}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} From fd5292178cefad514025d0bc02e2be6dae715e58 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 9 Jul 2026 10:47:15 -0500 Subject: [PATCH 43/71] Change to dots --- R/get_ogc_data.R | 5 +---- ....R => make_monitoring_location_arguments.R} | 4 ++-- R/read_waterdata_channel.R | 2 ++ R/read_waterdata_combined_meta.R | 2 ++ R/read_waterdata_continuous.R | 2 ++ R/read_waterdata_daily.R | 18 +++++++----------- R/read_waterdata_field_measurements.R | 2 ++ R/read_waterdata_field_meta.R | 2 ++ R/read_waterdata_latest_continuous.R | 2 ++ R/read_waterdata_latest_daily.R | 3 ++- R/read_waterdata_peaks.R | 2 ++ R/read_waterdata_ts_meta.R | 2 ++ man/check_arguments_non_api.Rd | 6 +----- man/make_monitoring_location_arguments.Rd | 4 ++-- man/read_ngwmn_lithology.Rd | 3 --- man/read_ngwmn_providers.Rd | 3 --- man/read_ngwmn_sites.Rd | 3 --- man/read_ngwmn_water_level.Rd | 3 --- man/read_ngwmn_well_construction.Rd | 3 --- man/read_waterdata_channel.Rd | 2 +- man/read_waterdata_combined_meta.Rd | 2 +- man/read_waterdata_continuous.Rd | 2 +- man/read_waterdata_daily.Rd | 15 +++++---------- man/read_waterdata_field_measurements.Rd | 2 +- man/read_waterdata_field_meta.Rd | 2 +- man/read_waterdata_latest_continuous.Rd | 2 +- man/read_waterdata_latest_daily.Rd | 2 +- ...read_waterdata_latest_field_measurements.Rd | 3 --- man/read_waterdata_monitoring_location.Rd | 3 --- man/read_waterdata_peaks.Rd | 2 +- man/read_waterdata_ts_meta.Rd | 2 +- 31 files changed, 45 insertions(+), 65 deletions(-) rename R/{check_non_returned.R => make_monitoring_location_arguments.R} (99%) diff --git a/R/get_ogc_data.R b/R/get_ogc_data.R index 4b6952b47..87be4141e 100644 --- a/R/get_ogc_data.R +++ b/R/get_ogc_data.R @@ -218,16 +218,13 @@ switch_properties_id <- function(properties, id) { #' the default for time series functions is #' `r getOption("dataRetrieval.site_chunk_size_data")`. #' Setting to `NA` will eliminate site chunking, giving users full control. -#' @param \dots Not used. Included to help differentiate official Water Data API arguments -#' from more seldom used, optional dataRetrieval-specific arguments. #' @keywords internal check_arguments_non_api <- function( convertType, no_paging, limit, attach_request, - chunk_size, - ... + chunk_size ) { check_logical(convertType, "convertType") check_logical(no_paging, "no_paging") diff --git a/R/check_non_returned.R b/R/make_monitoring_location_arguments.R similarity index 99% rename from R/check_non_returned.R rename to R/make_monitoring_location_arguments.R index cd41f85c2..769163c8b 100644 --- a/R/check_non_returned.R +++ b/R/make_monitoring_location_arguments.R @@ -62,7 +62,7 @@ #' make_monitoring_location_arguments(service = "field-measurements", #' state_name = c("Ohio", "Wisconsin")) make_monitoring_location_arguments <- function( - service = c("daily"), + service = "daily", agency_code = NA_character_, agency_name = NA_character_, monitoring_location_number = NA_character_, @@ -165,7 +165,7 @@ cleanup_arguments <- function(args, monitoring_location_arguments, service) { ) args[["monitoring_location_arguments"]] <- NULL - + args[["..."]] <- NULL args <- c(args, query_args) return(args) diff --git a/R/read_waterdata_channel.R b/R/read_waterdata_channel.R index 74e92840c..74fbdb9d1 100644 --- a/R/read_waterdata_channel.R +++ b/R/read_waterdata_channel.R @@ -34,6 +34,8 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("channel-measurements", "channel_measurements_id")`. #' The default (`NA`) will return all columns of the data. +#' @param \dots Not used. Included to help differentiate official Water Data API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' diff --git a/R/read_waterdata_combined_meta.R b/R/read_waterdata_combined_meta.R index de173e1db..b84e76b8a 100644 --- a/R/read_waterdata_combined_meta.R +++ b/R/read_waterdata_combined_meta.R @@ -82,6 +82,8 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("combined-metadata", "field_measurement_id")`. #' The default (`NA`) will return all columns of the data. +#' @param \dots Not used. Included to help differentiate official Water Data API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @inherit read_waterdata_continuous details diff --git a/R/read_waterdata_continuous.R b/R/read_waterdata_continuous.R index ba9aefaaa..8a0a292c2 100644 --- a/R/read_waterdata_continuous.R +++ b/R/read_waterdata_continuous.R @@ -35,6 +35,8 @@ #' but are not returned. These are used as alternatives to specifying specific #' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "continuous")` #' to get a list of all possible arguments available in this list. +#' @param \dots Not used. Included to help differentiate official Water Data API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @seealso [make_monitoring_location_arguments()] #' @inheritParams check_arguments_non_api #' @inheritParams check_arguments_api diff --git a/R/read_waterdata_daily.R b/R/read_waterdata_daily.R index 2e9dde692..88b48a443 100644 --- a/R/read_waterdata_daily.R +++ b/R/read_waterdata_daily.R @@ -25,10 +25,10 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("daily", "daily_id")`. #' The default (`NA`) will return all columns of the data. -#' @param monitoring_location_arguments A list of arguments that can be queried, +#' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "daily")` -#' to get a list of all possible arguments available in this list. +#' monitoring_location_ids. See `make_monitoring_location_arguments()` +#' to get a list of all possible arguments available. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] @@ -77,9 +77,8 @@ #' parameter_code = "00060", #' time = c("2021-01-01", "2022-01-01")) #' -#' dv_dane <- read_waterdata_daily(monitoring_location_arguments = list( -#' state_name = "Wisconsin", -#' county_name = "Dane County"), +#' dv_dane <- read_waterdata_daily(state_name = "Wisconsin", +#' county_name = "Dane County", #' parameter_code = "00060", #' time = "P7D") #' @@ -98,9 +97,6 @@ read_waterdata_daily <- function( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments( - service = "daily" - ), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -110,12 +106,12 @@ read_waterdata_daily <- function( ) { service <- "daily" output_id <- "daily_id" - rlang::check_dots_empty() + args <- mget(names(formals())) args <- cleanup_arguments( args = args, - monitoring_location_arguments = monitoring_location_arguments, + monitoring_location_arguments = list(...), service = service ) diff --git a/R/read_waterdata_field_measurements.R b/R/read_waterdata_field_measurements.R index 8db1a9f3f..a9d8b1bd8 100644 --- a/R/read_waterdata_field_measurements.R +++ b/R/read_waterdata_field_measurements.R @@ -41,6 +41,8 @@ #' but are not returned. These are used as alternatives to specifying specific #' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "field-measurements")` #' to get a list of all possible arguments available in this list. +#' @param \dots Not used. Included to help differentiate official Water Data API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] diff --git a/R/read_waterdata_field_meta.R b/R/read_waterdata_field_meta.R index b45df0154..b499c5fbb 100644 --- a/R/read_waterdata_field_meta.R +++ b/R/read_waterdata_field_meta.R @@ -24,6 +24,8 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("field-measurements-metadata", "field_measurement_id")`. #' The default (`NA`) will return all columns of the data. +#' @param \dots Not used. Included to help differentiate official Water Data API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api diff --git a/R/read_waterdata_latest_continuous.R b/R/read_waterdata_latest_continuous.R index 2678cac1f..ca3499b92 100644 --- a/R/read_waterdata_latest_continuous.R +++ b/R/read_waterdata_latest_continuous.R @@ -27,6 +27,8 @@ #' but are not returned. These are used as alternatives to specifying specific #' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "latest-continuous")` #' to get a list of all possible arguments available in this list. +#' @param \dots Not used. Included to help differentiate official Water Data API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] diff --git a/R/read_waterdata_latest_daily.R b/R/read_waterdata_latest_daily.R index f27fbe6e2..b1236d8bc 100644 --- a/R/read_waterdata_latest_daily.R +++ b/R/read_waterdata_latest_daily.R @@ -29,7 +29,8 @@ #' but are not returned. These are used as alternatives to specifying specific #' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "latest-daily")` #' to get a list of all possible arguments available in this list. -#' +#' @param \dots Not used. Included to help differentiate official Water Data API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] diff --git a/R/read_waterdata_peaks.R b/R/read_waterdata_peaks.R index d3d0ccf3c..6caef0e03 100644 --- a/R/read_waterdata_peaks.R +++ b/R/read_waterdata_peaks.R @@ -40,6 +40,8 @@ #' but are not returned. These are used as alternatives to specifying specific #' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "peaks")` #' to get a list of all possible arguments available in this list. +#' @param \dots Not used. Included to help differentiate official Water Data API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] diff --git a/R/read_waterdata_ts_meta.R b/R/read_waterdata_ts_meta.R index b3f869dec..0b06a704f 100644 --- a/R/read_waterdata_ts_meta.R +++ b/R/read_waterdata_ts_meta.R @@ -45,6 +45,8 @@ #' `r dataRetrieval:::get_properties_for_docs("time-series-metadata", "time_series_id")`. #' The default (`NA`) will return all columns of the data. #' @param time_series_id `r get_ogc_params("time-series-metadata")$id` +#' @param \dots Not used. Included to help differentiate official Water Data API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' diff --git a/man/check_arguments_non_api.Rd b/man/check_arguments_non_api.Rd index 193ab821a..bf59ebb93 100644 --- a/man/check_arguments_non_api.Rd +++ b/man/check_arguments_non_api.Rd @@ -9,8 +9,7 @@ check_arguments_non_api( no_paging, limit, attach_request, - chunk_size, - ... + chunk_size ) } \arguments{ @@ -40,9 +39,6 @@ is 250, while the default for time series functions is 10. Setting to \code{NA} will eliminate site chunking, giving users full control.} - -\item{\dots}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} } \description{ Function to check types and create parameter descriptions. diff --git a/man/make_monitoring_location_arguments.Rd b/man/make_monitoring_location_arguments.Rd index af08765ec..802efdda2 100644 --- a/man/make_monitoring_location_arguments.Rd +++ b/man/make_monitoring_location_arguments.Rd @@ -1,11 +1,11 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/check_non_returned.R +% Please edit documentation in R/make_monitoring_location_arguments.R \name{make_monitoring_location_arguments} \alias{make_monitoring_location_arguments} \title{Get Monitoring Location Arguments} \usage{ make_monitoring_location_arguments( - service = c("daily"), + service = "daily", agency_code = NA_character_, agency_name = NA_character_, monitoring_location_number = NA_character_, diff --git a/man/read_ngwmn_lithology.Rd b/man/read_ngwmn_lithology.Rd index b50588ba8..8b38cf12d 100644 --- a/man/read_ngwmn_lithology.Rd +++ b/man/read_ngwmn_lithology.Rd @@ -26,9 +26,6 @@ Available options are: agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, lithology_id, lithology_description, lithology_controlled_concept, lithology_depth_from, lithology_depth_to, lithology_depth_to_unit, lithology_depth_from_unit. The default (\code{NA}) will return all columns of the data.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} - \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} diff --git a/man/read_ngwmn_providers.Rd b/man/read_ngwmn_providers.Rd index 82bd71d79..6517f40a7 100644 --- a/man/read_ngwmn_providers.Rd +++ b/man/read_ngwmn_providers.Rd @@ -29,9 +29,6 @@ Available options are: agency_name, agency_code, organization_type, state, link. The default (\code{NA}) will return all columns of the data.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} - \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} diff --git a/man/read_ngwmn_sites.Rd b/man/read_ngwmn_sites.Rd index f291585ea..fc5191c8c 100644 --- a/man/read_ngwmn_sites.Rd +++ b/man/read_ngwmn_sites.Rd @@ -108,9 +108,6 @@ The default (\code{NA}) will return all columns of the data.} each feature. The returning object will be a data frame with no spatial information.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} - \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} diff --git a/man/read_ngwmn_water_level.Rd b/man/read_ngwmn_water_level.Rd index 949c0751b..16de6b493 100644 --- a/man/read_ngwmn_water_level.Rd +++ b/man/read_ngwmn_water_level.Rd @@ -65,9 +65,6 @@ Examples: Only features that have a \code{sample_time} that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} - \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} diff --git a/man/read_ngwmn_well_construction.Rd b/man/read_ngwmn_well_construction.Rd index 352e166ec..765446552 100644 --- a/man/read_ngwmn_well_construction.Rd +++ b/man/read_ngwmn_well_construction.Rd @@ -29,9 +29,6 @@ Available options are: agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, type, depth_from, depth_to, depth_from_unit, depth_to_unit, material, diameter, diameter_unit, hole_size, hole_size_unit. The default (\code{NA}) will return all columns of the data.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} - \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} diff --git a/man/read_waterdata_channel.Rd b/man/read_waterdata_channel.Rd index e9bee3b98..9f7e0c0ef 100644 --- a/man/read_waterdata_channel.Rd +++ b/man/read_waterdata_channel.Rd @@ -132,7 +132,7 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} -\item{...}{Not used. Included to help differentiate official Water Data API arguments +\item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} \item{convertType}{logical, defaults to TRUE. diff --git a/man/read_waterdata_combined_meta.Rd b/man/read_waterdata_combined_meta.Rd index f51477936..8f3f01002 100644 --- a/man/read_waterdata_combined_meta.Rd +++ b/man/read_waterdata_combined_meta.Rd @@ -252,7 +252,7 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} -\item{...}{Not used. Included to help differentiate official Water Data API arguments +\item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} \item{convertType}{logical, defaults to TRUE. diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index 85d774bba..b49c11453 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -97,7 +97,7 @@ but are not returned. These are used as alternatives to specifying specific monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "continuous")} to get a list of all possible arguments available in this list.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments +\item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} \item{convertType}{logical, defaults to TRUE. diff --git a/man/read_waterdata_daily.Rd b/man/read_waterdata_daily.Rd index c28c775c3..5ef5297a0 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -18,7 +18,6 @@ read_waterdata_daily( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments(service = "daily"), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -96,13 +95,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} -\item{monitoring_location_arguments}{A list of arguments that can be queried, +\item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "daily")} -to get a list of all possible arguments available in this list.} - -\item{...}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} +monitoring_location_ids. See \code{make_monitoring_location_arguments()} +to get a list of all possible arguments available.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -194,9 +190,8 @@ dv_data_no_request <- read_waterdata_daily(monitoring_location_id = site, parameter_code = "00060", time = c("2021-01-01", "2022-01-01")) -dv_dane <- read_waterdata_daily(monitoring_location_arguments = list( - state_name = "Wisconsin", - county_name = "Dane County"), +dv_dane <- read_waterdata_daily(state_name = "Wisconsin", + county_name = "Dane County", parameter_code = "00060", time = "P7D") diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index 9beb5099d..57462756c 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -125,7 +125,7 @@ but are not returned. These are used as alternatives to specifying specific monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "field-measurements")} to get a list of all possible arguments available in this list.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments +\item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} \item{convertType}{logical, defaults to TRUE. diff --git a/man/read_waterdata_field_meta.Rd b/man/read_waterdata_field_meta.Rd index 30bec39af..9047ae656 100644 --- a/man/read_waterdata_field_meta.Rd +++ b/man/read_waterdata_field_meta.Rd @@ -104,7 +104,7 @@ limit is 50,000. It may be beneficial to set this number lower if your internet connection is spotty. The default (\code{NA}) will set the limit to the maximum allowable limit for the service.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments +\item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} \item{convertType}{logical, defaults to TRUE. diff --git a/man/read_waterdata_latest_continuous.Rd b/man/read_waterdata_latest_continuous.Rd index 9de7f1a6a..1cf2db828 100644 --- a/man/read_waterdata_latest_continuous.Rd +++ b/man/read_waterdata_latest_continuous.Rd @@ -97,7 +97,7 @@ but are not returned. These are used as alternatives to specifying specific monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-continuous")} to get a list of all possible arguments available in this list.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments +\item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} \item{convertType}{logical, defaults to TRUE. diff --git a/man/read_waterdata_latest_daily.Rd b/man/read_waterdata_latest_daily.Rd index 0c443fb55..c83c8b8da 100644 --- a/man/read_waterdata_latest_daily.Rd +++ b/man/read_waterdata_latest_daily.Rd @@ -102,7 +102,7 @@ but are not returned. These are used as alternatives to specifying specific monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-daily")} to get a list of all possible arguments available in this list.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments +\item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} \item{convertType}{logical, defaults to TRUE. diff --git a/man/read_waterdata_latest_field_measurements.Rd b/man/read_waterdata_latest_field_measurements.Rd index c0cdd0793..b1c708cc6 100644 --- a/man/read_waterdata_latest_field_measurements.Rd +++ b/man/read_waterdata_latest_field_measurements.Rd @@ -98,9 +98,6 @@ but are not returned. These are used as alternatives to specifying specific monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-field-measurements")} to get a list of all possible arguments available in this list.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} - \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} diff --git a/man/read_waterdata_monitoring_location.Rd b/man/read_waterdata_monitoring_location.Rd index e9c20e686..cae5751b3 100644 --- a/man/read_waterdata_monitoring_location.Rd +++ b/man/read_waterdata_monitoring_location.Rd @@ -179,9 +179,6 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} each feature. The returning object will be a data frame with no spatial information. The default \code{NA} will not specify the argument in the request.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} - \item{limit}{numeric, The optional limit parameter is used to control the subset of the selected features that should be returned in each page. The maximum allowable limit is 50,000. It may be beneficial to set this number lower if your internet diff --git a/man/read_waterdata_peaks.Rd b/man/read_waterdata_peaks.Rd index 20258e916..3ef0022b0 100644 --- a/man/read_waterdata_peaks.Rd +++ b/man/read_waterdata_peaks.Rd @@ -110,7 +110,7 @@ but are not returned. These are used as alternatives to specifying specific monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "peaks")} to get a list of all possible arguments available in this list.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments +\item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} \item{allow_incomplete_dates}{Specifically in the peaks data, exact peak dates diff --git a/man/read_waterdata_ts_meta.Rd b/man/read_waterdata_ts_meta.Rd index dd4c80cb2..fd381a2fe 100644 --- a/man/read_waterdata_ts_meta.Rd +++ b/man/read_waterdata_ts_meta.Rd @@ -145,7 +145,7 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{end}{This field contains the same information as "end_utc", but in the local time of the monitoring location. It is retained for backwards compatibility, but will be removed in V1 of these APIs.} -\item{...}{Not used. Included to help differentiate official Water Data API arguments +\item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} \item{limit}{numeric, The optional limit parameter is used to control the subset of the From be7fa99edb58b5a55853b86e5db57e223bbf1a39 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 9 Jul 2026 10:56:33 -0500 Subject: [PATCH 44/71] dots --- R/read_waterdata_monitoring_location.R | 2 ++ man/read_waterdata_monitoring_location.Rd | 3 +++ 2 files changed, 5 insertions(+) diff --git a/R/read_waterdata_monitoring_location.R b/R/read_waterdata_monitoring_location.R index 983591836..898f891cb 100644 --- a/R/read_waterdata_monitoring_location.R +++ b/R/read_waterdata_monitoring_location.R @@ -51,6 +51,8 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("monitoring-locations", "monitoring_location_id")`. #' The default (`NA`) will return all columns of the data. +#' @param \dots Not used. Included to help differentiate official Water Data API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @param q Full-text search across the most relevant text fields for this collection #' (e.g. site name, identifier, number, state, county, and site type). #' Matching rules: diff --git a/man/read_waterdata_monitoring_location.Rd b/man/read_waterdata_monitoring_location.Rd index cae5751b3..ee2b32f76 100644 --- a/man/read_waterdata_monitoring_location.Rd +++ b/man/read_waterdata_monitoring_location.Rd @@ -179,6 +179,9 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} each feature. The returning object will be a data frame with no spatial information. The default \code{NA} will not specify the argument in the request.} +\item{\dots}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + \item{limit}{numeric, The optional limit parameter is used to control the subset of the selected features that should be returned in each page. The maximum allowable limit is 50,000. It may be beneficial to set this number lower if your internet From 79aec5302860b24f36a957df5e4ff951e22c2678 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 9 Jul 2026 11:09:07 -0500 Subject: [PATCH 45/71] Specific NGWMN dot --- R/read_ngwmn_lithology.R | 8 +++++--- R/read_ngwmn_providers.R | 2 ++ R/read_ngwmn_sites.R | 3 ++- R/read_ngwmn_water_level.R | 11 ++++++----- R/read_ngwmn_well_construction.R | 6 ++++-- R/read_waterdata_latest_field.R | 3 ++- man/read_ngwmn_lithology.Rd | 3 +++ man/read_ngwmn_providers.Rd | 3 +++ man/read_ngwmn_sites.Rd | 3 +++ man/read_ngwmn_water_level.Rd | 3 +++ man/read_ngwmn_well_construction.Rd | 3 +++ man/read_waterdata_latest_field_measurements.Rd | 3 +++ 12 files changed, 39 insertions(+), 12 deletions(-) diff --git a/R/read_ngwmn_lithology.R b/R/read_ngwmn_lithology.R index 032352b83..d4092fd3f 100644 --- a/R/read_ngwmn_lithology.R +++ b/R/read_ngwmn_lithology.R @@ -11,6 +11,8 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("lithologyObs", base = "NGWMN")`. #' The default (`NA`) will return all columns of the data. +#' @param \dots Not used. Included to help differentiate official NGWMN API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_non_api #' #' @examplesIf is_dataRetrieval_user() @@ -38,12 +40,12 @@ read_ngwmn_lithology <- function( attach_request = getOption("dataRetrieval.attach_request") ) { service <- "lithologyObs" - + # Check for mandatory arguments: - if(all(is.na(monitoring_location_id))){ + if (all(is.na(monitoring_location_id))) { stop("monitoring_location_id is a mandatory argument.") } - + rlang::check_dots_empty() args <- mget(names(formals())) diff --git a/R/read_ngwmn_providers.R b/R/read_ngwmn_providers.R index ae322fdc9..d3740e600 100644 --- a/R/read_ngwmn_providers.R +++ b/R/read_ngwmn_providers.R @@ -13,6 +13,8 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("providers", base = "NGWMN")`. #' The default (`NA`) will return all columns of the data. +#' @param \dots Not used. Included to help differentiate official NGWMN API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_non_api #' #' @examplesIf is_dataRetrieval_user() diff --git a/R/read_ngwmn_sites.R b/R/read_ngwmn_sites.R index c8eb38573..961900a44 100644 --- a/R/read_ngwmn_sites.R +++ b/R/read_ngwmn_sites.R @@ -68,7 +68,8 @@ #' depth). Coordinates are assumed to be in crs 4326. The expected format is a numeric #' vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, #' Southern-most latitude, Eastern-most longitude, Northern-most longitude). -#' +#' @param \dots Not used. Included to help differentiate official NGWMN API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_non_api #' @examplesIf is_dataRetrieval_user() #' diff --git a/R/read_ngwmn_water_level.R b/R/read_ngwmn_water_level.R index 307930e9f..6bfc37784 100644 --- a/R/read_ngwmn_water_level.R +++ b/R/read_ngwmn_water_level.R @@ -24,12 +24,13 @@ #' #' @param datetime #' `r get_ogc_params("waterLevelObs", base = "NGWMN")$sample_time$description` -#' +#' #' @param properties A vector of requested columns to be returned from the query. #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("waterLevelObs", base = "NGWMN")`. #' The default (`NA`) will return all columns of the data. -#' +#' @param \dots Not used. Included to help differentiate official NGWMN API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_non_api #' #' @examplesIf is_dataRetrieval_user() @@ -68,12 +69,12 @@ read_ngwmn_water_level <- function( attach_request = getOption("dataRetrieval.attach_request") ) { service <- "waterLevelObs" - + # Check for mandatory arguments: - if(all(is.na(monitoring_location_id))){ + if (all(is.na(monitoring_location_id))) { stop("monitoring_location_id is a mandatory argument.") } - + rlang::check_dots_empty() args <- mget(names(formals())) diff --git a/R/read_ngwmn_well_construction.R b/R/read_ngwmn_well_construction.R index 6e11c5868..3caa5a3ab 100644 --- a/R/read_ngwmn_well_construction.R +++ b/R/read_ngwmn_well_construction.R @@ -13,6 +13,8 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("constructionObs", base = "NGWMN")`. #' The default (`NA`) will return all columns of the data. +#' @param \dots Not used. Included to help differentiate official NGWMN API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_non_api #' #' @examplesIf is_dataRetrieval_user() @@ -43,10 +45,10 @@ read_ngwmn_well_construction <- function( ) { service <- "constructionObs" # Check for mandatory arguments: - if(all(is.na(monitoring_location_id))){ + if (all(is.na(monitoring_location_id))) { stop("monitoring_location_id is a mandatory argument.") } - + rlang::check_dots_empty() args <- mget(names(formals())) diff --git a/R/read_waterdata_latest_field.R b/R/read_waterdata_latest_field.R index a27300561..7839aa470 100644 --- a/R/read_waterdata_latest_field.R +++ b/R/read_waterdata_latest_field.R @@ -29,7 +29,8 @@ #' but are not returned. These are used as alternatives to specifying specific #' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "latest-field-measurements")` #' to get a list of all possible arguments available in this list. -#' +#' @param \dots Not used. Included to help differentiate official Water Data API arguments +#' from more seldom used, optional dataRetrieval-specific arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] diff --git a/man/read_ngwmn_lithology.Rd b/man/read_ngwmn_lithology.Rd index 8b38cf12d..27b9636ff 100644 --- a/man/read_ngwmn_lithology.Rd +++ b/man/read_ngwmn_lithology.Rd @@ -26,6 +26,9 @@ Available options are: agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, lithology_id, lithology_description, lithology_controlled_concept, lithology_depth_from, lithology_depth_to, lithology_depth_to_unit, lithology_depth_from_unit. The default (\code{NA}) will return all columns of the data.} +\item{\dots}{Not used. Included to help differentiate official NGWMN API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} diff --git a/man/read_ngwmn_providers.Rd b/man/read_ngwmn_providers.Rd index 6517f40a7..6d128f88b 100644 --- a/man/read_ngwmn_providers.Rd +++ b/man/read_ngwmn_providers.Rd @@ -29,6 +29,9 @@ Available options are: agency_name, agency_code, organization_type, state, link. The default (\code{NA}) will return all columns of the data.} +\item{\dots}{Not used. Included to help differentiate official NGWMN API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} diff --git a/man/read_ngwmn_sites.Rd b/man/read_ngwmn_sites.Rd index fc5191c8c..35868f693 100644 --- a/man/read_ngwmn_sites.Rd +++ b/man/read_ngwmn_sites.Rd @@ -108,6 +108,9 @@ The default (\code{NA}) will return all columns of the data.} each feature. The returning object will be a data frame with no spatial information.} +\item{\dots}{Not used. Included to help differentiate official NGWMN API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} diff --git a/man/read_ngwmn_water_level.Rd b/man/read_ngwmn_water_level.Rd index 16de6b493..f0b95fe43 100644 --- a/man/read_ngwmn_water_level.Rd +++ b/man/read_ngwmn_water_level.Rd @@ -65,6 +65,9 @@ Examples: Only features that have a \code{sample_time} that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties.} +\item{\dots}{Not used. Included to help differentiate official NGWMN API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} diff --git a/man/read_ngwmn_well_construction.Rd b/man/read_ngwmn_well_construction.Rd index 765446552..907f21c89 100644 --- a/man/read_ngwmn_well_construction.Rd +++ b/man/read_ngwmn_well_construction.Rd @@ -29,6 +29,9 @@ Available options are: agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, type, depth_from, depth_to, depth_from_unit, depth_to_unit, material, diameter, diameter_unit, hole_size, hole_size_unit. The default (\code{NA}) will return all columns of the data.} +\item{\dots}{Not used. Included to help differentiate official NGWMN API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} diff --git a/man/read_waterdata_latest_field_measurements.Rd b/man/read_waterdata_latest_field_measurements.Rd index b1c708cc6..895bd2a95 100644 --- a/man/read_waterdata_latest_field_measurements.Rd +++ b/man/read_waterdata_latest_field_measurements.Rd @@ -98,6 +98,9 @@ but are not returned. These are used as alternatives to specifying specific monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-field-measurements")} to get a list of all possible arguments available in this list.} +\item{\dots}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.} From 3f87265eae5e834d6b42158d2be00a141da370cc Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 9 Jul 2026 11:57:23 -0500 Subject: [PATCH 46/71] simplify to just dots --- R/read_waterdata_continuous.R | 20 +++++------------ R/read_waterdata_field_measurements.R | 20 +++++------------ R/read_waterdata_latest_continuous.R | 20 +++++------------ R/read_waterdata_latest_daily.R | 20 +++++------------ R/read_waterdata_latest_field.R | 18 ++++++--------- R/read_waterdata_peaks.R | 20 +++++------------ man/read_waterdata_continuous.Rd | 17 +++++--------- man/read_waterdata_field_measurements.Rd | 17 +++++--------- man/read_waterdata_latest_continuous.Rd | 17 +++++--------- man/read_waterdata_latest_daily.Rd | 17 +++++--------- ...ead_waterdata_latest_field_measurements.Rd | 22 +++++++++---------- man/read_waterdata_peaks.Rd | 16 +++++--------- 12 files changed, 72 insertions(+), 152 deletions(-) diff --git a/R/read_waterdata_continuous.R b/R/read_waterdata_continuous.R index 8a0a292c2..92bfa4db2 100644 --- a/R/read_waterdata_continuous.R +++ b/R/read_waterdata_continuous.R @@ -31,12 +31,10 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("continuous", "continuous_id")`. #' The default (`NA`) will return all columns of the data. -#' @param monitoring_location_arguments A list of arguments that can be queried, +#' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "continuous")` -#' to get a list of all possible arguments available in this list. -#' @param \dots Not used. Included to help differentiate official Water Data API arguments -#' from more seldom used, optional dataRetrieval-specific arguments. +#' monitoring_location_ids. See `make_monitoring_location_arguments()` +#' to get a list of all possible arguments available. #' @seealso [make_monitoring_location_arguments()] #' @inheritParams check_arguments_non_api #' @inheritParams check_arguments_api @@ -82,10 +80,8 @@ #' last_modified = "P7D") #' #' dane <- read_waterdata_continuous( -#' monitoring_location_arguments = list( -#' state_name = "Wisconsin", -#' county_name = "Dane County" -#' ), +#' state_name = "Wisconsin", +#' county_name = "Dane County", #' parameter_code = "00060", #' time = "P1D") #' @@ -135,9 +131,6 @@ read_waterdata_continuous <- function( time = NA_character_, skipGeometry = TRUE, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments( - service = "continuous" - ), ..., convertType = getOption("dataRetrieval.convertType"), limit = getOption("dataRetrieval.limit"), @@ -147,13 +140,12 @@ read_waterdata_continuous <- function( ) { service <- "continuous" output_id <- "continuous_id" - rlang::check_dots_empty() args <- mget(names(formals())) args <- cleanup_arguments( args = args, - monitoring_location_arguments = monitoring_location_arguments, + monitoring_location_arguments = list(...), service = service ) diff --git a/R/read_waterdata_field_measurements.R b/R/read_waterdata_field_measurements.R index a9d8b1bd8..c994aa5d6 100644 --- a/R/read_waterdata_field_measurements.R +++ b/R/read_waterdata_field_measurements.R @@ -37,12 +37,10 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("field-measurements", "field_measurement_id")`. #' The default (`NA`) will return all columns of the data. -#' @param monitoring_location_arguments A list of arguments that can be queried, +#' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "field-measurements")` -#' to get a list of all possible arguments available in this list. -#' @param \dots Not used. Included to help differentiate official Water Data API arguments -#' from more seldom used, optional dataRetrieval-specific arguments. +#' monitoring_location_ids. See `make_monitoring_location_arguments()` +#' to get a list of all possible arguments available. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] @@ -89,10 +87,8 @@ #' parameter_code = "00060") #' #' dane <- read_waterdata_field_measurements( -#' monitoring_location_arguments = list( -#' state_name = "Wisconsin", -#' county_name = "Dane County" -#' ), +#' state_name = "Wisconsin", +#' county_name = "Dane County", #' parameter_code = "00060", #' time = "P30D") #' @@ -118,9 +114,6 @@ read_waterdata_field_measurements <- function( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments( - service = "field-measurements" - ), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -130,13 +123,12 @@ read_waterdata_field_measurements <- function( ) { service <- "field-measurements" output_id <- "field_measurement_id" - rlang::check_dots_empty() args <- mget(names(formals())) args <- cleanup_arguments( args = args, - monitoring_location_arguments = monitoring_location_arguments, + monitoring_location_arguments = list(...), service = service ) diff --git a/R/read_waterdata_latest_continuous.R b/R/read_waterdata_latest_continuous.R index ca3499b92..da859f870 100644 --- a/R/read_waterdata_latest_continuous.R +++ b/R/read_waterdata_latest_continuous.R @@ -23,12 +23,10 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("latest-continuous", "latest_continuous_id")`. #' The default (`NA`) will return all columns of the data. -#' @param monitoring_location_arguments A list of arguments that can be queried, +#' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "latest-continuous")` -#' to get a list of all possible arguments available in this list. -#' @param \dots Not used. Included to help differentiate official Water Data API arguments -#' from more seldom used, optional dataRetrieval-specific arguments. +#' monitoring_location_ids. See `make_monitoring_location_arguments()` +#' to get a list of all possible arguments available. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] @@ -68,10 +66,8 @@ #' last_modified = "P7D") #' #' dane <- read_waterdata_latest_continuous( -#' monitoring_location_arguments = list( -#' state_name = "Wisconsin", -#' county_name = "Dane County" -#' ), +#' state_name = "Wisconsin", +#' county_name = "Dane County", #' parameter_code = "00060", #' time = "P1D") #' @@ -89,9 +85,6 @@ read_waterdata_latest_continuous <- function( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments( - service = "latest-continuous" - ), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -101,13 +94,12 @@ read_waterdata_latest_continuous <- function( ) { service <- "latest-continuous" output_id <- "latest_continuous_id" - rlang::check_dots_empty() args <- mget(names(formals())) args <- cleanup_arguments( args = args, - monitoring_location_arguments = monitoring_location_arguments, + monitoring_location_arguments = list(...), service = service ) diff --git a/R/read_waterdata_latest_daily.R b/R/read_waterdata_latest_daily.R index b1236d8bc..8a329c03d 100644 --- a/R/read_waterdata_latest_daily.R +++ b/R/read_waterdata_latest_daily.R @@ -25,12 +25,10 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("latest-daily", "latest_daily_id")`. #' The default (`NA`) will return all columns of the data. -#' @param monitoring_location_arguments A list of arguments that can be queried, +#' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "latest-daily")` -#' to get a list of all possible arguments available in this list. -#' @param \dots Not used. Included to help differentiate official Water Data API arguments -#' from more seldom used, optional dataRetrieval-specific arguments. +#' monitoring_location_ids. See `make_monitoring_location_arguments()` +#' to get a list of all possible arguments available. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] @@ -63,10 +61,8 @@ #' parameter_code = c("00060", "00010")) #' #' dane <- read_waterdata_latest_daily( -#' monitoring_location_arguments = list( -#' state_name = "Wisconsin", -#' county_name = "Dane County" -#' ), +#' state_name = "Wisconsin", +#' county_name = "Dane County", #' parameter_code = "00060", #' time = "P7D") #' @@ -85,9 +81,6 @@ read_waterdata_latest_daily <- function( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments( - service = "latest-daily" - ), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -97,13 +90,12 @@ read_waterdata_latest_daily <- function( ) { service <- "latest-daily" output_id <- "latest_daily_id" - rlang::check_dots_empty() args <- mget(names(formals())) args <- cleanup_arguments( args = args, - monitoring_location_arguments = monitoring_location_arguments, + monitoring_location_arguments = list(...), service = service ) diff --git a/R/read_waterdata_latest_field.R b/R/read_waterdata_latest_field.R index 7839aa470..606fa9b45 100644 --- a/R/read_waterdata_latest_field.R +++ b/R/read_waterdata_latest_field.R @@ -29,8 +29,10 @@ #' but are not returned. These are used as alternatives to specifying specific #' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "latest-field-measurements")` #' to get a list of all possible arguments available in this list. -#' @param \dots Not used. Included to help differentiate official Water Data API arguments -#' from more seldom used, optional dataRetrieval-specific arguments. +#' @param \dots Arguments that can be queried, +#' but are not returned. These are used as alternatives to specifying specific +#' monitoring_location_ids. See `make_monitoring_location_arguments()` +#' to get a list of all possible arguments available. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] @@ -55,10 +57,8 @@ #' "USGS-14202650")) #' #' dane <- read_waterdata_latest_field_measurements( -#' monitoring_location_arguments = list( -#' state_name = "Wisconsin", -#' county_name = "Dane County" -#' ), +#' state_name = "Wisconsin", +#' county_name = "Dane County", #' time = "P30D") #' #' } @@ -76,9 +76,6 @@ read_waterdata_latest_field_measurements <- function( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments( - service = "latest-field-measurements" - ), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -88,13 +85,12 @@ read_waterdata_latest_field_measurements <- function( ) { service <- "latest-field-measurements" output_id <- "latest_field_id" - rlang::check_dots_empty() args <- mget(names(formals())) args <- cleanup_arguments( args = args, - monitoring_location_arguments = monitoring_location_arguments, + monitoring_location_arguments = list(...), service = service ) diff --git a/R/read_waterdata_peaks.R b/R/read_waterdata_peaks.R index 6caef0e03..871d7f50f 100644 --- a/R/read_waterdata_peaks.R +++ b/R/read_waterdata_peaks.R @@ -36,12 +36,10 @@ #' or whether to set those dates to `NA` (`FALSE`). Peaks with uncertain days #' are stored on the first of the month, and those with uncertain #' month stored on January 1. Default is `FALSE`. -#' @param monitoring_location_arguments A list of arguments that can be queried, +#' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "peaks")` -#' to get a list of all possible arguments available in this list. -#' @param \dots Not used. Included to help differentiate official Water Data API arguments -#' from more seldom used, optional dataRetrieval-specific arguments. +#' monitoring_location_ids. See `make_monitoring_location_arguments()` +#' to get a list of all possible arguments available. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' @seealso [make_monitoring_location_arguments()] @@ -62,10 +60,8 @@ #' parameter_code = "00060") #' #' dane <- read_waterdata_peaks( -#' monitoring_location_arguments = list( -#' state_name = "Wisconsin", -#' county_name = "Dane County" -#' ), +#' state_name = "Wisconsin", +#' county_name = "Dane County", #' parameter_code = "00060") #' #' incomplete_dates_not_allowed <- read_waterdata_peaks( @@ -97,9 +93,6 @@ read_waterdata_peaks <- function( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments( - service = "peaks" - ), ..., allow_incomplete_dates = FALSE, convertType = getOption("dataRetrieval.convertType"), @@ -110,13 +103,12 @@ read_waterdata_peaks <- function( ) { service <- "peaks" output_id <- "peak_id" - rlang::check_dots_empty() args <- mget(names(formals())) args <- cleanup_arguments( args = args, - monitoring_location_arguments = monitoring_location_arguments, + monitoring_location_arguments = list(...), service = service ) diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index b49c11453..e21deaa4a 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -17,8 +17,6 @@ read_waterdata_continuous( time = NA_character_, skipGeometry = TRUE, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments(service = - "continuous"), ..., convertType = getOption("dataRetrieval.convertType"), limit = getOption("dataRetrieval.limit"), @@ -92,13 +90,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} -\item{monitoring_location_arguments}{A list of arguments that can be queried, +\item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "continuous")} -to get a list of all possible arguments available in this list.} - -\item{\dots}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} +monitoring_location_ids. See \code{make_monitoring_location_arguments()} +to get a list of all possible arguments available.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -178,10 +173,8 @@ multi_site2 <- read_waterdata_continuous(monitoring_location_id = c("USGS-45160 last_modified = "P7D") dane <- read_waterdata_continuous( - monitoring_location_arguments = list( - state_name = "Wisconsin", - county_name = "Dane County" - ), + state_name = "Wisconsin", + county_name = "Dane County", parameter_code = "00060", time = "P1D") diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index 57462756c..4adee87cc 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -24,8 +24,6 @@ read_waterdata_field_measurements( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments(service = - "field-measurements"), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -120,13 +118,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} -\item{monitoring_location_arguments}{A list of arguments that can be queried, +\item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "field-measurements")} -to get a list of all possible arguments available in this list.} - -\item{\dots}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} +monitoring_location_ids. See \code{make_monitoring_location_arguments()} +to get a list of all possible arguments available.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -214,10 +209,8 @@ surface_water <- read_waterdata_field_measurements( parameter_code = "00060") dane <- read_waterdata_field_measurements( - monitoring_location_arguments = list( - state_name = "Wisconsin", - county_name = "Dane County" - ), + state_name = "Wisconsin", + county_name = "Dane County", parameter_code = "00060", time = "P30D") diff --git a/man/read_waterdata_latest_continuous.Rd b/man/read_waterdata_latest_continuous.Rd index 1cf2db828..ea1da5b8d 100644 --- a/man/read_waterdata_latest_continuous.Rd +++ b/man/read_waterdata_latest_continuous.Rd @@ -17,8 +17,6 @@ read_waterdata_latest_continuous( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments(service = - "latest-continuous"), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -92,13 +90,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} -\item{monitoring_location_arguments}{A list of arguments that can be queried, +\item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-continuous")} -to get a list of all possible arguments available in this list.} - -\item{\dots}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} +monitoring_location_ids. See \code{make_monitoring_location_arguments()} +to get a list of all possible arguments available.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -181,10 +176,8 @@ multi_site2 <- read_waterdata_latest_continuous(monitoring_location_id = c("USG last_modified = "P7D") dane <- read_waterdata_latest_continuous( - monitoring_location_arguments = list( - state_name = "Wisconsin", - county_name = "Dane County" - ), + state_name = "Wisconsin", + county_name = "Dane County", parameter_code = "00060", time = "P1D") diff --git a/man/read_waterdata_latest_daily.Rd b/man/read_waterdata_latest_daily.Rd index c83c8b8da..bdf08ab6b 100644 --- a/man/read_waterdata_latest_daily.Rd +++ b/man/read_waterdata_latest_daily.Rd @@ -18,8 +18,6 @@ read_waterdata_latest_daily( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments(service = - "latest-daily"), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -97,13 +95,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} -\item{monitoring_location_arguments}{A list of arguments that can be queried, +\item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-daily")} -to get a list of all possible arguments available in this list.} - -\item{\dots}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} +monitoring_location_ids. See \code{make_monitoring_location_arguments()} +to get a list of all possible arguments available.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -179,10 +174,8 @@ multi_site <- read_waterdata_latest_daily(monitoring_location_id = c("USGS-0149 parameter_code = c("00060", "00010")) dane <- read_waterdata_latest_daily( - monitoring_location_arguments = list( - state_name = "Wisconsin", - county_name = "Dane County" - ), + state_name = "Wisconsin", + county_name = "Dane County", parameter_code = "00060", time = "P7D") diff --git a/man/read_waterdata_latest_field_measurements.Rd b/man/read_waterdata_latest_field_measurements.Rd index 895bd2a95..70c637463 100644 --- a/man/read_waterdata_latest_field_measurements.Rd +++ b/man/read_waterdata_latest_field_measurements.Rd @@ -18,8 +18,6 @@ read_waterdata_latest_field_measurements( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments(service = - "latest-field-measurements"), ..., convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), @@ -93,13 +91,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} -\item{monitoring_location_arguments}{A list of arguments that can be queried, +\item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-field-measurements")} -to get a list of all possible arguments available in this list.} - -\item{\dots}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} +monitoring_location_ids. See \code{make_monitoring_location_arguments()} +to get a list of all possible arguments available.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -127,6 +122,11 @@ Setting to \code{NA} will eliminate site chunking, giving users full control.} \item{attach_request}{logical, defaults to TRUE. If set to \code{TRUE}, the full request sent to the Water Data API is attached as an attribute to the data set.} + +\item{monitoring_location_arguments}{A list of arguments that can be queried, +but are not returned. These are used as alternatives to specifying specific +monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-field-measurements")} +to get a list of all possible arguments available in this list.} } \description{ Field measurements are physically measured values collected during a visit to the monitoring location. Field measurements consist of measurements of gage height and discharge, and readings of groundwater levels, and are primarily used as calibration readings for the automated sensors collecting continuous data. They are collected at a low frequency, and delivery of the data in WDFN may be delayed due to data processing time. @@ -167,10 +167,8 @@ multi_site <- read_waterdata_latest_field_measurements(monitoring_location_id = "USGS-14202650")) dane <- read_waterdata_latest_field_measurements( - monitoring_location_arguments = list( - state_name = "Wisconsin", - county_name = "Dane County" - ), + state_name = "Wisconsin", + county_name = "Dane County", time = "P30D") } diff --git a/man/read_waterdata_peaks.Rd b/man/read_waterdata_peaks.Rd index 3ef0022b0..4a758af80 100644 --- a/man/read_waterdata_peaks.Rd +++ b/man/read_waterdata_peaks.Rd @@ -22,7 +22,6 @@ read_waterdata_peaks( skipGeometry = NA, time = NA_character_, bbox = NA, - monitoring_location_arguments = make_monitoring_location_arguments(service = "peaks"), ..., allow_incomplete_dates = FALSE, convertType = getOption("dataRetrieval.convertType"), @@ -105,13 +104,10 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} -\item{monitoring_location_arguments}{A list of arguments that can be queried, +\item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "peaks")} -to get a list of all possible arguments available in this list.} - -\item{\dots}{Not used. Included to help differentiate official Water Data API arguments -from more seldom used, optional dataRetrieval-specific arguments.} +monitoring_location_ids. See \code{make_monitoring_location_arguments()} +to get a list of all possible arguments available.} \item{allow_incomplete_dates}{Specifically in the peaks data, exact peak dates are not always known. Sometimes peaks are known just for the year, sometimes @@ -183,10 +179,8 @@ dv_data_sf <- read_waterdata_peaks( parameter_code = "00060") dane <- read_waterdata_peaks( - monitoring_location_arguments = list( - state_name = "Wisconsin", - county_name = "Dane County" - ), + state_name = "Wisconsin", + county_name = "Dane County", parameter_code = "00060") incomplete_dates_not_allowed <- read_waterdata_peaks( From 3444e4ec34469c2ed71506bb70544cba63cb1192 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 9 Jul 2026 13:45:34 -0500 Subject: [PATCH 47/71] Added news --- NEWS | 13 ++++++++++++- R/read_waterdata_continuous.R | 2 +- R/read_waterdata_daily.R | 9 +++++---- man/read_waterdata_continuous.Rd | 2 +- man/read_waterdata_daily.Rd | 9 +++++---- 5 files changed, 24 insertions(+), 11 deletions(-) diff --git a/NEWS b/NEWS index 19d5dcc01..4929f5c32 100644 --- a/NEWS +++ b/NEWS @@ -2,8 +2,19 @@ dataRetrieval 2.7.26 =================== * Added suite of read_ngwmn to access new National Groundwater Monitoring Network API. -* Added read_waterdata_use to access USGS's National Water Availability +* Added read_wateruse to access USGS's National Water Availability Assessment Data Companion API service. +* Created make_monitoring_location_arguments to help users understand +what new optional arguments are available in many of the read_waterdata functions. +* Added ability to use `...` in the Water Data functions for: daily, latest-continuous, +field-measurements, latest-daily, latest-field-measurements, continuous, and peaks. +The "..." argument can now accept any parameter that is output from the new +make_monitoring_location_arguments function. +* Added "q" argument to read_waterdata_monitoring_location. Full-text search across +the most relevant text fields for this collection (e.g. site name, identifier, +number, state, county, and site type). +* Added "skipGeometry" argument to read_waterdata_continuous. Previously geometry +wasn't included with continuous data, but now is supported. dataRetrieval 2.7.25 =================== diff --git a/R/read_waterdata_continuous.R b/R/read_waterdata_continuous.R index 92bfa4db2..8d0aca640 100644 --- a/R/read_waterdata_continuous.R +++ b/R/read_waterdata_continuous.R @@ -6,7 +6,7 @@ #' a single request. If no "time" is specified, the service will return the #' last single year of data. If this is a bottleneck, please check back #' for new direct download functions that are expected to be available sometime -#' in 2026. +#' in 2027. #' #' #' @export diff --git a/R/read_waterdata_daily.R b/R/read_waterdata_daily.R index 88b48a443..8eb34ba6c 100644 --- a/R/read_waterdata_daily.R +++ b/R/read_waterdata_daily.R @@ -77,10 +77,11 @@ #' parameter_code = "00060", #' time = c("2021-01-01", "2022-01-01")) #' -#' dv_dane <- read_waterdata_daily(state_name = "Wisconsin", -#' county_name = "Dane County", -#' parameter_code = "00060", -#' time = "P7D") +#' dv_dane <- read_waterdata_daily( +#' state_name = "Wisconsin", +#' county_name = "Dane County", +#' parameter_code = "00060", +#' time = "P7D") #' #' } read_waterdata_daily <- function( diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index e21deaa4a..55f87fd91 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -129,7 +129,7 @@ Currently, the services only allow up to 3 years of data to be requested with a single request. If no "time" is specified, the service will return the last single year of data. If this is a bottleneck, please check back for new direct download functions that are expected to be available sometime -in 2026. +in 2027. } \details{ You can also use a vector of length 2 for any time queries (such as time diff --git a/man/read_waterdata_daily.Rd b/man/read_waterdata_daily.Rd index 5ef5297a0..6f35753b5 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -190,10 +190,11 @@ dv_data_no_request <- read_waterdata_daily(monitoring_location_id = site, parameter_code = "00060", time = c("2021-01-01", "2022-01-01")) -dv_dane <- read_waterdata_daily(state_name = "Wisconsin", - county_name = "Dane County", - parameter_code = "00060", - time = "P7D") +dv_dane <- read_waterdata_daily( + state_name = "Wisconsin", + county_name = "Dane County", + parameter_code = "00060", + time = "P7D") } \dontshow{\}) # examplesIf} From c16f21837054079cd1374f7186d99b64fc2497aa Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 9 Jul 2026 13:46:53 -0500 Subject: [PATCH 48/71] sp --- NEWS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWS b/NEWS index 4929f5c32..4f87cf0d7 100644 --- a/NEWS +++ b/NEWS @@ -8,7 +8,7 @@ Assessment Data Companion API service. what new optional arguments are available in many of the read_waterdata functions. * Added ability to use `...` in the Water Data functions for: daily, latest-continuous, field-measurements, latest-daily, latest-field-measurements, continuous, and peaks. -The "..." argument can now accept any parameter that is output from the new +The "..." argument can now accept any parameter that is output from the make_monitoring_location_arguments function. * Added "q" argument to read_waterdata_monitoring_location. Full-text search across the most relevant text fields for this collection (e.g. site name, identifier, From 5b178bd37bc6d194700501203c7272a0f4ca21c1 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 9 Jul 2026 14:16:18 -0500 Subject: [PATCH 49/71] cleanup arg --- R/read_waterdata_latest_field.R | 4 ---- man/read_waterdata_latest_field_measurements.Rd | 5 ----- 2 files changed, 9 deletions(-) diff --git a/R/read_waterdata_latest_field.R b/R/read_waterdata_latest_field.R index 606fa9b45..20f865795 100644 --- a/R/read_waterdata_latest_field.R +++ b/R/read_waterdata_latest_field.R @@ -25,10 +25,6 @@ #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("latest-field-measurements", "latest_field_id")`. #' The default (`NA`) will return all columns of the data. -#' @param monitoring_location_arguments A list of arguments that can be queried, -#' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. Run `make_monitoring_location_arguments(service = "latest-field-measurements")` -#' to get a list of all possible arguments available in this list. #' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific #' monitoring_location_ids. See `make_monitoring_location_arguments()` diff --git a/man/read_waterdata_latest_field_measurements.Rd b/man/read_waterdata_latest_field_measurements.Rd index 70c637463..33f723e65 100644 --- a/man/read_waterdata_latest_field_measurements.Rd +++ b/man/read_waterdata_latest_field_measurements.Rd @@ -122,11 +122,6 @@ Setting to \code{NA} will eliminate site chunking, giving users full control.} \item{attach_request}{logical, defaults to TRUE. If set to \code{TRUE}, the full request sent to the Water Data API is attached as an attribute to the data set.} - -\item{monitoring_location_arguments}{A list of arguments that can be queried, -but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. Run \code{make_monitoring_location_arguments(service = "latest-field-measurements")} -to get a list of all possible arguments available in this list.} } \description{ Field measurements are physically measured values collected during a visit to the monitoring location. Field measurements consist of measurements of gage height and discharge, and readings of groundwater levels, and are primarily used as calibration readings for the automated sensors collecting continuous data. They are collected at a low frequency, and delivery of the data in WDFN may be delayed due to data processing time. From 6d0ea7463bbbbc54cb236e65609330fae001ac16 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Mon, 13 Jul 2026 08:15:46 -0500 Subject: [PATCH 50/71] get NEWS added to pkgdown --- NEWS => NEWS.md | 15 ++++----------- _pkgdown.yml | 4 ++++ 2 files changed, 8 insertions(+), 11 deletions(-) rename NEWS => NEWS.md (96%) diff --git a/NEWS b/NEWS.md similarity index 96% rename from NEWS rename to NEWS.md index 4f87cf0d7..a7d1824fa 100644 --- a/NEWS +++ b/NEWS.md @@ -2,19 +2,12 @@ dataRetrieval 2.7.26 =================== * Added suite of read_ngwmn to access new National Groundwater Monitoring Network API. -* Added read_wateruse to access USGS's National Water Availability -Assessment Data Companion API service. +* Added read_wateruse to access USGS's National Water Availability Assessment Data Companion API service. * Created make_monitoring_location_arguments to help users understand what new optional arguments are available in many of the read_waterdata functions. -* Added ability to use `...` in the Water Data functions for: daily, latest-continuous, -field-measurements, latest-daily, latest-field-measurements, continuous, and peaks. -The "..." argument can now accept any parameter that is output from the -make_monitoring_location_arguments function. -* Added "q" argument to read_waterdata_monitoring_location. Full-text search across -the most relevant text fields for this collection (e.g. site name, identifier, -number, state, county, and site type). -* Added "skipGeometry" argument to read_waterdata_continuous. Previously geometry -wasn't included with continuous data, but now is supported. +* Added ability to use `...` in the Water Data functions for: daily, latest-continuous, field-measurements, latest-daily, latest-field-measurements, continuous, and peaks. The "..." argument can now accept any parameter that is output from the make_monitoring_location_arguments function. +* Added "q" argument to read_waterdata_monitoring_location. Full-text search across the most relevant text fields for this collection (e.g. site name, identifier, number, state, county, and site type). +* Added "skipGeometry" argument to read_waterdata_continuous. Previously geometry wasn't included with continuous data, but now is supported. dataRetrieval 2.7.25 =================== diff --git a/_pkgdown.yml b/_pkgdown.yml index a95d78a12..86ee1aadc 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -65,6 +65,10 @@ navbar: - text: How to Contribute href: articles/Contributing.html right: + - text: News + href: news/index.html + - icon: fa-gitlab fa-lg + href: https://code.usgs.gov/water/dataRetrieval - icon: fa-github fa-lg href: https://github.com/DOI-USGS/dataRetrieval reference: From d12f9c335f866eb049f7acab79570cc332d9b9bb Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Mon, 13 Jul 2026 08:47:11 -0500 Subject: [PATCH 51/71] with logo --- .github/workflows/pkgdown.yaml | 3 ++- .gitlab-ci.yml | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 38eef4aba..06e731e81 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -74,7 +74,8 @@ jobs: - name: Build site run: | pkgdown::build_site(override = list(destination = "public")) | - file.copy(from = "./public/articles/logo.png",to = "./public/reference/logo.png") + file.copy(from = "./public/articles/logo.png",to = "./public/reference/logo.png") | + file.copy(from = "./public/articles/logo.png", to = "./public/news/logo.png") shell: Rscript {0} - name: Set up Quarto uses: quarto-dev/quarto-actions/setup@v2 diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 565ddcb1d..660a94752 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -141,7 +141,8 @@ pages: - | Rscript -e ' pkgdown::build_site(override = list(destination = "public")) - file.copy(from = "./public/articles/logo.png", to = "./public/reference/logo.png")' + file.copy(from = "./public/articles/logo.png", to = "./public/reference/logo.png") + file.copy(from = "./public/articles/logo.png", to = "./public/news/logo.png")' - quarto render artifacts: paths: From 358148a5a3076748fc92347685c2ad2cf22816fd Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 16 Jul 2026 10:28:07 -0500 Subject: [PATCH 52/71] Add subtitles --- .gitlab-ci.yml | 1 + tutorials/basic_slides_deck.qmd | 8 +++++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 660a94752..c4019d83f 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -138,6 +138,7 @@ pages: variables: RETICULATE_PYTHON: /usr/bin/python3 script: + - quarto add parmsam/quarto-subtitles - | Rscript -e ' pkgdown::build_site(override = list(destination = "public")) diff --git a/tutorials/basic_slides_deck.qmd b/tutorials/basic_slides_deck.qmd index ab03fbcb8..4e4699ea5 100644 --- a/tutorials/basic_slides_deck.qmd +++ b/tutorials/basic_slides_deck.qmd @@ -8,8 +8,12 @@ format: toc: false slide-number: true logo: hex_logo.png - footer: preview-links: auto + subtitles: + toggleKey: 't' + isVisible: true +revealjs-plugins: + - subtitles title-slide-attributes: data-background-image: combo_hex.png data-background-size: 15% @@ -29,6 +33,8 @@ params: run_python: true --- + + ```{r} #| echo: false #| include: false From 540f27223bf74d52ae03d67195865d58c7b437b5 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 16 Jul 2026 10:30:33 -0500 Subject: [PATCH 53/71] ? --- .github/workflows/pkgdown.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 06e731e81..ea1e1521d 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -79,6 +79,8 @@ jobs: shell: Rscript {0} - name: Set up Quarto uses: quarto-dev/quarto-actions/setup@v2 + - name: Add extension + run: quarto add parmsam/quarto-subtitles - name: Render Quarto Project uses: quarto-dev/quarto-actions/render@v2 - name: Upload artifact From 2629ceec6e98118331252bf301de9b808dd164fb Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 16 Jul 2026 10:43:30 -0500 Subject: [PATCH 54/71] no prompt --- .github/workflows/pkgdown.yaml | 2 +- .gitlab-ci.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index ea1e1521d..a547f10fc 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -80,7 +80,7 @@ jobs: - name: Set up Quarto uses: quarto-dev/quarto-actions/setup@v2 - name: Add extension - run: quarto add parmsam/quarto-subtitles + run: quarto add parmsam/quarto-subtitles --no-prompt - name: Render Quarto Project uses: quarto-dev/quarto-actions/render@v2 - name: Upload artifact diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index c4019d83f..4ff866839 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -138,7 +138,7 @@ pages: variables: RETICULATE_PYTHON: /usr/bin/python3 script: - - quarto add parmsam/quarto-subtitles + - quarto add parmsam/quarto-subtitles --no-prompt - | Rscript -e ' pkgdown::build_site(override = list(destination = "public")) From efd745ec95885146ce600b2bfc6fa3a4a4e299a0 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 16 Jul 2026 11:20:23 -0500 Subject: [PATCH 55/71] I think this will be better because local installations will work without special install instructions. --- .github/workflows/pkgdown.yaml | 2 - .gitlab-ci.yml | 1 - .../parmsam/subtitles/_extension.yml | 16 ++ .../parmsam/subtitles/subtitles.css | 61 ++++++ .../parmsam/subtitles/subtitles.js | 190 ++++++++++++++++++ 5 files changed, 267 insertions(+), 3 deletions(-) create mode 100644 tutorials/_extensions/parmsam/subtitles/_extension.yml create mode 100644 tutorials/_extensions/parmsam/subtitles/subtitles.css create mode 100644 tutorials/_extensions/parmsam/subtitles/subtitles.js diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index a547f10fc..06e731e81 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -79,8 +79,6 @@ jobs: shell: Rscript {0} - name: Set up Quarto uses: quarto-dev/quarto-actions/setup@v2 - - name: Add extension - run: quarto add parmsam/quarto-subtitles --no-prompt - name: Render Quarto Project uses: quarto-dev/quarto-actions/render@v2 - name: Upload artifact diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 4ff866839..660a94752 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -138,7 +138,6 @@ pages: variables: RETICULATE_PYTHON: /usr/bin/python3 script: - - quarto add parmsam/quarto-subtitles --no-prompt - | Rscript -e ' pkgdown::build_site(override = list(destination = "public")) diff --git a/tutorials/_extensions/parmsam/subtitles/_extension.yml b/tutorials/_extensions/parmsam/subtitles/_extension.yml new file mode 100644 index 000000000..1fedc76c4 --- /dev/null +++ b/tutorials/_extensions/parmsam/subtitles/_extension.yml @@ -0,0 +1,16 @@ +title: Subtitles +author: parmsam +version: 1.2.0 +quarto-required: ">=1.4.0" +contributes: + revealjs-plugins: + - name: RevealSubtitles + script: + - subtitles.js + stylesheet: + - subtitles.css + config: + subtitles: + isVisible: true + toggleKey: "t" + diff --git a/tutorials/_extensions/parmsam/subtitles/subtitles.css b/tutorials/_extensions/parmsam/subtitles/subtitles.css new file mode 100644 index 000000000..f9a96b459 --- /dev/null +++ b/tutorials/_extensions/parmsam/subtitles/subtitles.css @@ -0,0 +1,61 @@ +#subtitles-container { + /* Positioning and sizing */ + box-sizing: border-box; + position: absolute; + bottom: 10px; + left: 10px; + right: 10px; + z-index: 1; + padding: 20px 100px; + + /* Align subtitles to bottom and center */ + display: flex; + justify-content: center; + align-content: flex-end; + + /* Pass all mouse events through to presentation below */ + pointer-events: none; + + /* Typography and colors */ + font-family: Arial, Helvetica, sans-serif; + font-size: 28px; + line-height: 42px; + color: white; + text-align: center; + background-color: rgba(0, 0, 0, .7); +} + +#subtitles-container.hidden { + display: none; +} + +#subtitles-container #subtitles-inner-container { + position: relative; + display: block; + width: 100%; + height: 75px; + overflow: hidden; +} + +#subtitles-container #subtitles-inner-container #subtitles { + position: absolute; + bottom: 0; + width: 100%; +} + +#subtitles-container #subtitles #interim_text { + opacity: .6; +} + +/* add class for .subtitles-dl-button */ + +.subtitles-dl-btn { + padding: 5px 10px; + background-color: rgba(0, 0, 0, .7); + color: white; + border: none; + border-radius: 5px; + cursor: pointer; + /* set font size as default */ + font-size: 20px; +} \ No newline at end of file diff --git a/tutorials/_extensions/parmsam/subtitles/subtitles.js b/tutorials/_extensions/parmsam/subtitles/subtitles.js new file mode 100644 index 000000000..0bfb1cf1f --- /dev/null +++ b/tutorials/_extensions/parmsam/subtitles/subtitles.js @@ -0,0 +1,190 @@ +/* + * This file includes code derived from the Reveal.js library, which is licensed under the MIT License. + * Portions of this code are also derived from a third-party repository built on top of Reveal.js. + * The original author did not specify a license for these modifications, so it is assumed to fall under + * the MIT License. + */ + +window.RevealSubtitles = function () { + var keyCodes = { + backspace: 8, tab: 9, enter: 13, shift: 16, ctrl: 17, alt: 18, pausebreak: 19, capslock: 20, + esc: 27, space: 32, pageup: 33, pagedown: 34, end: 35, home: 36, leftarrow: 37, uparrow: 38, + rightarrow: 39, downarrow: 40, insert: 45, delete: 46, 0: 48, 1: 49, 2: 50, 3: 51, 4: 52, + 5: 53, 6: 54, 7: 55, 8: 56, 9: 57, a: 65, b: 66, c: 67, d: 68, e: 69, f: 70, g: 71, h: 72, + i: 73, j: 74, k: 75, l: 76, m: 77, n: 78, o: 79, p: 80, q: 81, r: 82, s: 83, t: 84, u: 85, + v: 86, w: 87, x: 88, y: 89, z: 90, leftwindowkey: 91, rightwindowkey: 92, selectkey: 93, + numpad0: 96, numpad1: 97, numpad2: 98, numpad3: 99, numpad4: 100, numpad5: 101, numpad6: 102, + numpad7: 103, numpad8: 104, numpad9: 105, multiply: 106, add: 107, subtract: 109, decimalpoint: 110, + divide: 111, f1: 112, f2: 113, f3: 114, f4: 115, f5: 116, f6: 117, f7: 118, f8: 119, f9: 120, + f10: 121, f11: 122, f12: 123, numlock: 144, scrolllock: 145, semicolon: 186, equalsign: 187, + comma: 188, dash: 189, period: 190, forwardslash: 191, graveaccent: 192, openbracket: 219, + backslash: 220, closebracket: 221, singlequote: 222 + }; + return { + id: "RevealSubtitles", + init: function (deck) { + const config = deck.getConfig(); + const options = config.subtitles || {}; + var settings = {}; + + settings.toggleKey = options.toggleKey ? options.toggleKey.toLowerCase() : "t"; + settings.toggleKeyCode = keyCodes[settings.toggleKey] || 84; + + var recognition; + var final_transcript = ''; + var start_timestamp; + var final_text_el; + var interim_text_el; + var subtitle_container_el; + var is_visible = true; + + function createHTML() { + subtitle_container_el = document.createElement('div'); + subtitle_container_el.setAttribute('id', 'subtitles-container'); + + subtitles_inner_container_el = document.createElement('div'); + subtitles_inner_container_el.setAttribute('id', 'subtitles-inner-container'); + + subtitles_el = document.createElement('div'); + subtitles_el.setAttribute('id', 'subtitles'); + + final_text_el = document.createElement('span'); + final_text_el.setAttribute('id', 'final_text'); + + interim_text_el = document.createElement('span'); + interim_text_el.setAttribute('id', 'interim_text'); + + subtitles_el.appendChild(final_text_el); + subtitles_el.appendChild(interim_text_el); + + subtitles_inner_container_el.appendChild(subtitles_el); + subtitle_container_el.appendChild(subtitles_inner_container_el); + + document.body.appendChild(subtitle_container_el); + } + + function toggleVisibility() { + is_visible = !is_visible; + subtitle_container_el.classList.toggle('hidden'); + } + + var two_line = /\n\n/g; + var one_line = /\n/g; + function linebreak(s) { + return s.replace(two_line, '

').replace(one_line, '
'); + } + + var first_char = /\S/; + function capitalize(s) { + return s.replace(first_char, function (m) { return m.toUpperCase(); }); + } + + function setup() { + if (!('webkitSpeechRecognition' in window)) { + console.log('Speech recognition not supported. Use Chrome instead.'); + } + else if ( + window.Reveal.isSpeakerNotes() === true + ) { + console.log("Speaker view window detected. Subtitles disabled in speaker view window."); + } else { + recognition = new webkitSpeechRecognition(); + recognition.continuous = true; + recognition.interimResults = true; + + recognition.onstart = function () { + createHTML(); + }; + + recognition.onerror = function (event) { + if (event.error == 'no-speech') { + console.log('No speech detected'); + ignore_onend = true; + } + + if (event.error == 'audio-capture') { + console.log('No microphone found'); + ignore_onend = true; + } + + if (event.error == 'not-allowed') { + if (event.timeStamp - start_timestamp < 100) { + console.log('Permission to use microphone is blocked. Change it at chrome://settings/contentExceptions#media-stream'); + } else { + console.log('Permission to use microphone is denied.'); + } + + ignore_onend = true; + } + }; + + recognition.onresult = function (event) { + var interim_transcript = ''; + + for (var i = event.resultIndex; i < event.results.length; ++i) { + if (event.results[i].isFinal) { + final_transcript += event.results[i][0].transcript; + } else { + interim_transcript += event.results[i][0].transcript; + } + } + + final_transcript = capitalize(final_transcript); + final_text.innerHTML = linebreak(final_transcript); + interim_text.innerHTML = linebreak(interim_transcript); + }; + + deck.addKeyBinding( + { + keyCode: settings.toggleKeyCode, + key: settings.toggleKey + }, + () =>{ + toggleVisibility(); + }); + + + + } + } + + function start() { + recognition.start(); + } + + function stop() { + recognition.stop(); + } + + deck.on('ready', (event) => { + setup(); + start(); + + const downloadButton = document.querySelector('.subtitles-dl-btn'); + downloadButton.addEventListener('click', function () { + const finalTextElement = document.getElementById('final_text'); + const interimTextElement = document.getElementById('interim_text'); + + const finalText = finalTextElement ? finalTextElement.innerText : ''; + const interimText = interimTextElement ? interimTextElement.innerText : ''; + + const combinedText = `Final Text:\n${finalText}\n\nInterim Text:\n${interimText}`; + + const blob = new Blob([combinedText], { type: 'text/plain' }); + + const link = document.createElement('a'); + link.href = URL.createObjectURL(blob); + link.download = 'subtitles-transcript.txt'; + + document.body.appendChild(link); + link.click(); + document.body.removeChild(link); + + URL.revokeObjectURL(link.href); + }); + }); + + }, + }; +}; + From 310d3a2b32b5e717c231b661263590a804412e53 Mon Sep 17 00:00:00 2001 From: Mike Mahoney Date: Tue, 21 Jul 2026 13:18:32 -0400 Subject: [PATCH 56/71] Repoint CQL to OGC sources The specific CQL we use is the Common Query Language from OGC; this PR fixes links to point at the proper sources. --- vignettes/read_waterdata_functions.Rmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vignettes/read_waterdata_functions.Rmd b/vignettes/read_waterdata_functions.Rmd index cb2e94cfa..28fa03211 100644 --- a/vignettes/read_waterdata_functions.Rmd +++ b/vignettes/read_waterdata_functions.Rmd @@ -77,9 +77,9 @@ API_USGS_PAT = "my_super_secret_token" ``` You can use `usethis::edit_r_environ()` to edit find and open your .Renviron file. You will need to restart R for that variable to be recognized. You should not add this file to git projects or generally share your API key. Anyone else using your API key will count against the number of requests available to you! -## Contextual Query Language Support +## Common Query Language Support -Supports [Contextual Query Language](https://www.loc.gov/standards/sru/cql/) (CQL2) syntax for flexible queries. See the `read_waterdata` section below to learn how to make specific and powerful CQL2 queries. +Supports [Common Query Language](https://www.ogc.org/standards/cql2/) (CQL2) syntax for flexible queries. See the `read_waterdata` section below to learn how to make specific and powerful CQL2 queries. ## Simple Features From 221f2971b90685f5c2bef728a9c3af5c36acd952 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Mon, 27 Jul 2026 15:54:30 -0500 Subject: [PATCH 57/71] Win+Ctrl+L seems like a better way to do transcripts if needed --- .../parmsam/subtitles/_extension.yml | 16 -- .../parmsam/subtitles/subtitles.css | 61 ------ .../parmsam/subtitles/subtitles.js | 190 ------------------ tutorials/basic_slides_deck.qmd | 5 - 4 files changed, 272 deletions(-) delete mode 100644 tutorials/_extensions/parmsam/subtitles/_extension.yml delete mode 100644 tutorials/_extensions/parmsam/subtitles/subtitles.css delete mode 100644 tutorials/_extensions/parmsam/subtitles/subtitles.js diff --git a/tutorials/_extensions/parmsam/subtitles/_extension.yml b/tutorials/_extensions/parmsam/subtitles/_extension.yml deleted file mode 100644 index 1fedc76c4..000000000 --- a/tutorials/_extensions/parmsam/subtitles/_extension.yml +++ /dev/null @@ -1,16 +0,0 @@ -title: Subtitles -author: parmsam -version: 1.2.0 -quarto-required: ">=1.4.0" -contributes: - revealjs-plugins: - - name: RevealSubtitles - script: - - subtitles.js - stylesheet: - - subtitles.css - config: - subtitles: - isVisible: true - toggleKey: "t" - diff --git a/tutorials/_extensions/parmsam/subtitles/subtitles.css b/tutorials/_extensions/parmsam/subtitles/subtitles.css deleted file mode 100644 index f9a96b459..000000000 --- a/tutorials/_extensions/parmsam/subtitles/subtitles.css +++ /dev/null @@ -1,61 +0,0 @@ -#subtitles-container { - /* Positioning and sizing */ - box-sizing: border-box; - position: absolute; - bottom: 10px; - left: 10px; - right: 10px; - z-index: 1; - padding: 20px 100px; - - /* Align subtitles to bottom and center */ - display: flex; - justify-content: center; - align-content: flex-end; - - /* Pass all mouse events through to presentation below */ - pointer-events: none; - - /* Typography and colors */ - font-family: Arial, Helvetica, sans-serif; - font-size: 28px; - line-height: 42px; - color: white; - text-align: center; - background-color: rgba(0, 0, 0, .7); -} - -#subtitles-container.hidden { - display: none; -} - -#subtitles-container #subtitles-inner-container { - position: relative; - display: block; - width: 100%; - height: 75px; - overflow: hidden; -} - -#subtitles-container #subtitles-inner-container #subtitles { - position: absolute; - bottom: 0; - width: 100%; -} - -#subtitles-container #subtitles #interim_text { - opacity: .6; -} - -/* add class for .subtitles-dl-button */ - -.subtitles-dl-btn { - padding: 5px 10px; - background-color: rgba(0, 0, 0, .7); - color: white; - border: none; - border-radius: 5px; - cursor: pointer; - /* set font size as default */ - font-size: 20px; -} \ No newline at end of file diff --git a/tutorials/_extensions/parmsam/subtitles/subtitles.js b/tutorials/_extensions/parmsam/subtitles/subtitles.js deleted file mode 100644 index 0bfb1cf1f..000000000 --- a/tutorials/_extensions/parmsam/subtitles/subtitles.js +++ /dev/null @@ -1,190 +0,0 @@ -/* - * This file includes code derived from the Reveal.js library, which is licensed under the MIT License. - * Portions of this code are also derived from a third-party repository built on top of Reveal.js. - * The original author did not specify a license for these modifications, so it is assumed to fall under - * the MIT License. - */ - -window.RevealSubtitles = function () { - var keyCodes = { - backspace: 8, tab: 9, enter: 13, shift: 16, ctrl: 17, alt: 18, pausebreak: 19, capslock: 20, - esc: 27, space: 32, pageup: 33, pagedown: 34, end: 35, home: 36, leftarrow: 37, uparrow: 38, - rightarrow: 39, downarrow: 40, insert: 45, delete: 46, 0: 48, 1: 49, 2: 50, 3: 51, 4: 52, - 5: 53, 6: 54, 7: 55, 8: 56, 9: 57, a: 65, b: 66, c: 67, d: 68, e: 69, f: 70, g: 71, h: 72, - i: 73, j: 74, k: 75, l: 76, m: 77, n: 78, o: 79, p: 80, q: 81, r: 82, s: 83, t: 84, u: 85, - v: 86, w: 87, x: 88, y: 89, z: 90, leftwindowkey: 91, rightwindowkey: 92, selectkey: 93, - numpad0: 96, numpad1: 97, numpad2: 98, numpad3: 99, numpad4: 100, numpad5: 101, numpad6: 102, - numpad7: 103, numpad8: 104, numpad9: 105, multiply: 106, add: 107, subtract: 109, decimalpoint: 110, - divide: 111, f1: 112, f2: 113, f3: 114, f4: 115, f5: 116, f6: 117, f7: 118, f8: 119, f9: 120, - f10: 121, f11: 122, f12: 123, numlock: 144, scrolllock: 145, semicolon: 186, equalsign: 187, - comma: 188, dash: 189, period: 190, forwardslash: 191, graveaccent: 192, openbracket: 219, - backslash: 220, closebracket: 221, singlequote: 222 - }; - return { - id: "RevealSubtitles", - init: function (deck) { - const config = deck.getConfig(); - const options = config.subtitles || {}; - var settings = {}; - - settings.toggleKey = options.toggleKey ? options.toggleKey.toLowerCase() : "t"; - settings.toggleKeyCode = keyCodes[settings.toggleKey] || 84; - - var recognition; - var final_transcript = ''; - var start_timestamp; - var final_text_el; - var interim_text_el; - var subtitle_container_el; - var is_visible = true; - - function createHTML() { - subtitle_container_el = document.createElement('div'); - subtitle_container_el.setAttribute('id', 'subtitles-container'); - - subtitles_inner_container_el = document.createElement('div'); - subtitles_inner_container_el.setAttribute('id', 'subtitles-inner-container'); - - subtitles_el = document.createElement('div'); - subtitles_el.setAttribute('id', 'subtitles'); - - final_text_el = document.createElement('span'); - final_text_el.setAttribute('id', 'final_text'); - - interim_text_el = document.createElement('span'); - interim_text_el.setAttribute('id', 'interim_text'); - - subtitles_el.appendChild(final_text_el); - subtitles_el.appendChild(interim_text_el); - - subtitles_inner_container_el.appendChild(subtitles_el); - subtitle_container_el.appendChild(subtitles_inner_container_el); - - document.body.appendChild(subtitle_container_el); - } - - function toggleVisibility() { - is_visible = !is_visible; - subtitle_container_el.classList.toggle('hidden'); - } - - var two_line = /\n\n/g; - var one_line = /\n/g; - function linebreak(s) { - return s.replace(two_line, '

').replace(one_line, '
'); - } - - var first_char = /\S/; - function capitalize(s) { - return s.replace(first_char, function (m) { return m.toUpperCase(); }); - } - - function setup() { - if (!('webkitSpeechRecognition' in window)) { - console.log('Speech recognition not supported. Use Chrome instead.'); - } - else if ( - window.Reveal.isSpeakerNotes() === true - ) { - console.log("Speaker view window detected. Subtitles disabled in speaker view window."); - } else { - recognition = new webkitSpeechRecognition(); - recognition.continuous = true; - recognition.interimResults = true; - - recognition.onstart = function () { - createHTML(); - }; - - recognition.onerror = function (event) { - if (event.error == 'no-speech') { - console.log('No speech detected'); - ignore_onend = true; - } - - if (event.error == 'audio-capture') { - console.log('No microphone found'); - ignore_onend = true; - } - - if (event.error == 'not-allowed') { - if (event.timeStamp - start_timestamp < 100) { - console.log('Permission to use microphone is blocked. Change it at chrome://settings/contentExceptions#media-stream'); - } else { - console.log('Permission to use microphone is denied.'); - } - - ignore_onend = true; - } - }; - - recognition.onresult = function (event) { - var interim_transcript = ''; - - for (var i = event.resultIndex; i < event.results.length; ++i) { - if (event.results[i].isFinal) { - final_transcript += event.results[i][0].transcript; - } else { - interim_transcript += event.results[i][0].transcript; - } - } - - final_transcript = capitalize(final_transcript); - final_text.innerHTML = linebreak(final_transcript); - interim_text.innerHTML = linebreak(interim_transcript); - }; - - deck.addKeyBinding( - { - keyCode: settings.toggleKeyCode, - key: settings.toggleKey - }, - () =>{ - toggleVisibility(); - }); - - - - } - } - - function start() { - recognition.start(); - } - - function stop() { - recognition.stop(); - } - - deck.on('ready', (event) => { - setup(); - start(); - - const downloadButton = document.querySelector('.subtitles-dl-btn'); - downloadButton.addEventListener('click', function () { - const finalTextElement = document.getElementById('final_text'); - const interimTextElement = document.getElementById('interim_text'); - - const finalText = finalTextElement ? finalTextElement.innerText : ''; - const interimText = interimTextElement ? interimTextElement.innerText : ''; - - const combinedText = `Final Text:\n${finalText}\n\nInterim Text:\n${interimText}`; - - const blob = new Blob([combinedText], { type: 'text/plain' }); - - const link = document.createElement('a'); - link.href = URL.createObjectURL(blob); - link.download = 'subtitles-transcript.txt'; - - document.body.appendChild(link); - link.click(); - document.body.removeChild(link); - - URL.revokeObjectURL(link.href); - }); - }); - - }, - }; -}; - diff --git a/tutorials/basic_slides_deck.qmd b/tutorials/basic_slides_deck.qmd index 4e4699ea5..05002d31d 100644 --- a/tutorials/basic_slides_deck.qmd +++ b/tutorials/basic_slides_deck.qmd @@ -9,11 +9,6 @@ format: slide-number: true logo: hex_logo.png preview-links: auto - subtitles: - toggleKey: 't' - isVisible: true -revealjs-plugins: - - subtitles title-slide-attributes: data-background-image: combo_hex.png data-background-size: 15% From 6832714d9aa59cc7c14dd86c0bc073b73a70ed7e Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Mon, 3 Aug 2026 15:58:08 -0500 Subject: [PATCH 58/71] response to review --- NAMESPACE | 2 +- R/make_monitoring_location_arguments.R | 8 +- R/read_waterdata_continuous.R | 6 +- R/read_waterdata_daily.R | 6 +- R/read_waterdata_field_measurements.R | 6 +- R/read_waterdata_latest_continuous.R | 6 +- R/read_waterdata_latest_daily.R | 6 +- R/read_wateruse.R | 181 ------------------ ...d => get_monitoring_location_arguments.Rd} | 10 +- man/read_waterdata_continuous.Rd | 6 +- man/read_waterdata_daily.Rd | 6 +- man/read_waterdata_field_measurements.Rd | 6 +- man/read_waterdata_latest_continuous.Rd | 6 +- man/read_waterdata_latest_daily.Rd | 6 +- ...ead_waterdata_latest_field_measurements.Rd | 6 +- man/read_waterdata_peaks.Rd | 6 +- 16 files changed, 46 insertions(+), 227 deletions(-) delete mode 100644 R/read_wateruse.R rename man/{make_monitoring_location_arguments.Rd => get_monitoring_location_arguments.Rd} (97%) diff --git a/NAMESPACE b/NAMESPACE index 47f4a228f..e8c305dc2 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -15,6 +15,7 @@ export(create_NWIS_bib) export(create_WQP_bib) export(findNLDI) export(getWebServiceData) +export(get_monitoring_location_arguments) export(get_nldi_sources) export(get_ogc_params) export(importNGWMN) @@ -23,7 +24,6 @@ export(importWQP) export(importWaterML1) export(importWaterML2) export(is_dataRetrieval_user) -export(make_monitoring_location_arguments) export(pCodeToName) export(parameterCdFile) export(parse_WQP) diff --git a/R/make_monitoring_location_arguments.R b/R/make_monitoring_location_arguments.R index 769163c8b..43ca6d09e 100644 --- a/R/make_monitoring_location_arguments.R +++ b/R/make_monitoring_location_arguments.R @@ -58,10 +58,10 @@ #' @export #' @examples #' -#' make_monitoring_location_arguments(service = "daily", agency_name = "USGS") -#' make_monitoring_location_arguments(service = "field-measurements", +#' get_monitoring_location_arguments(service = "daily", agency_name = "USGS") +#' get_monitoring_location_arguments(service = "field-measurements", #' state_name = c("Ohio", "Wisconsin")) -make_monitoring_location_arguments <- function( +get_monitoring_location_arguments <- function( service = "daily", agency_code = NA_character_, agency_name = NA_character_, @@ -160,7 +160,7 @@ make_monitoring_location_arguments <- function( cleanup_arguments <- function(args, monitoring_location_arguments, service) { query_args <- do.call( - make_monitoring_location_arguments, + get_monitoring_location_arguments, c(monitoring_location_arguments, service = service) ) diff --git a/R/read_waterdata_continuous.R b/R/read_waterdata_continuous.R index 8d0aca640..def389673 100644 --- a/R/read_waterdata_continuous.R +++ b/R/read_waterdata_continuous.R @@ -33,9 +33,9 @@ #' The default (`NA`) will return all columns of the data. #' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. See `make_monitoring_location_arguments()` -#' to get a list of all possible arguments available. -#' @seealso [make_monitoring_location_arguments()] +#' monitoring_location_ids. See `?get_monitoring_location_arguments` +#' for available arguments. +#' @seealso [get_monitoring_location_arguments()] #' @inheritParams check_arguments_non_api #' @inheritParams check_arguments_api #' diff --git a/R/read_waterdata_daily.R b/R/read_waterdata_daily.R index 8eb34ba6c..7cd8e810f 100644 --- a/R/read_waterdata_daily.R +++ b/R/read_waterdata_daily.R @@ -27,11 +27,11 @@ #' The default (`NA`) will return all columns of the data. #' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. See `make_monitoring_location_arguments()` -#' to get a list of all possible arguments available. +#' monitoring_location_ids. See `?get_monitoring_location_arguments` +#' for available arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api -#' @seealso [make_monitoring_location_arguments()] +#' @seealso [get_monitoring_location_arguments()] #' @inherit read_waterdata_continuous details #' #' @examplesIf is_dataRetrieval_user() diff --git a/R/read_waterdata_field_measurements.R b/R/read_waterdata_field_measurements.R index c994aa5d6..166da199c 100644 --- a/R/read_waterdata_field_measurements.R +++ b/R/read_waterdata_field_measurements.R @@ -39,11 +39,11 @@ #' The default (`NA`) will return all columns of the data. #' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. See `make_monitoring_location_arguments()` -#' to get a list of all possible arguments available. +#' monitoring_location_ids. See `?get_monitoring_location_arguments` +#' for available arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api -#' @seealso [make_monitoring_location_arguments()] +#' @seealso [get_monitoring_location_arguments()] #' #' @inherit read_waterdata_continuous details #' diff --git a/R/read_waterdata_latest_continuous.R b/R/read_waterdata_latest_continuous.R index da859f870..f37ddb924 100644 --- a/R/read_waterdata_latest_continuous.R +++ b/R/read_waterdata_latest_continuous.R @@ -25,11 +25,11 @@ #' The default (`NA`) will return all columns of the data. #' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. See `make_monitoring_location_arguments()` -#' to get a list of all possible arguments available. +#' monitoring_location_ids. See `?get_monitoring_location_arguments` +#' for available arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api -#' @seealso [make_monitoring_location_arguments()] +#' @seealso [get_monitoring_location_arguments()] #' #' @inherit read_waterdata_continuous details #' @examplesIf is_dataRetrieval_user() diff --git a/R/read_waterdata_latest_daily.R b/R/read_waterdata_latest_daily.R index 8a329c03d..aa415f6e6 100644 --- a/R/read_waterdata_latest_daily.R +++ b/R/read_waterdata_latest_daily.R @@ -27,11 +27,11 @@ #' The default (`NA`) will return all columns of the data. #' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. See `make_monitoring_location_arguments()` -#' to get a list of all possible arguments available. +#' monitoring_location_ids. See `?get_monitoring_location_arguments` +#' for available arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api -#' @seealso [make_monitoring_location_arguments()] +#' @seealso [get_monitoring_location_arguments()] #' @inherit read_waterdata_continuous details #' #' @examplesIf is_dataRetrieval_user() diff --git a/R/read_wateruse.R b/R/read_wateruse.R deleted file mode 100644 index 4b43a8a85..000000000 --- a/R/read_wateruse.R +++ /dev/null @@ -1,181 +0,0 @@ -#' Get USGS Water Use Data -#' -#' @description USGS's National Water Availability Assessment Data Companion -#' (NWDC) offers web services that provide access to national-scale USGS -#' modeled water availability data underlying the National Water Availability -#' Assessment. More information at \url{https://water.usgs.gov/nwaa-data}. -#' -#' @export -#' @param model See model IDs on the NWDC data catalog page. -#' Options are : "wu-public-supply-wd", "wu-thermoelectric", "wu-irrigation-cu", -#' "wu-irrigation-wd", and "wu-public-supply-cu" -#' \url{https://water.usgs.gov/nwaa-data/data-catalog} -#' @param variable See variable IDs on the NWDC data catalog page. -#' @param location Options : huc12, huc10, huc8, huc6, huc4, huc2, countyCd, stateCd -#' Locations can be visualized with the Spatial Extent Viewer. Only one location -#' can be queried at a time. All data are returned on a HUC12 spatial resolution. -#' When a queried location contains more than the maximum number of HUC12s -#' allowed per page or file (defined under limit below), multiple pages or files -#' will be returned. All huc12, huc10, and countyCd location queries return a -#' single page or file. All huc2 location queries return multiple pages or files. -#' All other (huc8, huc6, huc4, stateCd) location queries may or may not return -#' multiple pages or files, depending on their size. -#' @param timeres Options : monthly, annualcy, annualwy. -#' @param startdate Format : YYYY (for annual data) or YYYY-MM (for monthly data) -#' @param enddate Format : YYYY (for annual data) or YYYY-MM (for monthly data) -#' @param intersection Options : overlap, envelop -#' @param limit Defines the number of HUC12s returned per page or file. -#' Queries of locations containing more than the below maximum value of HUC12s -#' will return multiple pages or files (see location above for details). -#' @param attach_request logical, defaults to `r getOption("dataRetrieval.attach_request")`. -#' If set to `TRUE`, the full request sent to the Water Data API is attached -#' as an attribute to the data set. -#' @examplesIf is_dataRetrieval_user() -#' -#' \donttest{ -#' wu1 <- read_wateruse(model = "wu-public-supply-wd", -#' variable = c("pswdtot", "pswdgw", "pswdsw"), -#' location = "stateCd:RI", -#' startdate = "2020-01", -#' timeres = "monthly") -#' -#' wu2 <- read_wateruse(model = "wu-thermoelectric", -#' variable = c('tecufgw', 'tecufsw', 'tecuftot', -#' 'tewdfgw', 'tewdfsw', 'tewdftot', -#' 'tewdssw'), -#' location = "stateCd:RI", -#' startdate = "2020-01", -#' timeres = "monthly") -#' -#' wu3 <- read_wateruse(model = "wu-irrigation-cu", -#' variable = "irrcutot", -#' location = "stateCd:WI", -#' startdate = "2020-01", -#' timeres = "monthly") -#' -#' wu4 <- read_wateruse(model = "wu-irrigation-wd", -#' variable = c("irrwdtot", "irrwdgw", "irrwdsw"), -#' location = "huc2:04", -#' startdate = "2015", -#' timeres = "annualcy") -#' -#' wu5 <- read_wateruse(model = "wu-public-supply-cu", -#' variable = "pscutot", -#' location = "stateCd:WI", -#' startdate = "2020", -#' timeres = "annualwy") -#' } -read_wateruse <- function(model = NA_character_, - variable = NA_character_, - location = NA_character_, - timeres = NA_character_, - startdate = NA_character_, - enddate = NA_character_, - intersection = "overlap", - limit = 500, - attach_request = getOption("dataRetrieval.attach_request")){ - - match.arg(intersection, choices = c("overlap", "envelop"), several.ok = FALSE) - match.arg(model, choices = c("wu-public-supply-wd", - "wu-thermoelectric", - "wu-irrigation-cu", - "wu-irrigation-wd", - "wu-public-supply-cu"), several.ok = FALSE) - - match.arg(timeres, choices = c("monthly", "annualcy", "annualwy")) - - location_prefix <- sapply(strsplit(location, ":"), function(x) x[1]) - choices = c("huc12", "huc10", "huc8", "huc6", "huc4", "huc2", "countyCd", "stateCd") - - - if(!location_prefix %in% choices){ - stop("Invalid location argument.") - } - - if(limit > 500){ - limit <- 500 - message("limit was reset to 500 which is the maximum value for this service.") - } - - if(!is.character(variable)){ - stop("Invalid variable argument.") - } - - # Monthly needs XXXX-XX - if(timeres == "monthly"){ - if(!is.na(startdate) & !grepl("^[0-9]{4}-[0-9]{2}$", startdate, perl = TRUE)){ - stop("Invalid startdate argument.") - } - - if(!is.na(enddate) & !grepl("^[0-9]{4}-[0-9]{2}$", enddate, perl = TRUE)){ - stop("Invalid enddate argument.") - } - } else { # Annual needs XXXX - if(!is.na(startdate) & !grepl("^[0-9]{4}$", startdate, perl = TRUE)){ - stop("Invalid startdate argument.") - } - - if(!is.na(enddate) & !grepl("^[0-9]{4}$", enddate, perl = TRUE)){ - stop("Invalid enddate argument.") - } - } - - args <- mget(names(formals())) - - args[["attach_request"]] <- NULL - - args <- Filter(Negate(anyNA), args) - - format <- "csv" - - baseURL <- httr2::request("https://api.water.usgs.gov/") |> - httr2::req_url_path_append("nwaa-data") |> - httr2::req_url_path_append("data") |> - httr2::req_user_agent(default_ua()) |> - httr2::req_headers(`Accept` = "application/json") |> - httr2::req_url_query(format = format ) |> - httr2::req_error(body = error_body) |> - httr2::req_timeout(seconds = 180) - - baseURL <- explode_query(baseURL, POST = FALSE, args, multi = "comma") - - message("Requesting:\n", baseURL$url) - - resps <- httr2::req_perform_iterative(baseURL, - next_req = next_req_url_wu_csv, - max_reqs = Inf, on_error = "stop") - - df <- resps |> - httr2::resps_successes() |> - httr2::resps_data(\(resp) data.table::fread(text = httr2::resp_body_string(resp), - data.table = FALSE, - colClasses = list(character = "huc12_id"))) - - if(attach_request){ - attr(df, "request") <- baseURL - } - attr(df, "queryTime") <- Sys.time() - return(df) - -} - -next_req_url_wu_csv <- function(resp, req){ - - headers <- httr2::resp_headers(resp) - if("link" %in% names(headers)){ - if(grepl(pattern = '\"next\"', headers$link)){ - next_url <- gsub(pattern = ".*<(.*)>.*", - replacement = "\\1", - x = headers$link) - next_url <- gsub(pattern = "https://water.usgs.gov", - replacement = "https://api.water.usgs.gov", - x = next_url) - return(httr2::req_url(req = req, url = next_url)) - } - } - return(NULL) -} - - - - diff --git a/man/make_monitoring_location_arguments.Rd b/man/get_monitoring_location_arguments.Rd similarity index 97% rename from man/make_monitoring_location_arguments.Rd rename to man/get_monitoring_location_arguments.Rd index 802efdda2..fbb61a6b6 100644 --- a/man/make_monitoring_location_arguments.Rd +++ b/man/get_monitoring_location_arguments.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/make_monitoring_location_arguments.R -\name{make_monitoring_location_arguments} -\alias{make_monitoring_location_arguments} +\name{get_monitoring_location_arguments} +\alias{get_monitoring_location_arguments} \title{Get Monitoring Location Arguments} \usage{ -make_monitoring_location_arguments( +get_monitoring_location_arguments( service = "daily", agency_code = NA_character_, agency_name = NA_character_, @@ -152,7 +152,7 @@ when using the \code{monitoring_location_arguments} argument. } \examples{ -make_monitoring_location_arguments(service = "daily", agency_name = "USGS") -make_monitoring_location_arguments(service = "field-measurements", +get_monitoring_location_arguments(service = "daily", agency_name = "USGS") +get_monitoring_location_arguments(service = "field-measurements", state_name = c("Ohio", "Wisconsin")) } diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index 55f87fd91..53035a4d3 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -92,8 +92,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. See \code{make_monitoring_location_arguments()} -to get a list of all possible arguments available.} +monitoring_location_ids. See \code{?get_monitoring_location_arguments} +for available arguments.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -214,5 +214,5 @@ time_df <- data.frame(start = time_chunks[-length(time_chunks)], \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +\code{\link[=get_monitoring_location_arguments]{get_monitoring_location_arguments()}} } diff --git a/man/read_waterdata_daily.Rd b/man/read_waterdata_daily.Rd index 6f35753b5..4e982ca9c 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -97,8 +97,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. See \code{make_monitoring_location_arguments()} -to get a list of all possible arguments available.} +monitoring_location_ids. See \code{?get_monitoring_location_arguments} +for available arguments.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -200,5 +200,5 @@ dv_dane <- read_waterdata_daily( \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +\code{\link[=get_monitoring_location_arguments]{get_monitoring_location_arguments()}} } diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index 4adee87cc..2565e2dcf 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -120,8 +120,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. See \code{make_monitoring_location_arguments()} -to get a list of all possible arguments available.} +monitoring_location_ids. See \code{?get_monitoring_location_arguments} +for available arguments.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -219,5 +219,5 @@ dane <- read_waterdata_field_measurements( \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +\code{\link[=get_monitoring_location_arguments]{get_monitoring_location_arguments()}} } diff --git a/man/read_waterdata_latest_continuous.Rd b/man/read_waterdata_latest_continuous.Rd index ea1da5b8d..8921a917a 100644 --- a/man/read_waterdata_latest_continuous.Rd +++ b/man/read_waterdata_latest_continuous.Rd @@ -92,8 +92,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. See \code{make_monitoring_location_arguments()} -to get a list of all possible arguments available.} +monitoring_location_ids. See \code{?get_monitoring_location_arguments} +for available arguments.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -185,5 +185,5 @@ dane <- read_waterdata_latest_continuous( \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +\code{\link[=get_monitoring_location_arguments]{get_monitoring_location_arguments()}} } diff --git a/man/read_waterdata_latest_daily.Rd b/man/read_waterdata_latest_daily.Rd index bdf08ab6b..2ac341a0a 100644 --- a/man/read_waterdata_latest_daily.Rd +++ b/man/read_waterdata_latest_daily.Rd @@ -97,8 +97,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. See \code{make_monitoring_location_arguments()} -to get a list of all possible arguments available.} +monitoring_location_ids. See \code{?get_monitoring_location_arguments} +for available arguments.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -183,5 +183,5 @@ dane <- read_waterdata_latest_daily( \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +\code{\link[=get_monitoring_location_arguments]{get_monitoring_location_arguments()}} } diff --git a/man/read_waterdata_latest_field_measurements.Rd b/man/read_waterdata_latest_field_measurements.Rd index 33f723e65..1c541ad5e 100644 --- a/man/read_waterdata_latest_field_measurements.Rd +++ b/man/read_waterdata_latest_field_measurements.Rd @@ -93,8 +93,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. See \code{make_monitoring_location_arguments()} -to get a list of all possible arguments available.} +monitoring_location_ids. See \code{?get_monitoring_location_arguments} +for available arguments.} \item{convertType}{logical, defaults to TRUE. If \code{TRUE}, the function will convert the data to dates, any qualifiers to string @@ -170,5 +170,5 @@ dane <- read_waterdata_latest_field_measurements( \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +\code{\link[=get_monitoring_location_arguments]{get_monitoring_location_arguments()}} } diff --git a/man/read_waterdata_peaks.Rd b/man/read_waterdata_peaks.Rd index 4a758af80..42b25d0e7 100644 --- a/man/read_waterdata_peaks.Rd +++ b/man/read_waterdata_peaks.Rd @@ -106,8 +106,8 @@ Southern-most latitude, Eastern-most longitude, Northern-most longitude).} \item{\dots}{Arguments that can be queried, but are not returned. These are used as alternatives to specifying specific -monitoring_location_ids. See \code{make_monitoring_location_arguments()} -to get a list of all possible arguments available.} +monitoring_location_ids. See \code{?get_monitoring_location_arguments} +for available arguments.} \item{allow_incomplete_dates}{Specifically in the peaks data, exact peak dates are not always known. Sometimes peaks are known just for the year, sometimes @@ -197,5 +197,5 @@ incomplete_dates_allowed$time \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=make_monitoring_location_arguments]{make_monitoring_location_arguments()}} +\code{\link[=get_monitoring_location_arguments]{get_monitoring_location_arguments()}} } From d7a9c01881e9acb51e1acd27dcabeb61ce8066e0 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Mon, 3 Aug 2026 16:02:34 -0500 Subject: [PATCH 59/71] missed a few commits --- NAMESPACE | 1 - R/read_waterdata_latest_field.R | 6 +-- R/read_waterdata_peaks.R | 6 +-- man/read_wateruse.Rd | 96 --------------------------------- 4 files changed, 6 insertions(+), 103 deletions(-) delete mode 100644 man/read_wateruse.Rd diff --git a/NAMESPACE b/NAMESPACE index e8c305dc2..002c070fb 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -66,7 +66,6 @@ export(read_waterdata_samples) export(read_waterdata_stats_daterange) export(read_waterdata_stats_por) export(read_waterdata_ts_meta) -export(read_wateruse) export(renameNWISColumns) export(setAccess) export(stateCd) diff --git a/R/read_waterdata_latest_field.R b/R/read_waterdata_latest_field.R index 20f865795..6f25d631d 100644 --- a/R/read_waterdata_latest_field.R +++ b/R/read_waterdata_latest_field.R @@ -27,11 +27,11 @@ #' The default (`NA`) will return all columns of the data. #' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. See `make_monitoring_location_arguments()` -#' to get a list of all possible arguments available. +#' monitoring_location_ids. See `?get_monitoring_location_arguments` +#' for available arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api -#' @seealso [make_monitoring_location_arguments()] +#' @seealso [get_monitoring_location_arguments()] #' @inherit read_waterdata_continuous details #' #' @examplesIf is_dataRetrieval_user() diff --git a/R/read_waterdata_peaks.R b/R/read_waterdata_peaks.R index 871d7f50f..dcb84b8b4 100644 --- a/R/read_waterdata_peaks.R +++ b/R/read_waterdata_peaks.R @@ -38,11 +38,11 @@ #' month stored on January 1. Default is `FALSE`. #' @param \dots Arguments that can be queried, #' but are not returned. These are used as alternatives to specifying specific -#' monitoring_location_ids. See `make_monitoring_location_arguments()` -#' to get a list of all possible arguments available. +#' monitoring_location_ids. See `?get_monitoring_location_arguments` +#' for available arguments. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api -#' @seealso [make_monitoring_location_arguments()] +#' @seealso [get_monitoring_location_arguments()] #' #' @inherit read_waterdata_continuous details #' diff --git a/man/read_wateruse.Rd b/man/read_wateruse.Rd deleted file mode 100644 index 96affc46c..000000000 --- a/man/read_wateruse.Rd +++ /dev/null @@ -1,96 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/read_wateruse.R -\name{read_wateruse} -\alias{read_wateruse} -\title{Get USGS Water Use Data} -\usage{ -read_wateruse( - model = NA_character_, - variable = NA_character_, - location = NA_character_, - timeres = NA_character_, - startdate = NA_character_, - enddate = NA_character_, - intersection = "overlap", - limit = 500, - attach_request = getOption("dataRetrieval.attach_request") -) -} -\arguments{ -\item{model}{See model IDs on the NWDC data catalog page. -Options are : "wu-public-supply-wd", "wu-thermoelectric", "wu-irrigation-cu", -"wu-irrigation-wd", and "wu-public-supply-cu" -\url{https://water.usgs.gov/nwaa-data/data-catalog}} - -\item{variable}{See variable IDs on the NWDC data catalog page.} - -\item{location}{Options : huc12, huc10, huc8, huc6, huc4, huc2, countyCd, stateCd -Locations can be visualized with the Spatial Extent Viewer. Only one location -can be queried at a time. All data are returned on a HUC12 spatial resolution. -When a queried location contains more than the maximum number of HUC12s -allowed per page or file (defined under limit below), multiple pages or files -will be returned. All huc12, huc10, and countyCd location queries return a -single page or file. All huc2 location queries return multiple pages or files. -All other (huc8, huc6, huc4, stateCd) location queries may or may not return -multiple pages or files, depending on their size.} - -\item{timeres}{Options : monthly, annualcy, annualwy.} - -\item{startdate}{Format : YYYY (for annual data) or YYYY-MM (for monthly data)} - -\item{enddate}{Format : YYYY (for annual data) or YYYY-MM (for monthly data)} - -\item{intersection}{Options : overlap, envelop} - -\item{limit}{Defines the number of HUC12s returned per page or file. -Queries of locations containing more than the below maximum value of HUC12s -will return multiple pages or files (see location above for details).} - -\item{attach_request}{logical, defaults to TRUE. -If set to \code{TRUE}, the full request sent to the Water Data API is attached -as an attribute to the data set.} -} -\description{ -USGS's National Water Availability Assessment Data Companion -(NWDC) offers web services that provide access to national-scale USGS -modeled water availability data underlying the National Water Availability -Assessment. More information at \url{https://water.usgs.gov/nwaa-data}. -} -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} - -\donttest{ -wu1 <- read_wateruse(model = "wu-public-supply-wd", - variable = c("pswdtot", "pswdgw", "pswdsw"), - location = "stateCd:RI", - startdate = "2020-01", - timeres = "monthly") - -wu2 <- read_wateruse(model = "wu-thermoelectric", - variable = c('tecufgw', 'tecufsw', 'tecuftot', - 'tewdfgw', 'tewdfsw', 'tewdftot', - 'tewdssw'), - location = "stateCd:RI", - startdate = "2020-01", - timeres = "monthly") - -wu3 <- read_wateruse(model = "wu-irrigation-cu", - variable = "irrcutot", - location = "stateCd:WI", - startdate = "2020-01", - timeres = "monthly") - -wu4 <- read_wateruse(model = "wu-irrigation-wd", - variable = c("irrwdtot", "irrwdgw", "irrwdsw"), - location = "huc2:04", - startdate = "2015", - timeres = "annualcy") - -wu5 <- read_wateruse(model = "wu-public-supply-cu", - variable = "pscutot", - location = "stateCd:WI", - startdate = "2020", - timeres = "annualwy") -} -\dontshow{\}) # examplesIf} -} From bf1de24f872218700afa43bce4bc45e7f8f41b0c Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 4 Aug 2026 07:35:00 -0500 Subject: [PATCH 60/71] Moving this to next release --- tests/testthat/tests_wateruse.R | 52 --------------------------------- 1 file changed, 52 deletions(-) delete mode 100644 tests/testthat/tests_wateruse.R diff --git a/tests/testthat/tests_wateruse.R b/tests/testthat/tests_wateruse.R deleted file mode 100644 index a908de63f..000000000 --- a/tests/testthat/tests_wateruse.R +++ /dev/null @@ -1,52 +0,0 @@ -context("Water Use functions") - -test_that("Water Use retrievals working", { - testthat::skip_on_cran() - testthat::skip_on_ci() - - vars <- c("pswdtot", "pswdgw", "pswdsw") - wu1 <- read_wateruse(model = "wu-public-supply-wd", - variable = vars, - location = "stateCd:RI", - startdate = "2020-01", - timeres = "monthly") - - expect_all_true(paste0(vars, "_mgd") %in% names(wu1)) - - expect_error(read_wateruse(model = "wu-public-supply-wd", - variable = c("pswdtot", "pswdgw", "pswdsw"), - location = "stateCd:RI", - startdate = "2020", #wrong type of startdate - timeres = "monthly")) - - wu2 <- read_wateruse(model = "wu-thermoelectric", - variable = c('tecufgw'), - location = "stateCd:RI", - startdate = "2020-01", - timeres = "monthly") - - expect_all_true(paste0("tecufgw", "_mgd") %in% names(wu2)) - - wu3 <- read_wateruse(model = "wu-irrigation-cu", - variable = "irrcutot", - location = "stateCd:WI", - startdate = "2020-01", - timeres = "monthly") - - expect_all_true(paste0("irrcutot", "_mgd") %in% names(wu3)) - - vars <- c("irrwdtot", "irrwdgw", "irrwdsw") - wu4 <- read_wateruse(model = "wu-irrigation-wd", - variable = vars, - location = "huc2:04", - startdate = "2015", - timeres = "annualcy") - expect_all_true(paste0(vars, "_mgd") %in% names(wu4)) - - wu5 <- read_wateruse(model = "wu-public-supply-cu", - variable = "pscutot", - location = "stateCd:WI", - startdate = "2020", - timeres = "annualwy") - expect_all_true(paste0("pscutot", "_mgd") %in% names(wu5)) -}) From f71ceb6b0ecd5fe11cf35433967ebc0c2f7081a6 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 4 Aug 2026 07:43:57 -0500 Subject: [PATCH 61/71] update News --- NEWS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index a7d1824fa..93ccdc939 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,7 +2,6 @@ dataRetrieval 2.7.26 =================== * Added suite of read_ngwmn to access new National Groundwater Monitoring Network API. -* Added read_wateruse to access USGS's National Water Availability Assessment Data Companion API service. * Created make_monitoring_location_arguments to help users understand what new optional arguments are available in many of the read_waterdata functions. * Added ability to use `...` in the Water Data functions for: daily, latest-continuous, field-measurements, latest-daily, latest-field-measurements, continuous, and peaks. The "..." argument can now accept any parameter that is output from the make_monitoring_location_arguments function. From 6a59ab645c755984aae81b415f9524ab040991d4 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 4 Aug 2026 07:56:18 -0500 Subject: [PATCH 62/71] Getting CRAN ready --- DESCRIPTION | 2 +- _pkgdown.yml | 4 ---- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 4df9e8d4c..dba89ba8c 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: dataRetrieval Type: Package Title: Retrieval Functions for USGS and EPA Hydrology and Water Quality Data -Version: 2.7.25.9000 +Version: 2.7.26 Authors@R: c( person("Laura", "DeCicco", role = c("aut","cre"), email = "ldecicco@usgs.gov", diff --git a/_pkgdown.yml b/_pkgdown.yml index 86ee1aadc..9aee75c6d 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -135,10 +135,6 @@ reference: contents: - findNLDI - get_nldi_sources - - title: National Water Availability Assessment Data - desc: Functions to get Water Use data - contents: - - read_wateruse - title: Import data desc: Functions to import different data formats contents: From 5b30b41bbd1e1dc55eab5a3efad67a19b6d5d9d0 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 4 Aug 2026 08:36:46 -0500 Subject: [PATCH 63/71] rename --- _pkgdown.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_pkgdown.yml b/_pkgdown.yml index 9aee75c6d..d40aaa82a 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -95,7 +95,7 @@ reference: - read_waterdata_peaks - summarize_waterdata_samples - check_waterdata_sample_params - - make_monitoring_location_arguments + - get_monitoring_location_arguments - title: National Water Information System (NWIS) desc: Functions to retrieve (USGS) NWIS data. These will be slowly phased out and replaced with the read_waterdata family of functions. contents: From a9a8d004247a3aac430107a16956d91993777e05 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 4 Aug 2026 08:55:06 -0500 Subject: [PATCH 64/71] fix news --- NEWS.md | 2 +- ...location_arguments.R => get_monitoring_location_arguments.R} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename R/{make_monitoring_location_arguments.R => get_monitoring_location_arguments.R} (100%) diff --git a/NEWS.md b/NEWS.md index 93ccdc939..f1ca1457d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,7 +2,7 @@ dataRetrieval 2.7.26 =================== * Added suite of read_ngwmn to access new National Groundwater Monitoring Network API. -* Created make_monitoring_location_arguments to help users understand +* Created get_monitoring_location_arguments to help users understand what new optional arguments are available in many of the read_waterdata functions. * Added ability to use `...` in the Water Data functions for: daily, latest-continuous, field-measurements, latest-daily, latest-field-measurements, continuous, and peaks. The "..." argument can now accept any parameter that is output from the make_monitoring_location_arguments function. * Added "q" argument to read_waterdata_monitoring_location. Full-text search across the most relevant text fields for this collection (e.g. site name, identifier, number, state, county, and site type). diff --git a/R/make_monitoring_location_arguments.R b/R/get_monitoring_location_arguments.R similarity index 100% rename from R/make_monitoring_location_arguments.R rename to R/get_monitoring_location_arguments.R From 638351a8954083269df9be16f181fc4b2fa822a5 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 4 Aug 2026 12:41:17 -0500 Subject: [PATCH 65/71] use time_periods --- R/deal_with_empty.R | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/R/deal_with_empty.R b/R/deal_with_empty.R index 30b05eb02..554624284 100644 --- a/R/deal_with_empty.R +++ b/R/deal_with_empty.R @@ -42,17 +42,7 @@ deal_with_empty <- function( return_list <- lapply(return_list, as.character) names(return_list) <- properties - single_params <- c( - "datetime", - "last_modified", - "begin", - "end", - "time", - "datetime", - "sample_time" - ) - - for (i in single_params) { + for (i in time_periods) { if (i %in% names(return_list)) { return_list[[i]] <- as.POSIXct(as.character(), origin = "1970-01-01") } From d1062d886528099fc33cddc6ab3d61f6b3e4b6b2 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 4 Aug 2026 13:04:59 -0500 Subject: [PATCH 66/71] Fix status --- man/get_monitoring_location_arguments.Rd | 2 +- vignettes/Status.Rmd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/man/get_monitoring_location_arguments.Rd b/man/get_monitoring_location_arguments.Rd index fbb61a6b6..d13f54561 100644 --- a/man/get_monitoring_location_arguments.Rd +++ b/man/get_monitoring_location_arguments.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/make_monitoring_location_arguments.R +% Please edit documentation in R/get_monitoring_location_arguments.R \name{get_monitoring_location_arguments} \alias{get_monitoring_location_arguments} \title{Get Monitoring Location Arguments} diff --git a/vignettes/Status.Rmd b/vignettes/Status.Rmd index 36aa1c930..30781563a 100644 --- a/vignettes/Status.Rmd +++ b/vignettes/Status.Rmd @@ -181,6 +181,6 @@ Currently, any "qw" data summaries provided by `whatNWISdata` are very likely ou ## National Groundwater Monitoring Network -Coming soon, a new new access point for the National Groundwater Monitoring Network. The original `readNGWMNdata` functions have been broken for some time. `read_waterdata_use` is currently in development! +A new access point for the National Groundwater Monitoring Network. The original `readNGWMNdata` functions have been broken for some time, the `read_ngwmn` set of functions are now available to access this data. From cd0e2d45b41e0ab15996043d375c5ef3f3482339 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 4 Aug 2026 13:52:19 -0500 Subject: [PATCH 67/71] still deprecated --- R/readNWISunit.R | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/R/readNWISunit.R b/R/readNWISunit.R index 0478f0b02..42ef26bc0 100644 --- a/R/readNWISunit.R +++ b/R/readNWISunit.R @@ -454,17 +454,17 @@ readNWISstat <- function( #' County and state fields will be included as appropriate. #' #' @export -readNWISuse <- function(stateCd, - countyCd, - years = "ALL", - categories = "ALL", - convertType = TRUE, - transform = FALSE) { - - .Deprecated(new = "read_waterdata_use", - package = "dataRetrieval", - msg = "NWIS servers for water use have been decommission. New functions are being developed.") +readNWISuse <- function( + stateCd, + countyCd, + years = "ALL", + categories = "ALL", + convertType = TRUE, + transform = FALSE +) { + .Deprecated( + package = "dataRetrieval", + msg = "NWIS servers for water use have been decommission. New functions are being developed." + ) return(NULL) - - } From 8a6307b065cbaea475b65e53a5c72b7aac20a426 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 4 Aug 2026 13:58:25 -0500 Subject: [PATCH 68/71] Update R/get_monitoring_location_arguments.R Co-authored-by: Elise Hinman <121896266+ehinman@users.noreply.github.com> --- R/get_monitoring_location_arguments.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/get_monitoring_location_arguments.R b/R/get_monitoring_location_arguments.R index 43ca6d09e..9f07b65a8 100644 --- a/R/get_monitoring_location_arguments.R +++ b/R/get_monitoring_location_arguments.R @@ -5,7 +5,7 @@ #' of possible arguments that can be used as input to the `monitoring_location_arguments` #' argument (found in many of the read_waterdata functions). This function #' also is used to check that user supplied available parameters to their queries -#' when using the `monitoring_location_arguments` argument. +#' when using the `get_monitoring_location_arguments` argument. #' #' @param service Endpoint to check arguments against. Possible values are #' "daily", "latest-continuous", "field-measurements", "latest-daily", From 55536268ac32a77a410849df056bb4e73d41cdc1 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 4 Aug 2026 13:58:35 -0500 Subject: [PATCH 69/71] Update R/get_monitoring_location_arguments.R Co-authored-by: Elise Hinman <121896266+ehinman@users.noreply.github.com> --- R/get_monitoring_location_arguments.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/get_monitoring_location_arguments.R b/R/get_monitoring_location_arguments.R index 9f07b65a8..1167477d7 100644 --- a/R/get_monitoring_location_arguments.R +++ b/R/get_monitoring_location_arguments.R @@ -2,7 +2,7 @@ #' #' Many read_waterdata functions have a long list of arguments that can be used #' to find sites that have data. Users can use this function to create a list -#' of possible arguments that can be used as input to the `monitoring_location_arguments` +#' of possible arguments that can be used as input to the `get_monitoring_location_arguments` #' argument (found in many of the read_waterdata functions). This function #' also is used to check that user supplied available parameters to their queries #' when using the `get_monitoring_location_arguments` argument. From cb9b6ad09b782325ae124297c7fc8eb003153dcc Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 5 Aug 2026 08:28:50 -0500 Subject: [PATCH 70/71] cleanup message --- R/get_monitoring_location_arguments.R | 9 ++++----- man/get_monitoring_location_arguments.Rd | 9 ++++----- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/R/get_monitoring_location_arguments.R b/R/get_monitoring_location_arguments.R index 1167477d7..57103f7e7 100644 --- a/R/get_monitoring_location_arguments.R +++ b/R/get_monitoring_location_arguments.R @@ -1,11 +1,10 @@ #' Get Monitoring Location Arguments #' #' Many read_waterdata functions have a long list of arguments that can be used -#' to find sites that have data. Users can use this function to create a list -#' of possible arguments that can be used as input to the `get_monitoring_location_arguments` -#' argument (found in many of the read_waterdata functions). This function -#' also is used to check that user supplied available parameters to their queries -#' when using the `get_monitoring_location_arguments` argument. +#' to find sites that have data. Users can use this function as a reference +#' of possible arguments that can be used as input. +#' Additionally, this function is also used by other functions to check that +#' the user supplied parameters are available to their queries #' #' @param service Endpoint to check arguments against. Possible values are #' "daily", "latest-continuous", "field-measurements", "latest-daily", diff --git a/man/get_monitoring_location_arguments.Rd b/man/get_monitoring_location_arguments.Rd index d13f54561..57a146af7 100644 --- a/man/get_monitoring_location_arguments.Rd +++ b/man/get_monitoring_location_arguments.Rd @@ -144,11 +144,10 @@ making sure your calls are accepted by the service, set to \code{TRUE}.} } \description{ Many read_waterdata functions have a long list of arguments that can be used -to find sites that have data. Users can use this function to create a list -of possible arguments that can be used as input to the \code{monitoring_location_arguments} -argument (found in many of the read_waterdata functions). This function -also is used to check that user supplied available parameters to their queries -when using the \code{monitoring_location_arguments} argument. +to find sites that have data. Users can use this function as a reference +of possible arguments that can be used as input. +Additionally, this function is also used by other functions to check that +the user supplied parameters are available to their queries } \examples{ From 2208c4dcced7091a2644c36320a936eee10c9550 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 5 Aug 2026 09:37:08 -0500 Subject: [PATCH 71/71] spelling --- R/readNWISunit.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/readNWISunit.R b/R/readNWISunit.R index 42ef26bc0..515054de8 100644 --- a/R/readNWISunit.R +++ b/R/readNWISunit.R @@ -464,7 +464,7 @@ readNWISuse <- function( ) { .Deprecated( package = "dataRetrieval", - msg = "NWIS servers for water use have been decommission. New functions are being developed." + msg = "NWIS servers for water use have been decommissioned. New functions are being developed." ) return(NULL) }