Correctly calculate relative humidity

See DrylandEcology/SOILWAT2#435

1) Updates to rSW2_set_weather_hist() are reflecting the changes in SOILWAT2's read_weather_hist()
* rSW2_set_weather_hist() now uses relativeHumidity1() to calculate relative humidity from vapor pressure -- fixing first part of SOILWAT2 bug #435
* rSW2_set_weather_hist() gained argument "elevation" and now uses relativeHumidity2() to calculate relative humidity from specific humidity inputs and elevation -- fixing second part of bug #435
** the conversion from specific to relative humidity is not exact, the code snaps estimated values within 100-150% to 100% relative humidity (with a warning)

Consequently,
* rSW2_setAllWeather() gained argument "elevation" which is passed to rSW2_set_weather_hist()

* onSet_WTH_DATA() calls rSW2_setAllWeather(): thus, functions that call onSet_WTH_DATA() are now required to previously set "elevation". These are
** rSW_CTL_obtain_inputs() calls onSet_WTH_DATA(): now, obtaining weather data occurs after obtaining "site" data that includes elevation
** rSW2_processAllWeather() calls onSet_WTH_DATA(): now, copies "elevation" from inputData argument to global object that is utilized by onSet_WTH_DATA()
*** dbW_generateWeather() calls rSW2_processAllWeather(): gained argument "elevation"
**** dbW_imputeWeather() calls dbW_generateWeather(): gained argument "elevation"

* rSW2_calc_SiteClimate() calls rSW2_setAllWeather(): gained argument "elevation"
** calc_SiteClimate() calls rSW2_calc_SiteClimate(): gained argument "elevation"

2) SOILWAT2's SW_WTH_read() now passes elevation as argument to readAllWeather(): thus, functions that call SW_WTH_read() are now required to previously set "elevation". These are
* rSW2_readAllWeatherFromDisk() calls SW_WTH_read(): gained argument "elevation"
** getWeatherData_folders() calls rSW2_readAllWeatherFromDisk(): gained argument "elevation"
*** dbW_addWeatherData() calls getWeatherData_folders(): gained argument "elevation"
**** dbW_addFromFolders() calls dbW_addWeatherData(): argument "MetaData" gained new column "elevation"

3) Update "extdata/example1" from SOILWAT2, i.e., "data_weather_maca" was renamed to "data_weather_maca-type1", "data_weather_maca-type2" is a new dataset
* update tests "Weather data sources" to handle new and renamed weather data sources

R/swWeatherGenerator.R

@@ -1129,6 +1129,9 @@ compare_weather <- function(
 #' @inheritParams sw_weather_data
 #' @param years An integer vector. The calendar years for which to generate
 #' daily weather. If `NULL`, then extracted from `weatherData`.
+#' @param elevation A numeric value. Site elevation above sea level `[m]`.
+#'   Used only if specific humidity is provided as input
+#'   for calculating relative humidity.
 #' @param wgen_coeffs A list with two named elements `"mkv_doy"` and
 #' `"mkv_woy"`, i.e., the return value of [dbW_estimate_WGen_coefs()].
 #' If `NULL`, then [dbW_estimate_WGen_coefs()] is called on `weatherData`.
@@ -1210,6 +1213,7 @@ compare_weather <- function(
 dbW_generateWeather <- function(
   weatherData,
   years = NULL,
+  elevation = NA,
   wgen_coeffs = NULL,
   imputation_type = "mean",
   imputation_span = 5L,
@@ -1243,6 +1247,9 @@ dbW_generateWeather <- function(
   swYears_EndYear(sw_in) <- max(years)
   swYears_StartYear(sw_in) <- min(years)
 
+  # Set elevation
+  swSite_IntrinsicSiteParams(sw_in)[3L] <- as.numeric(elevation)
+
   # Turn on weather generator (to fill in missing values)
   swWeather_UseMarkov(sw_in) <- TRUE
   swWeather_UseMarkovOnly(sw_in) <- FALSE
@@ -1371,6 +1378,7 @@ dbW_imputeWeather <- function(
   seed = NULL,
   method_after_wg = c("interp", "locf", "mean", "none", "fail"),
   nmax_run = Inf,
+  elevation = NA,
   return_weatherDF = FALSE
 ) {
 
@@ -1402,6 +1410,7 @@ dbW_imputeWeather <- function(
     #--- Use weather generator for available variables
     tmp <- dbW_generateWeather(
       weatherData = weatherData,
+      elevation = elevation,
       return_weatherDF = TRUE,
       seed = seed
     )

R/sw_Miscellaneous_Functions.R

@@ -20,6 +20,9 @@
 #' @param latitude A numeric value. The latitude in degree of the site. Used
 #'   to adjust seasons between northern/southern hemisphere only if
 #'   \code{isTRUE(do_C4vars)} and \code{simTime2} has to be re-calculated.
+#' @param elevation A numeric value. Site elevation above sea level `[m]`.
+#'   Used only if specific humidity is provided as input
+#'   for calculating relative humidity.
 #'
 #' @return A list with named elements \describe{
 #'   \item{\var{\dQuote{meanMonthlyTempC}}}{A numeric vector of length 12.
@@ -60,7 +63,7 @@
 #' @export
 calc_SiteClimate <- function(weatherList, year.start = NA, year.end = NA,
   do_C4vars = FALSE, do_Cheatgrass_ClimVars = FALSE, simTime2 = NULL,
-  latitude = 90) {
+  latitude = 90, elevation = NA) {
 
       x <- dbW_weatherData_to_dataframe(weatherList)
 
@@ -90,7 +93,8 @@ calc_SiteClimate <- function(weatherList, year.start = NA, year.end = NA,
                    year.end,
                    do_C4vars,
                    do_Cheatgrass_ClimVars,
-                   latitude
+                   latitude,
+                   elevation
       )
 
       res[["dailyTempMin"]] <- if (do_C4vars) x[, "Tmin_C"] else NA

R/sw_dbW_WeatherDatabase.R

@@ -1218,6 +1218,9 @@ dbW_addWeatherDataNoCheck <- function(
 #' @inheritParams sw_weather_database
 #' @inheritParams dbW_getSiteId
 #' @param weatherFolderPath A character string. The path to the parent folder.
+#' @param elevation A numeric value. Site elevation above sea level `[m]`.
+#'   Used only if specific humidity is provided as input
+#'   for calculating relative humidity.
 #' @param overwrite A logical value. Should weather data that already exists
 #' in the data base be overwritten?
 #'
@@ -1236,6 +1239,7 @@ dbW_addWeatherData <- function(
   Scenario_id = NULL,
   Scenario = "Current",
   weather_tag = "weath",
+  elevation = NA,
   ignore.case = FALSE,
   overwrite = FALSE,
   verbose = FALSE
@@ -1304,7 +1308,8 @@ dbW_addWeatherData <- function(
   if (is.null(weatherData)) {
     weatherData <- getWeatherData_folders(
       LookupWeatherFolder = weatherFolderPath,
-      filebasename = weather_tag
+      filebasename = weather_tag,
+      elevation = elevation
     )
   }
 
@@ -1605,7 +1610,8 @@ dbW_createDatabase <- function(
 #'   (in that order) (name of site weather data) `folder`,
 #'   `lat` (site latitude),
 #'   `long` (site longitude),
-#'   `label` (name of site).
+#'   `label` (name of site),
+#'   `elevation` (site elevation).
 #' @param FoldersPath A character string. The path to the folder that contains
 #'   the site weather data folders.
 #' @param ScenarioName A character string. The scenario name represented by
@@ -1635,6 +1641,7 @@ dbW_addFromFolders <- function(
           weatherFolderPath = file.path(FoldersPath, x[1]),
           weatherData = NULL,
           Label = x[4],
+          elevation = if (length(x) >= 5L) x[5L] else NA_real_,
           Scenario = ScenarioName,
           weather_tag = weather_tag
         )
@@ -1946,6 +1953,9 @@ dbW_weatherData_to_blob <- function(weatherData, type = "gzip") {
 #'   see `"weathsetup.in"`.
 #' @param method A character string. `"R"` uses code in `R` to read files as-is
 #'   whereas `"C"` uses `"SOILWAT2"` code to read and process files.
+#' @param elevation A numeric value. Site elevation above sea level `[m]`.
+#'   Used only if specific humidity is provided as input
+#'   for calculating relative humidity.
 #'
 #' @return A list of elements of class \code{\linkS4class{swWeatherData}}.
 #'
@@ -2012,7 +2022,8 @@ getWeatherData_folders <- function(
   startYear = NULL,
   endYear = NULL,
   dailyInputFlags = c(rep(TRUE, 3L), rep(FALSE, 11L)),
-  method = c("R", "C")
+  method = c("R", "C"),
+  elevation = NA
 ) {
 
   method <- match.arg(method)
@@ -2062,6 +2073,7 @@ getWeatherData_folders <- function(
       filebasename,
       used_years[[1L]],
       used_years[[length(used_years)]],
+      elevation,
       dailyInputFlags,
       rSOILWAT2::sw_exampleData
     )