Added a touched arugment to RomFeature() and added an outaszoo argument to om_get_rundata to allow data frames to be returned

Author: COBrogan

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: hydrotools
 Title: Data processing and accessors for VAHydro
-Version: 1.0.10
+Version: 1.0.11
 Authors@R: person("Robert", "Burgholzer", email = "rburghol@vt.edu", role = c("aut", "cre"))
 Description: Provides set of reference classes and functions to assemble a component based simulation for constructing time-based model simulations.
 Depends: 

R/RomFeature.R

@@ -233,23 +233,27 @@ RomFeature <- R6Class(
     #'   meteorology varkeys include 'prism_mod_daily', 'daymet_mod_daily',
     #'   'nldas2_obs_hourly', 'nldas2_precip_hourly_tiled_16x16',
     #'   'nldas2_precip_daily', 'amalgamate_simple_lm', 'amalgamate_storm_vol'
-    #' @param starttime begin tstime to limit query (default FALSE to remove a
+    #' @param starttime begin date-time to limit query (default FALSE to remove a
     #'   tstime filter)
-    #' @param endtime last tsendtime to limit query (default FALSE to remove a
-    #'   tsendtime filter)
+    #' @param endtime last date-time to limit query (default to Sys.Date())
     #' @param band which raster band to query (default = 1)?
     #' @param aggregate Should data be aggregated and if so, how? FALSE will
     #'   return 1 record for every date. Otheriwse, can use basic aggregate
     #'   functions like mean, min, max to summarize data
     #' @param metric default mean, which aspect of the ST_SummaryStats() to return
+    #' @param touched Defaults to FALSE. Should PostGIS ST_Clip() use the
+    #'   touched argument to return all raster cells touched by the feature? Or,
+    #'   if FALSE, should only pixels that have centroids within the feature be
+    #'   considered?
     #' @return dataframe of timeseries values
     get_raster_ts = function(
         varkey = 'prism_mod_daily',
         starttime = FALSE,
         endtime = Sys.Date(),
         band = '1',
         aggregate = FALSE,
-        metric = 'mean'
+        metric = 'mean',
+        touched = FALSE
       ) {
       # looks at the table dh_timeseries_weather
       # coverage raster summary
@@ -269,14 +273,21 @@ RomFeature <- R6Class(
       }
       #If the user wishes to apply an aggregate function, group the data by the
       #featureid and apply the aggregate and metric arguments. Otherwise, just
-      #get the metric from st_summarystats
+      #get the metric from st_summarystats. The data will be clipped to the
+      #feature and the user can choose to apply the touched argument from
+      #postGIS st_Clip
+      if(touched){
+        clipSQL <- paste0("st_clip(met.rast, fgeo.dh_geofield_geom,touched => true)")
+      }else{
+        clipSQL <- paste0("st_clip(met.rast, fgeo.dh_geofield_geom,touched => false)")
+      }
       if (!is.logical(aggregate)) {
-        rastercalc = fn$paste0("$aggregate((ST_summarystats(st_clip(met.rast, fgeo.dh_geofield_geom), 1, TRUE)).$metric)")
+        rastercalc = fn$paste0("$aggregate((ST_summarystats($clipSQL, 1, TRUE)).$metric)")
         groupby = "GROUP BY met.featureid"
         startcol = "to_timestamp(min(met.tsendtime))"
         endcol = "to_timestamp(max(met.tsendtime))"
       } else {
-        rastercalc = fn$paste0("(ST_summarystats(st_clip(met.rast, fgeo.dh_geofield_geom), 1, TRUE)).$metric")
+        rastercalc = fn$paste0("(ST_summarystats($clipSQL, 1, TRUE)).$metric")
         groupby = ""
         startcol = "to_timestamp(met.tsendtime)"
         endcol = "to_timestamp(met.tsendtime)"

R/om_get_rundata.R

@@ -3,8 +3,10 @@
 #'   particular model and run ID (scenario ID).
 #' @details A wrapper of \code{hydrotools::fn_get_runfile()}. This function
 #'   returns the results in a zoo (see zoo::zoo()) that has the timestamp as the
-#'   index. See \code{hydrotools::fn_get_runfile()} for more details.
-#'
+#'   index. See \code{hydrotools::fn_get_runfile()} for more details. If
+#'   outaszoo is TRUE, the output will be a zoo TS with numeric mode. Please note
+#'   that zoo's are matrices and cannot hold more than one data type such that
+#'   character and date fields will be set to NA.
 #' @param elid integer OM element connection ID e.g. the original OM model ID
 #' @param runid integer run id representing the scenario. Ask the modeling team
 #'   for scenario IDs if you are unsure otherwise see the WSPA Shiny Dashboard
@@ -17,15 +19,18 @@
 #' @param cleanup Logical. Should the function delete the log file create for
 #'   the cached argument? If this is TRUE, the .log files will be deleted after
 #'   download from OM server
+#' @param outaszoo boolean return as a zoo timeseries with numeric mode if TRUE,
+#'   or as data frame if FALSE. Default is TRUE.
 #' @return data.frame of model results
 #' @export om_get_rundata
 #' @examples #om_get_rundata(72446, 600, site=omsite)
 om_get_rundata <- function(elid, runid, site='http://deq2.bse.vt.edu',
                            cached=FALSE, hydrowarmup=TRUE,
-                           cleanup = FALSE) {
+                           cleanup = FALSE,  outaszoo = TRUE) {
   # replace this with a single function that grabs
   # a hydro model for summarization and slims it down
-  dat <- fn_get_runfile(elid, runid, 37, site,  cached = FALSE, cleanup = cleanup)
+  dat <- fn_get_runfile(elid, runid, 37, site,  cached = FALSE, cleanup = cleanup,
+                        outaszoo = outaszoo)
   syear = as.integer(min(dat$year))
   eyear = as.integer(max(dat$year))
   if ((hydrowarmup == TRUE) & (syear < (eyear - 2))) {
@@ -47,9 +52,13 @@ om_get_rundata <- function(elid, runid, site='http://deq2.bse.vt.edu',
   edate <- as.POSIXct(edate,tz = "EST")
 
   #Get the window of interest from the timeseries
-  dat <- stats::window(dat, start = sdate, end = edate);
-  #Change mode of zoo to numeric e.g. Convert all fields to numeric
-  mode(dat) <- 'numeric'
+  if(outaszoo){
+    dat <- stats::window(dat, start = sdate, end = edate)
+    #Change mode of zoo to numeric e.g. Convert all fields to numeric
+    mode(dat) <- 'numeric'
+  }else{
+    dat <- dat[dat$timestamp >= sdate & dat$timestamp <= edate,]
+  }
 
   return(dat)
 }

README.md

@@ -109,6 +109,13 @@ Rob Burgholzer ([robert.burgholzer\@deq.virginia.gov](mailto:robert.burgholzer@d
 This package is in active development.
 
 ## Release notes
+### 1.0.11 01/07/2026
+1. Updated the documentation on `RomFeature$get_raster_ts()` to be more accurate
+for the starttime and endtime arguments. Additionally, added a `touched` argument
+to leverage the new options in PostGIS `ST_Clip()`
+2. Added an `outaszoo` argument to `om_get_rundata()` to allow data frames of
+model data to be returned.
+
 ### 1.0.10 12/15/2025
 1. Update elfgen wrappers to allow for more dynamic generation of NHDPlus flows.
 2. Added an `na.rm = TRUE` to the mean flows call in `om_flow_table()`