merging master updates to dev

DESCRIPTION

@@ -2,7 +2,7 @@ Package: RavenR
 Type: Package
 Title: Raven Hydrological Modelling Framework R Support and Analysis
 Version: 2.2.1
-Date: 2023-08-16
+Date: 2024-05-06
 Authors@R: c(
     person("Robert", "Chlumsky", email = "[email protected]", role = c("cre","aut"), comment = c(ORCID = "0000-0002-1303-5064")),
     person("James", "Craig", email = "[email protected]", role = c("ctb","aut"), comment = c(ORCID = "0000-0003-2715-7166")),
@@ -52,6 +52,6 @@ URL: https://github.com/rchlumsk/RavenR
 License: GPL-3
 Encoding: UTF-8
 LazyData: TRUE
-RoxygenNote: 7.2.2
+RoxygenNote: 7.3.1
 VignetteBuilder: knitr
 LinkingTo: Rcpp

NAMESPACE

@@ -16,6 +16,7 @@ export(rvn_apply_wyearly)
 export(rvn_apply_wyearly_which_max_xts)
 export(rvn_budyko_plot)
 export(rvn_calc_runoff_coeff)
+export(rvn_csv_read)
 export(rvn_cum_plot_flow)
 export(rvn_custom_output_plot)
 export(rvn_custom_read)
@@ -105,6 +106,7 @@ importFrom(cowplot,draw_label)
 importFrom(cowplot,ggdraw)
 importFrom(cowplot,plot_grid)
 importFrom(crayon,green)
+importFrom(dplyr,"%>%")
 importFrom(dplyr,across)
 importFrom(dplyr,all_of)
 importFrom(dplyr,as_tibble)

R/rvn_csv_read.R

@@ -0,0 +1,93 @@
+#' @title Read in generic Raven output csv files
+#'
+#' @description
+#' Reads in output csv files produced by Raven.
+#'
+#' @details
+#' Expects a full file path to the Raven output file.
+#'
+#' The timezone is provided by the tzone argument as "UTC" by default, and should be adjusted by
+#' the user to the local time zone as needed, based on the model run.
+#'
+#' @param ff full file path to the csv file
+#' @param tzone string indicating the timezone of the data in ff
+#' @param xtsformat boolean whether to return in xts format (if date and/or hour found)
+#' @return \item{data frame (as xts if set with \code{xtsformat}) read from the file}
+#' @seealso \code{\link{rvn_hyd_read}} for reading Hydrographs output files
+#'
+#' @examples
+#' # create full file path
+#' ff <- system.file("extdata","ReservoirStages.csv", package="RavenR")
+#'
+#' # read in the Reservoir file with the generic call
+#' myres <- rvn_csv_read(ff)
+#'
+#' # view contents
+#' head(myres)
+#'
+#' @export rvn_csv_read
+#' @importFrom xts xts
+#' @importFrom dplyr %>%
+#' @importFrom xts xts
+#' @importFrom utils read.csv
+rvn_csv_read <- function(ff=NA, tzone="UTC", xtsformat=TRUE) {
+
+  if (missing(ff)) {
+    stop("Requires the full file path to the Raven csv output file.")
+  }
+
+  #read output
+  dd <- read.csv(ff,header=TRUE,nrows=5)
+  # careful in date-time formats; excel can screw it up if csv is saved over. This works for
+  # an untouched Raven output file
+
+  cols <- colnames(dd)
+  classes <- rep(NA,length(cols))
+  if ("time" %in% cols) {
+    classes[which(cols=="time")] <- "integer"
+  }
+  if ("date" %in% cols) {
+    classes[which(cols=="date")] <- "Date"
+  }
+  if ("hour" %in% cols) {
+    classes[which(cols=="hour")] <- "character"
+  }
+
+  # re-read with specified colClasses
+  dd <- read.csv(ff,header=TRUE,colClasses = classes,na.strings=c("---",'NA'))
+
+  dt <- NULL
+  if ("date" %in% cols) {
+    if ("hour" %in% cols) {
+      dt <- as.POSIXct(paste(dd$date,dd$hour), format="%Y-%m-%d %H:%M:%S", tz=tzone)
+    } else {
+      dt <- as.Date(dd$date)
+    }
+    # check if dt converted properly
+    if (any(is.na(dt))) {
+      warning("date and time failed to convert from date and hour columns, please check file format.")
+      dt <- NULL
+    }
+  }
+
+  # change all dots to underscore
+  newcols <- cols %>%
+    gsub("\\.\\.\\.","\\.\\.",x=.) %>%
+    gsub("\\.\\.","\\.",x=.) %>%
+    gsub("\\.","_",x=.)
+
+  # trim all last underscores
+  for (i in 1:length(newcols)) {
+    if (rvn_substrRight(newcols[i],1) == "_") {
+      newcols[i] <- rvn_substrMRight(newcols[i],1)
+    }
+  }
+  colnames(dd) <- newcols
+
+  # change to xtsformat if desired
+  if (xtsformat & !is.null(dt)) {
+    dd <- xts(order.by=dt,x=dd)
+  }
+
+  return(dd)
+}

R/rvn_rvi_write_template.R

@@ -7,7 +7,7 @@
 #' @param filename Name of the rvi file, with extension (optional)
 #' @param overwrite boolean whether to overwrite file if it already exists (default \code{FALSE})
 #' @param writeheader boolean whether to write a header to the rvi file (default \code{TRUE})
-#' @param filetype File extension, Encoding, Raven version (e.g. "rvp ASCII Raven 2.9.1") (optional)
+#' @param filetype File extension, Encoding, Raven version (e.g. "rvp ASCII Raven v3.8") (optional)
 #' @param author Name of file author (optional)
 #' @param description File Description for header (e.g., Basin or project information, R script name) (optional)
 #'
@@ -19,7 +19,7 @@
 #' for ease of getting started with a model using Raven.
 #'
 #' The template_name parameter should be one of "UBCWM", "HBV-EC", "HBV-Light", "GR4J",
-#'  "CdnShield", "MOHYSE", "HMETS", "HYPR", "HYMOD", or "blended_v1".
+#'  "CdnShield", "MOHYSE", "HMETS", "HYPR", "HYMOD", "SAC-SMA", "blended", or "blended_v2".
 #'
 #' This function uses the same model template files that are provided in the Raven User's manual, Appendix D.
 #'
@@ -44,8 +44,8 @@ rvn_rvi_write_template <- function(template_name="UBCWM", filename=NULL,
                                    filetype="rvi ASCII Raven", author="RavenR",
                                    description=NULL) {
 
-  known_templates  <- c("UBCWM", "HBV-EC", "HBV-Light", "GR4J", "CdnShield", "MOHYSE",
-                        "HMETS", "HYPR", "HYMOD", "blended_v1")
+  known_templates  <- c("UBCWM", "HBV-EC", "HBV-Light", "GR4J", "CdnShield", "MOHYSE", "HMETS", "HYPR",
+                        "HYMOD", "SAC-SMA", "blended","blended_v2")
 
   if (is.null(template_name) | template_name %notin% known_templates) {
     stop("template_name must be one of the available model templates, see function details")
@@ -480,21 +480,52 @@ rvn_rvi_write_template <- function(template_name="UBCWM", filename=NULL,
 
 ",
 
-"blended_v1"="
+"SAC-SMA"="
 :StartDate    2000-01-01 00:00:00
 :Duration     365
 :TimeStep     1.0
 
-:PotentialMeltMethod     POTMELT_HMETS
+# Model options for SAC-SMA emulation
+#------------------------------------------------------------------------
+:PotentialMeltMethod     POTMELT_DEGREE_DAY
+:RainSnowFraction        RAINSNOW_DATA
+:Evaporation             PET_DATA
+:CatchmentRoute          ROUTE_DUMP
+:Routing                 ROUTE_NONE
 
-:RainSnowFraction        RAINSNOW_HBV        # RAINSNOW_DATA
-#:SWRadiationMethod      SW_RAD_NONE         # no radiation is faster
+:SoilModel               SOIL_MULTILAYER 7
 
-:Evaporation           PET_OUDIN
+:Alias UZ_T  SOIL[0]
+:Alias UZ_F  SOIL[1]
+:Alias LZ_T  SOIL[2]
+:Alias LZ_PF SOIL[3]
+:Alias LZ_PS SOIL[4]
 
+:HydrologicProcesses
+  :SnowBalance           SNOBAL_SIMPLE_MELT   SNOW          PONDED_WATER
+  :Precipitation         RAVEN_DEFAULT        ATMOS_PRECIP  MULTIPLE
+  :SoilEvaporation       SOILEVAP_SACSMA      MULTIPLE      ATMOSPHERE
+  :SoilBalance           SOILBAL_SACSMA       MULTIPLE      MULTIPLE
+  :OpenWaterEvaporation  OPEN_WATER_RIPARIAN  SURFACE_WATER ATMOSPHERE
+:EndHydrologicProcesses
+
+#
+
+",
+    "blended"="
+:StartDate    2000-01-01 00:00:00
+:Duration     365
+:TimeStep     1.0
+:Method              ORDERED_SERIES
+:Interpolation       INTERP_NEAREST_NEIGHBOR
+
+:PotentialMeltMethod     POTMELT_HMETS
+:RainSnowFraction        RAINSNOW_HBV
+:SWRadiationMethod       SW_RAD_NONE         # no radiation is faster
+:Evaporation             PET_DATA
 :CatchmentRoute          ROUTE_DUMP
 :Routing                 ROUTE_NONE
-:SoilModel               SOIL_MULTILAYER 3
+:SoilModel               SOIL_MULTILAYER 2
 
 :Alias DELAYED_RUNOFF CONVOLUTION[1]
 
@@ -504,13 +535,13 @@ rvn_rvi_write_template <- function(template_name="UBCWM", filename=NULL,
                 :Infiltration    INF_HMETS               PONDED_WATER   MULTIPLE
                 :Infiltration    INF_VIC_ARNO            PONDED_WATER   MULTIPLE
                 :Infiltration    INF_HBV                 PONDED_WATER   MULTIPLE
-  :EndProcessGroup CALCULATE_WTS 0.55556 0.5
+  :EndProcessGroup CALCULATE_WTS 0.556 0.5
                   :Overflow      OVERFLOW_RAVEN          SOIL[0]        DELAYED_RUNOFF
   :ProcessGroup #quickflow group
                 :Baseflow        BASE_LINEAR_ANALYTIC    SOIL[0]        SURFACE_WATER   # interflow, really
                 :Baseflow        BASE_VIC                SOIL[0]        SURFACE_WATER
                 :Baseflow        BASE_TOPMODEL           SOIL[0]        SURFACE_WATER
-  :EndProcessGroup CALCULATE_WTS 0.55556 0.5
+  :EndProcessGroup CALCULATE_WTS 0.556 0.5
   :Percolation                   PERC_LINEAR             SOIL[0]        SOIL[1]         # recharge
     :Overflow                    OVERFLOW_RAVEN          SOIL[1]        DELAYED_RUNOFF
   :Percolation                   PERC_LINEAR             SOIL[1]        SOIL[2]         # loss to deep gw
@@ -528,8 +559,66 @@ rvn_rvi_write_template <- function(template_name="UBCWM", filename=NULL,
                 :SnowBalance     SNOBAL_HMETS            MULTIPLE       MULTIPLE
                 :SnowBalance     SNOBAL_SIMPLE_MELT      SNOW           PONDED_WATER
                 :SnowBalance     SNOBAL_HBV              MULTIPLE       MULTIPLE
-  :EndProcessGroup CALCULATE_WTS 0.55556 0.5
+  :EndProcessGroup CALCULATE_WTS 0.556 0.5
 :EndHydrologicProcesses
+
+#
+
+",
+    "blended_v2"="
+:StartDate    2000-01-01 00:00:00
+:Duration     365
+:TimeStep     1.0
+:Method              ORDERED_SERIES
+
+:SoilModel               SOIL_MULTILAYER 3
+
+:Evaporation           PET_BLENDED
+:BlendedPETWeights PET_GRANGERGRAY 0.556 PET_HAMON 0.5 PET_PENMAN_MONTEITH
+
+:PotentialMeltMethod           POTMELT_BLENDED
+:BlendedPotMeltWeights POTMELT_HMETS 0.5 POTMELT_RESTRICTED
+
+:RainSnowFraction        RAINSNOW_HBV        # RAINSNOW_DATA
+:PrecipIceptFract   PRECIP_ICEPT_USER
+:CatchmentRoute          ROUTE_DUMP
+:Routing                 ROUTE_NONE
+
+:Alias DELAYED_RUNOFF CONVOLUTION[1]
+
+:HydrologicProcesses
+  :Precipitation                 RAVEN_DEFAULT           ATMOS_PRECIP   MULTIPLE
+  :CanopyDrip                    CANDRIP_RUTTER          CANOPY         PONDED_WATER
+  :Abstraction                   ABST_PERCENTAGE         PONDED_WATER   DEPRESSION
+  :OpenWaterEvaporation          OPEN_WATER_EVAP         DEPRESSION     ATMOSPHERE
+  :CanopyEvaporation             CANEVP_MAXIMUM          CANOPY         ATMOSPHERE
+  :CanopySnowEvap                CANEVP_MAXIMUM          CANOPY_SNOW    ATMOSPHERE
+  :Seepage                       SEEP_LINEAR             DEPRESSION     SOIL[1]
+  :Infiltration    INF_HMETS               PONDED_WATER   MULTIPLE
+         :Overflow      OVERFLOW_RAVEN          SOIL[0]        DELAYED_RUNOFF
+   :ProcessGroup #quickflow/interflow group
+                :Baseflow        BASE_POWER_LAW          SOIL[0]        SURFACE_WATER
+                :Baseflow        BASE_THRESH_POWER       SOIL[0]        SURFACE_WATER
+  :EndProcessGroup CALCULATE_WTS 0.5
+  :Percolation                   PERC_LINEAR             SOIL[0]        SOIL[1]         # recharge
+  :CapillaryRise                 CRISE_HBV               SOIL[1]        SOIL[0]
+  :Overflow                      OVERFLOW_RAVEN          SOIL[1]        DELAYED_RUNOFF
+  :Percolation                   PERC_LINEAR             SOIL[1]        SOIL[2]         # loss to deep gw
+  :CapillaryRise                 CRISE_HBV               SOIL[2]        SOIL[1]
+  :ProcessGroup #evaporation group
+                :SoilEvaporation SOILEVAP_ALL            SOIL[0]        ATMOSPHERE      # AET
+                :SoilEvaporation SOILEVAP_ROOT           SOIL[0]        ATMOSPHERE      # AET
+				:SoilEvaporation SOILEVAP_SEQUEN         SOIL[0]        ATMOSPHERE      # AET
+  :EndProcessGroup CALCULATE_WTS  0.556 0.5
+  :Convolve                      CONVOL_GAMMA            CONVOLUTION[0] SURFACE_WATER   # 'surface runoff'
+  :Convolve                      CONVOL_GAMMA_2          DELAYED_RUNOFF SURFACE_WATER   # 'delayed runoff'
+  :ProcessGroup #baseflow group
+        :Baseflow        BASE_POWER_LAW          SOIL[1]        SURFACE_WATER
+				:Baseflow        BASE_THRESH_POWER       SOIL[1]        SURFACE_WATER
+  :EndProcessGroup CALCULATE_WTS  0.5
+  :SnowBalance     SNOBAL_HBV              MULTIPLE       MULTIPLE
+:EndHydrologicProcesses
+
 #
 
 "

R/rvn_rvt_write_met.R

@@ -293,19 +293,9 @@ rvn_rvt_write_met <-  function(metdata, rvt_met_mapping=NULL, filenames=NULL, me
           writeLines(sprintf("  :Latitude %.6f", md$LAT[k]),fc)
           writeLines(sprintf("  :Longitude %.6f", md$LON[k]),fc)
           writeLines(sprintf("  :Elevation %.2f", md$ELEV[k]),fc)
-          writeLines(sprintf(":RedirectToFile %s", md$rvt.name[k]),fc)
+          writeLines(sprintf("  :RedirectToFile %s", md$rvt.name[k]),fc)
           writeLines(":EndGauge\n",fc)
         }
-
-        ## Write Redirect commands in stndata file
-        # if(write_redirect) {
-        #   # writeLines("\n",fc)
-        #   # fc.redirect = file(rd_file, open = "a+")
-        #   for(k in 1:nrow(md)){
-        #     writeLines(sprintf(":RedirectToFile %s", md$rvt.name[k]),fc)
-        #   }
-        # }
-
         close(fc)
         message(sprintf("rvn_rvt_write_met: Done writing station data to %s", filename_stndata))
       }

R/rvn_utilities.R

@@ -546,7 +546,6 @@ rvn_fortify_xts <- function(x)
   return(y)
 }
 
-
 #' @title Provide known options for Raven rvi options
 #'
 #' @description
@@ -732,11 +731,19 @@ get_rvt_data_type_mapping <- function() {
     "RESERVOIR_NETINFLOW"=list(
       "units"="m3/s"
     ),
+    "WATER_LEVEL"=list(
+      "units"="m"
+    ),
+    "STREAM_TEMPERATURE"=list(
+      "units"="dC"
+    ),
+    "STREAM_CONCENTRATION"=list(
+      "units"="mg/L"
+    ),
     "SNOW"=list(
       "units"="mm"
     )
   )
-
   return(rvt_data_type_mapping)
 }
 
@@ -798,6 +805,7 @@ get_rvt_met_mapping_weathercan <- function() {
     "TOTAL_SNOW"=list("SNOWFALL"),
     "MAX_TEMP"=list("TEMP_MAX"),
     "MIN_TEMP"=list("TEMP_MIN"),
+    "MEAN_TEMP"=list("TEMP_AVE"),
     "WIND_SPD"=list("WIND_VEL"), # warning on unit conversion
     "REL_HUM"=list("REL_HUMIDITY"),
     "PRECIP_AMT"=list("PRECIP"), # add warning on unit conversion

inst/extdata/RavenAlgParams.dat

@@ -37,6 +37,11 @@ SOILEVAP_HYPR SoilEvaporation PET_CORRECTION SOIL
 SOILEVAP_HYPR SoilEvaporation MAX_DEP_AREA_FRAC LULT
 SOILEVAP_HYPR SoilEvaporation PONDED_EXP LULT
 SOILEVAP_HYPR SoilEvaporation DEP_MAX LULT
+SOILEVAP_HYMOD2 SoilEvaporation HYMOD2_G LULT
+SOILEVAP_HYMOD2 SoilEvaporation HYMOD2_Kmax LULT
+SOILEVAP_HYMOD2 SoilEvaporation HYMOD2_exp LULT
+SOILEVAP_HYMOD2 SoilEvaporation PDM_B  LULT
+SOILEVAP_PDM SoilEvaporation PDM_B  LULT
 
 LAKE_EVAP_BASIC LakeEvaporation LAKE_PET_CORR LULT
 OPEN_WATER_EVAP OpenWaterEvaporation OW_PET_CORR LULT
@@ -152,16 +157,17 @@ ABST_SCS Abstraction SCS_CN LULT
 ABST_SCS Abstraction SCS_IA_FRACTION LULT
 ABST_PDMROF Abstraction PDMROF_B LULT
 ABST_PDMROF Abstraction DEP_MAX LULT
-DFLOW_THRESHPOW DepressionOverflow DEP_THRESHHOLD LULT
+DFLOW_THRESHPOW DepressionOverflow DEP_THRESHOLD LULT
 DFLOW_THRESHPOW DepressionOverflow DEP_N         LULT
 DFLOW_THRESHPOW DepressionOverflow DEP_MAX_FLOW  LULT
 DFLOW_THRESHPOW DepressionOverflow DEP_MAX LULT
-DFLOW_LINEAR DepressionOverflow DEP_THRESHHOLD LULT
+DFLOW_LINEAR DepressionOverflow DEP_THRESHOLD LULT
 DFLOW_LINEAR DepressionOverflow DEP_K          LULT
-DFLOW_WEIR DepressionOverflow DEP_THRESHHOLD LULT
+DFLOW_WEIR DepressionOverflow DEP_THRESHOLD LULT
 DFLOW_WEIR DepressionOverflow DEP_CRESTRATIO LULT
 SEEPAGE_LINEAR Seepage DEP_SEEP_K LULT
 
+
 # JRC: missing GR4J, HMETS, MOHYSE, CONVOLUTION...
 
 ROUTE_DIFFUSIVE_WAVE RoutingMethod MANNINGS_N SUBBASIN