Merge branch 'devel'

.Rprofile

@@ -0,0 +1,4 @@
+require(udunits2)
+require(magrittr)
+require(transformeR)
+sapply(list.files("R", full.names = TRUE), "source", .GlobalEnv)

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: convertR
 Depends:
-    R(>= 3.4.0),
+    R(>= 3.6.0),
     udunits2,
-    transformeR(>= 1.4.2)
+    transformeR(>= 1.7.2)
 Imports:
     magrittr
 Suggests:
@@ -12,19 +12,17 @@ Suggests:
     visualizeR
 Type: Package
 Title: A climate4R Package for Unit Conversion and Variable Derivation
-Version: 0.1.2
-Date: 2018-06-28
-Authors@R: as.person(c(
-    "Santander Meteorology Group <http://meteo.unican.es> [cph]",
-    "Joaquin Bedia <[email protected]> [aut, cre]",
-    "Antonio Cofiño <[email protected]> [ctb]",
-    "Sixto Herrera <[email protected]> [aut]",
-    "Maialen Iturbide <[email protected]> [ctb]"))
+Version: 0.2.0
+Date: 2020-02-22
+Authors@R: c(person("Bedia", "Joaquín", email = "[email protected]", role = c("aut","cre"), comment = c(ORCID = "0000-0001-6219-4312")),
+             person("Cofiño", "Antonio", email = "[email protected]", role = "ctb"),
+             person("Herrera", "Sixto", email = "[email protected]", role = "ctb"),
+             person("Iturbide", "Maialen", email = "[email protected]", role = "ctb"),
+             person("Santander Meteorology Group", comment = "<http://www.meteo.unican.es/en>", role = "cph"))
 BugReports: https://github.com/SantanderMetGroup/convertR/issues
 URL: https://github.com/SantanderMetGroup/convertR
 Encoding: UTF-8
 Description: Implements different variable derivations and unit transformations exploiting the UDUNITS-2 capabilitites for the climate4R CDM (<http://meteo.unican.es/climate4R>).
 License: file LICENSE
 LazyData: true
-RoxygenNote: 6.0.1
-
+RoxygenNote: 6.1.1

NAMESPACE

@@ -1,13 +1,15 @@
 # Generated by roxygen2: do not edit by hand
 
 export(hurs2huss)
+export(hurs2tdps)
 export(hurs2w)
 export(huss2hurs)
 export(huss2pvp)
 export(ps2psl)
 export(psl2ps)
 export(rad2cc)
 export(tas2ws)
+export(tdps2hurs)
 export(udConvertGrid)
 import(transformeR)
 importFrom(magrittr,"%<>%")
@@ -18,3 +20,4 @@ importFrom(udunits2,ud.convert)
 importFrom(udunits2,ud.is.parseable)
 importFrom(utils,globalVariables)
 importFrom(utils,packageDescription)
+importFrom(utils,packageVersion)

NEWS

@@ -19,4 +19,7 @@
  * New derivation functions for pressure reduction:
     * `psl2ps`, to reduce sea-level pressure to surface pressure
     * `ps2psl`, performing the reverse operation
- * Other minor changes and doc updates
+ * Other minor changes and doc updates
+
+## v0.1.3 (in devel)
+ * Add package description attributes to outputs

R/hurs2huss.R

@@ -28,6 +28,7 @@
 #' @import transformeR
 #' @importFrom magrittr %>% %<>% extract2
 #' @importFrom udunits2 ud.are.convertible
+#' @importFrom utils packageVersion
 #' @family derivation
 #' @family humidity
 #' @template templateRefHumidity
@@ -63,6 +64,8 @@ hurs2huss <- function(hurs, ps, tas) {
     attr(huss$Variable, "units") <- "kg/kg"
     attr(huss$Variable, "longname") <- "specific_humidity"
     attr(huss$Variable, "description") <- "The ratio of the mass of water vapor to the total mass of the moist air parcel"
+    attr(huss, "origin") <- paste0("Calculated with R package 'convertR' v", packageVersion("convertR"))
+    attr(huss, "URL") <- "https://github.com/SantanderMetGroup/convertR"
     message("[", Sys.time(), "] Done.")
     invisible(huss)
 }

R/hurs2w.R

@@ -38,6 +38,7 @@
 #' @import transformeR
 #' @importFrom magrittr %>% %<>% extract2
 #' @importFrom udunits2 ud.are.convertible
+#' @importFrom utils packageVersion
 #' @family derivation
 #' @family humidity
 #' @template templateRefHumidity
@@ -91,6 +92,8 @@ hurs2w <- function(ps, tas, hurs) {
     attr(w$Variable, "units") <- "1"
     attr(w$Variable, "longname") <- "humidity_mixing_ratio"
     attr(w$Variable, "description") <- "Humidity mixing ratio of a parcel of moist air is the ratio of the mass of water vapor to the mass of dry air"
+    attr(w, "origin") <- paste0("Calculated with R package 'convertR' v", packageVersion("convertR"))
+    attr(w, "URL") <- "https://github.com/SantanderMetGroup/convertR"
     message("[", Sys.time(), "] Done.")
     invisible(w)
 }

R/huss2hurs.R

@@ -28,6 +28,7 @@
 #' @import transformeR
 #' @importFrom magrittr %>% %<>% extract2
 #' @importFrom udunits2 ud.are.convertible
+#' @importFrom utils packageVersion
 #' @family derivation
 #' @family humidity
 #' @template templateRefHumidity
@@ -84,6 +85,8 @@ huss2hurs <- function(huss, ps, tas) {
     attr(hurs$Variable, "units") <- "%"
     attr(hurs$Variable, "longname") <- "Surface_air_relative_humidity"
     attr(hurs$Variable, "description") <- "Estimated relative humidity from saturation pressure and specific humidity"
+    attr(hurs, "origin") <- paste0("Calculated with R package 'convertR' v", packageVersion("convertR"))
+    attr(hurs, "URL") <- "https://github.com/SantanderMetGroup/convertR"
     message("[", Sys.time(), "] Done.")
     invisible(hurs)
 }

R/huss2pvp.R

@@ -27,6 +27,7 @@
 #' @import transformeR
 #' @importFrom magrittr %>% %<>% extract2
 #' @importFrom udunits2 ud.are.convertible
+#' @importFrom utils packageVersion
 #' @family derivation
 #' @family humidity
 #' @family pressure
@@ -91,6 +92,8 @@ huss2pvp <- function(huss, ps) {
     attr(pvp$Variable, "units") <- "Pa"
     attr(pvp$Variable, "longname") <- "water_vapor_partial_pressure_in_air"
     attr(pvp$Variable, "description") <- "Estimated partial vapour pressure"
+    attr(pvp, "origin") <- paste0("Calculated with R package 'convertR' v", packageVersion("convertR"))
+    attr(pvp, "URL") <- "https://github.com/SantanderMetGroup/convertR"
     message("[", Sys.time(), "] Done.")
     invisible(pvp)
 }

R/ps2psl.R

@@ -30,6 +30,7 @@
 #' @import transformeR
 #' @importFrom magrittr %>% %<>% extract2
 #' @importFrom udunits2 ud.are.convertible
+#' @importFrom utils packageVersion
 #' @family derivation
 #' @family pressure
 #' @examples
@@ -109,6 +110,8 @@ ps2psl <- function(ps, tas, zgs) {
     attr(psl$Variable, "units") <- "Pa"
     attr(psl$Variable, "longname") <- "air_pressure_at_mean_sea_level"
     attr(psl$Variable, "description") <- "Estimated sea-level pressure from pressure at surface"
+    attr(psl, "origin") <- paste0("Calculated with R package 'convertR' v", packageVersion("convertR"))
+    attr(psl, "URL") <- "https://github.com/SantanderMetGroup/convertR"
     message("[", Sys.time(), "] Done.")
     invisible(psl)
 }

R/psl2ps.R

@@ -32,6 +32,7 @@
 #' pressure is usually provided.
 #' @importFrom magrittr %>% %<>% extract2
 #' @importFrom udunits2 ud.are.convertible
+#' @importFrom utils packageVersion
 #' @family derivation
 #' @family pressure
 #' @examples
@@ -112,6 +113,8 @@ psl2ps <- function(psl, tas, zgs) {
     attr(ps$Variable, "units") <- "Pa"
     attr(ps$Variable, "longname") <- "surface_pressure"
     attr(ps$Variable, "description") <- "Estimated surface pressure from sea-level pressure"
+    attr(ps, "origin") <- paste0("Calculated with R package 'convertR' v", packageVersion("convertR"))
+    attr(ps, "URL") <- "https://github.com/SantanderMetGroup/convertR"
     message("[", Sys.time(), "] Done.")
     invisible(ps)
 }

R/rad2cc.R

@@ -29,6 +29,7 @@
 #' @family derivation
 #' @importFrom magrittr %>% %<>% extract2
 #' @importFrom udunits2 ud.are.convertible
+#' @importFrom utils packageVersion
 #' @examples
 #' data("rsds.iberia")
 #' data("rlds.iberia")
@@ -109,6 +110,8 @@ rad2cc <- function(rsds = NULL, rlds = NULL, rtds = NULL) {
     attr(cc$Variable, "units") <- "1"
     attr(cc$Variable, "longname") <- "cloud_area_fraction"
     attr(cc$Variable, "description") <- "Estimated cloud area fraction from radiation"
+    attr(cc, "origin") <- paste0("Calculated with R package 'convertR' v", packageVersion("convertR"))
+    attr(cc, "URL") <- "https://github.com/SantanderMetGroup/convertR"
     message("[", Sys.time(), "] Done.")
     invisible(cc)
 }

R/reducePressure.R

@@ -2,7 +2,7 @@
 #' @description Internal function with formula for presssure reduction
 #' @param p A 2D matrix of (sea-level/surface) pressure values (in Pascals)
 #' @param t A 2D matrix of near-surface temperature (in K)
-#' @param paux Auxiliar grid (one single member, dropped)
+#' @param direction Direction of the conversion, either \code{"ps2psl"} or \code{"psl2ps"}.
 #' @param zgs A matrix of geopotential height (static variable, all rows are equal, in meters)
 #' @return A 2D matrix with reduced pressure data. Need to be reconverted to a grid using \code{\link[transformeR]{mat2Dto3Darray}} afterwards.
 #' @details This function is a internal for the derivation functions \code{\link{ps2psl}} and \code{\link{psl2ps}}.

R/tas2ws.R

@@ -96,6 +96,8 @@ tas2ws <- function(tas, ps) {
     attr(wt$Variable, "units") <- "atm"
     attr(wt$Variable, "longname") <- "water_vapour_saturation_pressure"
     attr(wt$Variable, "description") <- "Estimated water vapour saturation pressure"
+    attr(wt, "origin") <- paste0("Calculated with R package 'convertR' v", packageVersion("convertR"))
+    attr(wt, "URL") <- "https://github.com/SantanderMetGroup/convertR"
     message("[", Sys.time(), "] Done.")
     invisible(wt)
 }

R/tdps2hurs.R

@@ -0,0 +1,167 @@
+##     tdps2hurs.R Relative humidity from Dew-point temperature 
+##
+##     Copyright (C) 2020 Santander Meteorology Group (http://www.meteo.unican.es)
+##
+##     This program is free software: you can redistribute it and/or modify
+##     it under the terms of the GNU General Public License as published by
+##     the Free Software Foundation, either version 3 of the License, or
+##     (at your option) any later version.
+##
+##     This program is distributed in the hope that it will be useful,
+##     but WITHOUT ANY WARRANTY; without even the implied warranty of
+##     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+##     GNU General Public License for more details.
+##
+##     You should have received a copy of the GNU General Public License
+##     along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+#' @title Relative humidity from Dew-point temperature
+#' @description Estimate the Relative humidity from Dew-point temperature and air temperaure
+#' @param tdps Dew-point temperature
+#' @param tas Near-surface air temperature
+#' @param negatives.to.zero Logical flag indicating if estimated negative values should be truncated to zero \%. Default to TRUE.
+#' @return A climate4R CDM grid of estimated relative humidity (in \%)
+#' @author J. Bedia
+#' @template templateUnits
+#' @export
+#' @template templateRefPressure
+#' @import transformeR
+#' @references Lawrence, Mark G., 2005: The relationship between relative humidity and the dewpoint temperature in moist air: A simple conversion and applications. Bull. Amer. Meteor. Soc., 86, 225-233. https://dx.doi.org/10.1175/BAMS-86-2-225 
+#' @importFrom magrittr %>% %<>% extract2
+#' @importFrom udunits2 ud.are.convertible
+#' @importFrom utils packageVersion
+#' @seealso hurs2tdps, performing the inverse calculation to derive dew-point temperature from relative humidity and observed temperature
+#' @note The formula is a valid aproximation for moist air (RH>50\%), but can yield very inaccurate results otherwise, so use it with caution.
+#' @family derivation
+#' @family humidity
+
+tdps2hurs <- function(tdps, tas, negatives.to.zero = TRUE) {
+    stopifnot(is.logical(negatives.to.zero))
+    # Consistency checks:
+    if (isMultigrid(tdps) | isMultigrid(tas)) stop("Multigrids are not an allowed input")
+    stopifnot(isGrid(tdps) | isGrid(tas))
+    # Redim to have members:
+    tdps %<>% redim(member = TRUE)
+    tas %<>% redim(member = TRUE)
+    # Check dim
+    suppressMessages(checkDim(tdps, tas))
+    # Check season
+    checkSeason(tdps, tas)
+    # Check units
+    tdps.u <- getGridUnits(tdps)
+    if (tdps.u != "degC") {
+        if (!ud.are.convertible(tdps.u, "degC")) {
+            stop("Non compliant tdps units (should be convertible to degrees Celsius)")
+        }
+        message("[", Sys.time(), "] Converting temperature units ...")
+        tdps %<>% udConvertGrid(new.units = "degC") %>% redim(member = TRUE)
+    }
+    tas.u <- getGridUnits(tas)
+    if (tas.u != "degC") {
+        if (!ud.are.convertible(tas.u, "degC")) {
+            stop("Non compliant tas units (should be convertible to degrees Celsius)")
+        }
+        message("[", Sys.time(), "] Converting temperature units ...")
+        tas %<>% udConvertGrid(new.units = "degC") %>% redim(member = TRUE)
+    }
+    coords <- getCoordinates(tdps)
+    n.mem <- getShape(tdps, "member")
+    message("[", Sys.time(), "] Deriving relative humidity ...")
+    hurs <- tdps
+    l <- lapply(1:n.mem, function(x) {
+        dp <- subsetGrid(tdps, members = x, drop = TRUE) %>% redim(member = FALSE) %>% extract2("Data") %>% array3Dto2Dmat()
+        t <- subsetGrid(tas, members = x, drop = TRUE) %>% redim(member = FALSE) %>% extract2("Data") %>% array3Dto2Dmat()
+        aux <- 100 - 5*(t - dp)
+        if (isTRUE(negatives.to.zero)) aux[which(aux < 0)] <- 0
+        hurs$Data <- mat2Dto3Darray(aux, coords$x, coords$y)
+        return(hurs)
+    })
+    hurs <- suppressWarnings(bindGrid(l, dimension = "member"))
+    tas <- tdps <- NULL
+    hurs$Variable$varName <- "hurs"
+    hurs$Variable$level <- NULL
+    attr(hurs$Variable, "units") <- "%"
+    attr(hurs$Variable, "longname") <- "near-surface relative humidity"
+    attr(hurs$Variable, "description") <- "Estimated near-surface relative humidity from dew-point temperature and air temperature"
+    attr(hurs, "origin") <- paste0("Calculated with R package 'convertR' v", packageVersion("convertR"))
+    attr(hurs, "URL") <- "https://github.com/SantanderMetGroup/convertR"
+    message("[", Sys.time(), "] Done.")
+    invisible(hurs)
+}
+
+
+
+#' @title Relative humidity from Dew-point temperature
+#' @description Estimate the Relative humidity from Dew-point temperature and air temperaure
+#' @param hurs relative humidity 
+#' @param tas Near-surface air temperature
+#' @return A climate4R CDM grid of estimated dew-point temperature (in degC)
+#' @author J. Bedia
+#' @template templateUnits
+#' @export
+#' @template templateRefPressure
+#' @import transformeR
+#' @references Lawrence, Mark G., 2005: The relationship between relative humidity and the dewpoint temperature in moist air: A simple conversion and applications. Bull. Amer. Meteor. Soc., 86, 225-233. https://dx.doi.org/10.1175/BAMS-86-2-225 
+#' @importFrom magrittr %>% %<>% extract2
+#' @importFrom udunits2 ud.are.convertible
+#' @importFrom utils packageVersion
+#' @seealso tdps2hurs, performing the inverse calculation to derive relative humidity from dew-point temperature and observed temperature
+#' @note The formula is a valid aproximation for moist air (RH>50\%), but can yield very inaccurate results otherwise, so use it with caution.
+#' @family derivation
+#' @family humidity
+
+hurs2tdps <- function(hurs, tas) {
+    # Consistency checks:
+    if (isMultigrid(hurs) | isMultigrid(tas)) stop("Multigrids are not an allowed input")
+    stopifnot(isGrid(hurs) | isGrid(tas))
+    # Redim to have members:
+    hurs %<>% redim(member = TRUE)
+    tas %<>% redim(member = TRUE)
+    # Check dim
+    suppressMessages(checkDim(hurs, tas))
+    # Check season
+    checkSeason(hurs, tas)
+    # Check units
+    hurs.u <- getGridUnits(hurs)
+    if (hurs.u != "%") {
+        if (!ud.are.convertible(hurs.u, "%")) {
+            stop("Non compliant hurs units (should be convertible to %)")
+        }
+        message("[", Sys.time(), "] Converting relative humidity units ...")
+        hurs %<>% udConvertGrid(new.units = "%") %>% redim(member = TRUE)
+    }
+    tas.u <- getGridUnits(tas)
+    if (tas.u != "degC") {
+        if (!ud.are.convertible(tas.u, "degC")) {
+            stop("Non compliant tas units (should be convertible to degrees Celsius)")
+        }
+        message("[", Sys.time(), "] Converting temperature units ...")
+        tas %<>% udConvertGrid(new.units = "degC") %>% redim(member = TRUE)
+    }
+    coords <- getCoordinates(hurs)
+    n.mem <- getShape(hurs, "member")
+    message("[", Sys.time(), "] Deriving dew-point temperature ...")
+    tdps <- hurs
+    l <- lapply(1:n.mem, function(x) {
+        rh <- subsetGrid(hurs, members = x, drop = TRUE) %>% redim(member = FALSE) %>% extract2("Data") %>% array3Dto2Dmat()
+        t <- subsetGrid(tas, members = x, drop = TRUE) %>% redim(member = FALSE) %>% extract2("Data") %>% array3Dto2Dmat()
+        aux <- t - ((100 - rh) / 5)
+        # if (isTRUE(negatives.to.zero)) aux[which(aux < 0)] <- 0
+        tdps$Data <- mat2Dto3Darray(aux, coords$x, coords$y)
+        return(tdps)
+    })
+    tdps <- suppressWarnings(bindGrid(l, dimension = "member"))
+    tas <- hurs <- NULL
+    tdps$Variable$varName <- "tdps"
+    tdps$Variable$level <- NULL
+    attr(tdps$Variable, "units") <- "degC"
+    attr(tdps$Variable, "longname") <- "dewpoint temperature"
+    attr(tdps$Variable, "description") <- "Estimated dewpoint temperature from relative humidity and air temperature"
+    attr(tdps, "origin") <- paste0("Calculated with R package 'convertR' v", packageVersion("convertR"))
+    attr(tdps, "URL") <- "https://github.com/SantanderMetGroup/convertR"
+    message("[", Sys.time(), "] Done.")
+    invisible(tdps)
+}
+
+